API-Referenz

prekonto ist headless benutzbar: Stammdaten hinterlegen, Rechnungen einliefern, Buchungsvorschläge lesen und korrigieren, DATEV-Buchungsstapel ziehen — alles über eine REST-API. Diese Seite beschreibt sie vollständig. Maßgeblich ist immer das Maschinendokument unter /api/v1/openapi.json.

Grundlagen: Basis-URL, Formate, Mandantenscope

Basis-URL ist https://prekonto.de, alle Pfade beginnen mit /api/v1. Die Version steigt nur bei Brüchen; ein /api/v2 wäre ein zweiter Pfad und keine stille Änderung an diesem.

• Geld ist immer Integer-Cent. Felder tragen dafür das Suffix Cent — umsatzCent: 142800 sind 1.428,00 Euro. Es gibt keine Fließkommabeträge in dieser API.
• Kalendertage sind YYYY-MM-DD, Zeitpunkte ISO-8601 mit Zeitzone.
• Mandantenscope: Jeder fachliche Pfad trägt eine Mandanten-ID, und jede Abfrage filtert auf das Konto des Credentials. Ein Mandant eines anderen Kontos ergibt 404, nicht 403 — fremde Existenz wird nicht bestätigt.
• Fehler tragen neben dem deutschen error-Text ein stabiles, maschinenlesbares code-Feld. Auf code darf ein Client sich verlassen, auf den Text nicht.

Authentifizierung: API-Key oder OAuth 2.0

Beide Wege laufen über denselben Header: Authorization: Bearer …. Am Präfix des Werts entscheidet der Server, worum es sich handelt — ein unbekanntes Präfix wird abgewiesen, ohne dass überhaupt in der Datenbank gesucht wird.

API-Key — für eigene Skripte und Server

Ein API-Key beginnt mit pk_live_. Angelegt wird er im angemeldeten Bereich unter API-Keys (Seite „API-Zugänge“); dort werden auch die Scopes angehakt, die der Key tragen soll. Der Klartext erscheint genau einmal, direkt nach dem Anlegen: gespeichert wird nur sein SHA-256-Hash. Verloren heißt neu erzeugen, nicht nachschauen. Widerrufen ist ein Zeitstempel und kein Löschen — die Frage, wer wann mit welchem Key zugegriffen hat, bleibt beantwortbar. Pro Konto sind höchstens 20 aktive Keys erlaubt.

curl https://prekonto.de/api/v1 \
  -H "Authorization: Bearer pk_live_…"

GET /api/v1 ist der Endpunkt, mit dem man einen Key prüft: Er kostet nichts und antwortet mit den effektiven Scopes des Credentials. Ein 200 heißt „der Key trägt“.

OAuth 2.0 mit PKCE — für Anwendungen fremder Nutzer

Wer eine Anwendung baut, die im Namen eines prekonto-Nutzers arbeitet, nimmt OAuth. Unterstützt wird ausschließlich der Authorization-Code-Flow, PKCE ist Pflicht und nur S256 erlaubt — plain wird abgelehnt, weil es nichts schützt. Redirect-URIs werden exakt verglichen, ohne Wildcards. Codes sind einmalig, Refresh-Tokens rotieren.

Ein OAuth-Client wird ebenfalls unter API-Keys registriert — mit Name und Redirect-URIs. Vertrauliche Clients (etwa eine Server-Integration) bekommen zusätzlich ein client_secret mit Präfix pcs_, öffentliche Clients (native Apps, MCP-Clients) weisen sich allein über PKCE aus.

401 und 403 sind sauber getrennt: 401 heißt „weise dich (anders) aus“, 403 heißt „dein Credential trägt, darf das aber nicht“ und nennt in fehlendeScopes genau die Scopes, die fehlen. Wer beides vermischt, lässt Clients endlos neue Tokens holen, die genauso wenig dürfen.

Scopes und was sie erlauben

Fünf Scopes, bewusst grob und an den vier Anwendungsfällen orientiert. Feingranulare Rechte, die niemand versteht, führen in der Praxis dazu, dass alle alles anhaken.

Zwei Eigenheiten, die man kennen muss. invoices:write enthält kein Leserecht — ein Dienst, der nur Belege einliefert, muss die Buchungsvorschläge nicht sehen können. Und Webhook-Abos hängen an stammdaten:write: Ein Abo ist eine Konfigurationsänderung am Mandanten, kein Lesevorgang.

