Erste Schritte

Nordlet ist eine API-first Buchhaltungsplattform für den EU-/EWR-Markt, die mit vollständiger litauischer Compliance startet. Alle Funktionen des Produkts - Rechnungsstellung, Hauptbuch, Bankabgleich, i.SAF - stehen über eine einzige JSON-API zur Verfügung.

1. Einen API-Schlüssel abrufen

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

Authorization: Bearer nl_...

Für die lokale Entwicklung lässt sich ein Unternehmen samt Schlüssel per Bootstrap einrichten:

pnpm --filter @nordlet/db bootstrap:dev     # leeres Unternehmen
pnpm --filter @nordlet/api seed:demo        # Unternehmen mit Demodaten

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 fertige Collection - jeder Endpunkt, gruppiert nach Modul, mit voreingestellter Bearer-Authentifizierung: Nordlet Postman collection. Nach dem Importieren setzen Sie die Variable bearerToken der Collection auf Ihren API-Schlüssel, und jede Anfrage wird authentifiziert.

Sandbox-Unternehmen

Für Integrationstests erstellen Sie ein Unternehmen mit isSandbox: true (POST /v1/account/companies/create oder durch Setzen des Sandbox-Häkchens während des Onboardings in der App). Ein Sandbox-Unternehmen verhält sich exakt wie ein reales Unternehmen - dieselben Module, dieselbe API, sodass Sie realistische Transaktionsvolumina darüber abwickeln können -, ist jedoch deutlich als Testdaten gekennzeichnet, und beim Löschen werden alle Daten sofort und nicht erst nach Ablauf der 10-tägigen Aufbewahrungsfrist bereinigt. Sie können beliebig viele Sandbox-Unternehmen parallel zu Ihrem echten Unternehmen unter demselben Account betreiben; das Kennzeichen kann nach der Erstellung nicht mehr geändert werden, sodass reale Buchhaltungssdaten niemals unbemerkt als Testdaten reklassifiziert werden können. Die Nutzung in einem Sandbox-Unternehmen wird exakt wie die Nutzung in einem echten Unternehmen gemessen und abgerechnet: Anfragen, Seiten für das Dokumentenscannen, Speicherplatz und die Reaktivierungsgebühr.

2. Erste Aufrufe

Jeder Vorgang erfolgt als POST /v1/{module}/{resource}/{action} mit einem JSON-Body. So legen Sie einen Geschäftspartner an:

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

So stellen Sie eine Rechnung aus (Beträge sind Dezimalstrings, niemals Gleitkommazahlen):

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

Durch die Ausstellung wird eine lückenlose Nummer (SF-1) vergeben, geprüft, ob die Abrechnungsperiode geöffnet ist, und der ausgeglichene Buchungssatz (S 2410 Forderungen / H 5001 Umsatzerlöse / H 4492 USt) im Rahmen derselben Transaktion verbucht.

3. Der vollständige Zyklus

Schritt	Aufruf
Buchhaltung aus einem Altsystem übernehmen	migration/books/validate → migration/books/import - siehe Migration aus einem anderen System
Eingangsrechnung erfassen	purchases/invoices/create → purchases/invoices/register
Kontoauszug importieren	bank/statements/import (camt.053 XML) oder bank/transactions/import (JSON)
Abgleichvorschläge abrufen	bank/transactions/suggest-matches
Zahlung abgleichen	bank/transactions/match - verbucht die Zahlung und aktualisiert den paymentStatus
Lieferanten bezahlen	bank/payments/export - pain.001 SEPA-Datei für Ihre Bank
Monatliche USt-Register	declarations/lt/isaf/generate - i.SAF 1.2 XML für die VMI
USt-Voranmeldungsdaten	declarations/lt/fr0600/compute - FR0600-Felder abgeglichen mit den Registern
Waren mit Lieferschein versenden	transport/waybills/create → issue, danach declarations/lt/ivaz/generate - i.VAZ XML für die 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 diese abzufragen (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"]}'

Lieferungen enthalten eine mit Zeitstempel versehene HMAC-Signatur (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> über <timestamp>.<raw body> mit Ihrem Abonnement-Secret) neben der ursprünglichen x-nordlet-signature: sha256=<hex> des unveränderten Body und werden etwa 24 Stunden lang wiederholt zugestellt. Informationen zum Wiederholungsfenster finden Sie unter API-Konventionen.

Jeder Zustellungs-Body hat das Format { id, version, companyId, eventType, createdAt, data }: version ist die Version des Envelopes (aktuell 1) und companyId ist das Unternehmen, zu dem das Ereignis gehört, sodass ein einzelner Empfänger mehrere Unternehmen bedienen kann. Das Abonnieren eines Namens, der nicht in der Liste unten aufgeführt ist, wird mit dem Status 400 abgelehnt; verwenden Sie "*" für alle Ereignisse. Wenn 5 Ereignisse in Folge nicht zugestellt werden können, wird das Abonnement pausiert und die Unternehmensinhaber erhalten eine E-Mail. Sie können das Abonnement unter Einstellungen → Webhooks oder über webhooks/subscriptions/update mit isActive: true wieder aktivieren.

Ereignisse: agreement.invoice_generated, bank_feed.synced, 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, 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_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. Das OpenAPI-Dokument listet die einzelnen Ereignisse unter x-webhooks auf.

Informationen zu Listabfragen, Fehler-Envelopes, Idempotenz-Semantik und Rate Limits finden Sie unter API-Konventionen.