REST API — Einführung

Die LedgerLou REST API bietet direkten, deterministischen Zugriff auf das GoBD-konforme Hauptbuch. Alle Endpunkte sind scope-geschützt, Append-Only-sicher und vollständig auditiert.

Basis-URL

https://api.ledgerlou.com

Alle Endpunkte beginnen mit /v1/. Der vollständige Pfad einer Anfrage lautet daher zum Beispiel https://api.ledgerlou.com/v1/journal/bookings.

Authentifizierung

Jede Anfrage muss einen gültigen API-Key im Authorization-Header enthalten:

Authorization: Bearer ll_<ihr-api-key>

API-Keys beginnen immer mit dem Präfix ll_ und werden im Dashboard unter Einstellungen → API-Keys ausgestellt. Anfragen ohne gültigen Key werden mit 401 Unauthorized abgelehnt.

curl https://api.ledgerlou.com/v1/journal/bookings \
  -H "Authorization: Bearer ll_abc123..."

await fetch('/v1/journal/bookings', {
  headers: {
    Authorization: `Bearer ${apiKey}`
  }
});

Scopes

Jeder API-Key trägt eine Liste von Scopes im Format modul:aktion. Ohne den passenden Scope liefert der Server 403 Forbidden — unabhängig davon, ob der Key gültig ist.

Für jeden Endpunkt zeigt diese Referenz neben dem Method-Badge, welcher Scope erforderlich ist. Detaillierte Scope-Tabelle: Auth & Scopes.

Query-Parameter

GET-Endpunkte akzeptieren Filter- und Paginierungsparameter als URL-Query-String. Parameter werden mit ? eingeleitet und mit & verkettet:

GET /v1/journal/bookings?from=2026-01-01&to=2026-01-31&limit=50

Werte müssen URL-kodiert sein. Zeichenketten mit Sonderzeichen (zum Beispiel Leerzeichen in Suchbegriffen) werden mit encodeURIComponent() kodiert:

GET /v1/accounts/search?q=Vorsteuer%2019%25

Antwortformat

Alle Antworten sind JSON. Erfolgreiche Anfragen liefern den HTTP-Statuscode 200 (oder 201 für neu erstellte Ressourcen). Fehler folgen diesem Format:

{
  "error": "Kurze Fehlerbeschreibung",
  "details": [ ... ]  // optional, bei Validierungsfehlern
}

Rate-Limiting

Standardlimit: 300 Anfragen pro Minute pro API-Key. Auth-Endpunkte (Login, Token) sind auf 10 Anfragen pro Minute begrenzt. Bei Überschreitung: 429 Too Many Requests mit Header Retry-After.