Meldet sich die eigene Oberfläche mit ihrem Session-Cookie an, trägt sie alle Scopes. Das ist kein Loch: Scopes begrenzen, was ein Nutzer einer fremden Anwendung erlaubt — ihn am eigenen Konto zusätzlich einzuschränken würde nur die eigene Oberfläche kaputtmachen.

Alle Endpunkte

Gruppiert wie in der Spec. Die Scope-Spalte gibt die security-Angabe der jeweiligen Operation wieder. „Jeder Scope“ heißt: jedes gültige Credential genügt — ohne Mandantenliste geht kein einziger anderer Aufruf, ein eigener Scope dafür hätte niemanden geschützt.

Die operationId ist der Name, unter dem generierte Clients eine Operation führen. Sie ist deshalb stabil: Ein Umbenennen wäre für jeden generierten Client ein Bruch, auch wenn sich am Pfad nichts ändert.

Der Hauptfluss mit curl

Sechs Schritte, von der leeren Mandantenakte bis zur DATEV-Datei. Der Key in den Beispielen braucht alle fünf Scopes.

0. Credential prüfen und Mandanten-ID holen

export PK="pk_live_…"

curl -s https://prekonto.de/api/v1 -H "Authorization: Bearer $PK"

curl -s https://prekonto.de/api/v1/mandanten \
  -H "Authorization: Bearer $PK"
# → { "mandanten": [ { "id": "…", "name": "Muster GmbH", … } ] }

export M="<mandanten-uuid>"

1. Stammdaten hochladen (Kreditoren, dann Gegenkonten)

# DATEV-KRexport-Datei: wird am Dateinamen bzw. an der Header-Signatur
# erkannt und ohne Sprachmodell geparst.
curl -s -X PUT "https://prekonto.de/api/v1/mandanten/$M/kreditoren" \
  -H "Authorization: Bearer $PK" \
  -F "file=@KRExport_KRED_12345_20260101.csv"

curl -s -X PUT "https://prekonto.de/api/v1/mandanten/$M/gegenkonten" \
  -H "Authorization: Bearer $PK" \
  -F "file=@KRExport_KTO_12345_20260101.csv"

# Wer die Liste schon strukturiert hat, schickt JSON statt einer Datei:
curl -s -X PUT "https://prekonto.de/api/v1/mandanten/$M/gegenkonten" \
  -H "Authorization: Bearer $PK" \
  -H "Content-Type: application/json" \
  -d '{"saetze":[
        {"kontoNr":"4930","bezeichnung":"Bürobedarf","erwarteterSteuersatz":19},
        {"kontoNr":"4980","bezeichnung":"Sonstiger Betriebsbedarf"}
      ]}'

Die Antwort ist ein Importbericht: format nennt das erkannte Quellformat, deterministisch: true heißt „ohne KI geparst“, und bericht.duplikate listet die Konten, die nicht angefasst wurden, weil ein Mensch sie gepflegt hat.

2. Rechnung einreichen

curl -s -X POST "https://prekonto.de/api/v1/mandanten/$M/invoices" \
  -H "Authorization: Bearer $PK" \
  -F "file=@rechnung.pdf"
# → 202
# { "invoiceId": "…", "status": "neu",
#   "statusUrl": "/api/v1/mandanten/…/invoices/…" }

export INV="<invoice-uuid>"

3. Status abfragen

curl -s "https://prekonto.de/api/v1/mandanten/$M/invoices/$INV" \
  -H "Authorization: Bearer $PK"
# status: "neu"        → läuft noch, in einigen Sekunden erneut fragen
#         "kontiert"   → fertig, buchungssatz steht in der Antwort
#         "fehler"     → Grund im Feld fehler

Wer nicht pollen will, abonniert invoice.processed (siehe Webhooks).

4. Buchungssätze lesen, korrigieren, bestätigen

# Was braucht einen Menschen?
curl -s "https://prekonto.de/api/v1/mandanten/$M/buchungssaetze?status=review" \
  -H "Authorization: Bearer $PK"

export SATZ="<satz-uuid>"

# Gegenkonto korrigieren (gültige Werte über listGegenkonten)
curl -s -X PATCH \
  "https://prekonto.de/api/v1/mandanten/$M/buchungssaetze/$SATZ" \
  -H "Authorization: Bearer $PK" \
  -H "Content-Type: application/json" \
  -d '{"gegenkonto":"4930"}'

# Vorschlag stimmt: unverändert freigeben
curl -s -X POST \
  "https://prekonto.de/api/v1/mandanten/$M/buchungssaetze/$SATZ/bestaetigen" \
  -H "Authorization: Bearer $PK"

Korrigieren und Bestätigen sind zwei Handlungen und deshalb zwei Aufrufe. Der PATCH sagt „das ist falsch, so ist es richtig“, der zweite Aufruf sagt „der Vorschlag stimmt“. Der Unterschied landet in korrigiertVonUser und ist die Grundlage der Qualitätsmessung; eine API, die beides über einen Aufruf abbildet, macht die Fälle im Nachhinein ununterscheidbar. Für Programme gibt es den Ein-Schritt-Weg trotzdem: {"gegenkonto":"4930","status":"bestaetigt"} korrigiert und gibt frei. Die Antwort trägt dann zusätzlich lernen — das Ergebnis der Lern-Regel.

5. Export ziehen und herunterladen

curl -s -X POST "https://prekonto.de/api/v1/mandanten/$M/exports" \
  -H "Authorization: Bearer $PK" \
  -H "Content-Type: application/json" \
  -d '{"zeitraumVon":"2026-07-01","zeitraumBis":"2026-07-31"}'
# → 201 { "id": "…", "dateiname": "EXTF_….csv", "anzahlBuchungen": 42,
#         "summeCent": 1234500, "warnungen": [],
#         "downloadUrl": "/api/v1/mandanten/…/exports/…/download" }

export BATCH="<batch-uuid>"

# Wichtig: --output, kein Umkodieren. Die Datei ist ISO-8859-1.
curl -s "https://prekonto.de/api/v1/mandanten/$M/exports/$BATCH/download" \
  -H "Authorization: Bearer $PK" \
  --output EXTF_Juli-2026.csv

Der Zeitraum darf das Wirtschaftsjahr des Mandanten nicht überschreiten: Das Belegdatum trägt im EXTF-Format kein Jahr, DATEV leitet es aus dem Header ab. Ein Stapel über die Wirtschaftsjahr-Grenze wäre nicht auflösbar — deshalb antwortet die API mit 422 zeitraum_ausserhalb_wirtschaftsjahr statt eine Datei zu erzeugen, die später im DATEV-Import scheitert. Mehr dazu in der Doku zum DATEV-Export.

Fehler: die Statuscode-Regel

Die Statuscodes folgen einer Regel, auf die man sich verlassen kann. Das Unterscheidungskriterium ist die Handlung, die ein Code verlangt — nicht die Stelle, an der die Prüfung sitzt. Ob eine Ablehnung aus einem Schema oder aus einer Datenbankabfrage kommt, ist für den Aufrufer ein Implementierungsdetail.

Der Unterschied zwischen 400 und 422 ist damit operativ: Bei 400 ist der Request falsch gebaut, bei 422 ist er richtig gebaut und passt nicht zu diesem Mandanten. Ein Retry hilft im zweiten Fall nie.

Maschinenlesbare Codes

Fachliche Ablehnungen tragen zusätzlich einen code. Kriterium für einen eigenen Code ist das Gegenmittel des Clients: Wo eine Anwendung eine Auswahlliste anbieten kann — kreditor_unbekannt, gegenkonto_unbekannt — gibt es einen eigenen Code; wo nichts anzubieten ist, bleibt es buchung_ungueltig mit Einzelmeldungen in probleme.

Bei Authentifizierungsfehlern gelten zusätzlich auth_required (401, gar kein Credential), invalid_token (401, Credential unbekannt, widerrufen oder abgelaufen) und insufficient_scope (403, mit fehlendeScopes).

Webhooks: Events, Signatur, Retry

Ein Webhook erspart das Pollen. prekonto meldet sich, wenn ein Beleg durch die Pipeline ist. Angelegt wird ein Abo mit einer https-URL und mindestens einem Event; die Antwort enthält einmalig das Secret, mit dem signiert wird.

Abo anlegen

curl -s -X POST "https://prekonto.de/api/v1/mandanten/$M/webhooks" \
  -H "Authorization: Bearer $PK" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.org/haken",
       "events":["invoice.processed","buchungssatz.review_needed"]}'
# → 201 { "id": "…", "secret": "…", … }   ← das Secret gibt es nur hier

Die drei Ereignisse

Dass invoice.processed auch bei status: "fehler" herausgeht, ist Absicht: Ein Empfänger, der nur Erfolge erfährt, kann einen hängenden Beleg nicht von einem gescheiterten unterscheiden und müsste doch pollen — genau das sollen Webhooks ersparen.

Nutzlast und Header

{
  "id": "…",                       // Event-ID, für Idempotenz beim Empfänger
  "event": "invoice.processed",
  "mandantId": "…",
  "zeitpunkt": "2026-08-06T09:12:44.000Z",
  "daten": { "invoiceId": "…", "status": "kontiert",
             "buchungssatzId": "…", "buchungssatzStatus": "review" }
}

Signatur prüfen

// Node.js / Express — rohen Körper behalten, nicht geparst signieren
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/haken",
  express.raw({ type: "application/json" }),   // req.body ist ein Buffer
  (req, res) => {
    const erwartet =
      "sha256=" +
      createHmac("sha256", process.env.PREKONTO_WEBHOOK_SECRET)
        .update(req.body)                       // die Rohbytes
        .digest("hex");
    const gegeben = req.header("X-Prekonto-Signature") ?? "";

    const a = Buffer.from(erwartet, "utf8");
    const b = Buffer.from(gegeben, "utf8");
    if (a.length !== b.length || !timingSafeEqual(a, b)) {
      return res.status(401).end();             // 4xx: wird NICHT wiederholt
    }

    const ereignis = JSON.parse(req.body.toString("utf8"));
    // Sofort quittieren, dann selbst weiterarbeiten — das Zeitlimit ist 10 s.
    res.status(202).end();
    verarbeite(ereignis);                        // eigene Warteschlange
  }
);

Zustellversuche

• Zeitlimit je Versuch: 10 Sekunden. Der Empfänger soll quittieren, nicht verarbeiten — wer länger braucht, antwortet 202 und arbeitet selbst weiter.
• Höchstens drei Versuche: der erste, dann nach 1 Sekunde und nach 5 Sekunden.
• Wiederholt wird nur, wo eine Wiederholung Sinn hat: Netzwerkfehler, Zeitüberschreitung, 5xx und 429. Ein 4xx außer 429 wird nicht wiederholt — ein 401 oder 404 ist beim dritten Mal genauso 401.
• Nach 20 aufeinanderfolgenden Fehlversuchen wird das Abo stillgelegt und muss neu angelegt werden. Ohne diese Grenze zahlt jeder Beleg die Timeouts einer URL mit, die es nicht mehr gibt.
• Eine gescheiterte Zustellung lässt niemals die auslösende Handlung scheitern. Ein Webhook ist eine Benachrichtigung, kein Teil der Transaktion.

Das Zustellziel wird zweimal geprüft: beim Anlegen des Abos (sonst 400 url_nicht_erlaubt) und erneut unmittelbar vor jeder Zustellung. Das ist keine Doppelung — der DNS-Eintrag gehört dem Empfänger, und ein Hostname, der gestern öffentlich auflöste, kann heute auf eine interne Adresse zeigen. Zugestellt wird nur an öffentlich erreichbare Ziele; ein verbotenes Ziel wird nicht wiederholt, weil es kein vorübergehender Zustand ist.

MCP-Server

Unter POST /api/v1/mcp liegt ein Model-Context-Protocol-Server: derselbe Funktionsumfang, aber als Werkzeuge für KI-Clients statt als REST-Aufrufe. Er benutzt dieselbe Fachschicht und dieselbe Authentifizierung. Elf Werkzeuge, ihre Scopes, die Einbindung in Claude und die Grenzen stehen auf der MCP-Seite.

Grenzen und Obergrenzen

Nicht über die API möglich: einen Mandanten anlegen (die DATEV-Kopfdaten sind eine Angabe des Steuerberaters und werden in der Oberfläche erfasst) und Kreditoren automatisch erzeugen. Wer auf ein Konto korrigiert, zu dem es keinen Kreditor gibt, bekommt 422 kreditor_unbekannt — die Kreditorenliste gehört dem Mandanten, nicht dem Zufall eines Belegs.