CompanyFin REST API: Endpunkte, Authentifizierung und Beispiele

Mit der REST API lesen eigene Systeme, Skripte und BI-Werkzeuge Daten aus CompanyFin und legen Belege, Buchungsentwürfe und Zuordnungsvorschläge an. Diese Seite zeigt den Zugang Schritt für Schritt und beschreibt jeden Endpunkt. Für KI-Agenten gibt es die separate MCP-Dokumentation.

Das Wichtigste in Kürze
Die REST API hat zwei Teile: eine lesende API v1 unter /api/v1/public/ (Kennzahlen, Konten, Transaktionen, Belege, Berichte) und eine schreibende API v2 unter /api/v2/ (Belege hochladen, Buchungsentwürfe, Zuordnungsvorschläge).
Die Anmeldung erfolgt mit einem API-Schlüssel im Header X-API-Key oder Authorization: Bearer. Der Schlüssel wird im Pro-Tarif unter Einstellungen → API und MCP erstellt.
Die lesende API braucht nur Lese-Scopes. Die schreibende API braucht zusätzlich eine Integration, ein Ablaufdatum (höchstens 180 Tage) und einen Idempotency-Key je Anfrage.
Alles, was Ihr System über die API anlegt, ist ein unverbindlicher Entwurf: wirksam wird es erst durch Ihre Freigabe in der App.
Ein KI-Agent verbindet sich besser über MCP. Diese Seite richtet sich an eigene Software und Skripte.

1. Überblick

Die API ist über HTTPS erreichbar und sendet und empfängt JSON (der Beleg-Upload nutzt multipart/form-data). Basis-URL:

Basis-URL
https://app.companyfin.de
TeilPfadZweckVoraussetzung am Schlüssel
API v1 (lesend)/api/v1/public/…Kennzahlen, Bankkonten, Kontenplan, Transaktionen, Belege, Berichte abrufenLese-Scopes
API v2 (schreibend)/api/v2/…Belege hochladen, Buchungsentwürfe und Zuordnungsvorschläge anlegenSchreib-Scopes, Integration, Ablaufdatum

Eine interaktive OpenAPI-Oberfläche (Swagger) gibt es im Produktivsystem nicht. Diese Seite ist die Referenz.

2. Zugang einrichten

Der Zugang ist ein API-Schlüssel, den nur Sie erstellen und jederzeit widerrufen können. Voraussetzung ist der Pro-Tarif.

  1. Einstellungen öffnen: Melden Sie sich unter app.companyfin.de an und öffnen Sie Einstellungen → API und MCP.
  2. Nur lesen (API v1): Erstellen Sie einen Schlüssel mit der Vertrauensstufe Lesen. Er enthält alle Lese-Scopes und braucht keine Integration.
  3. Auch schreiben (API v2): Legen Sie im Bereich Integrationen eine Integration an, zum Beispiel „ERP-Anbindung“. Erstellen Sie dann einen Schlüssel mit dieser Integration, den passenden Scopes (siehe Tabelle unten) und einem Ablaufdatum von höchstens 180 Tagen. Die Stufe Zuarbeiten enthält die Scopes für Entwürfe und Vorschläge; write:receipts für den Beleg-Upload der API v2 vergeben Sie einzeln unter „Individuell“.
  4. Schlüssel kopieren: Der Schlüssel beginnt mit cf_live_ und wird nur einmal angezeigt. Legen Sie ihn in einem Secret-Speicher oder einer Umgebungsvariable ab, nie im Quellcode.
ScopeEndpunkteEnthalten in Stufe
read:kpisGET /api/v1/public/kpis/summaryLesen
read:analyticsGET /api/v1/public/kpis/analyticsLesen
read:accountsGET /api/v1/public/accounts/…Lesen
read:transactionsGET /api/v1/public/transactions…Lesen
read:receiptsGET /api/v1/public/receiptsLesen
read:reportsGET /api/v1/public/reports/…Lesen
write:receiptsPOST /api/v2/receipts und …/processingeinzeln vergeben
read:booking-draftsGET /api/v2/booking-drafts…Zuarbeiten
write:booking-draftsPOST und PATCH /api/v2/booking-drafts…Zuarbeiten
read:match-proposalsGET /api/v2/match-proposals…Zuarbeiten
write:match-proposalsPOST /api/v2/match-proposals…Zuarbeiten

Bei Schlüsseln, die über MCP genutzt werden, kommt der Scope read:mcp hinzu; für die REST API ist er nicht nötig.

3. Authentifizierung und erster Aufruf

Senden Sie den Schlüssel bei jeder Anfrage in einem der beiden Header. Beide sind gleichwertig:

Header
X-API-Key: cf_live_…
Authorization: Bearer cf_live_…

Cookies und Browser-Sitzungen werden von der API bewusst nicht akzeptiert. Rufen Sie die API daher nicht direkt aus Browser-Code Ihrer Webseite auf, sondern von einem Server aus, damit der Schlüssel nie öffentlich wird.

Erster Aufruf: Bankkonten lesen

curl
export COMPANYFIN_API_KEY="cf_live_…"

curl -s https://app.companyfin.de/api/v1/public/accounts/bank-accounts \
  -H "X-API-Key: $COMPANYFIN_API_KEY"

Eine erfolgreiche Antwort (HTTP 200) sieht so aus (Auszug, Beispielwerte):

Antwort
{
  "bank_accounts": [
    {
      "name": "Geschäftskonto",
      "bank_name": "Beispielbank",
      "iban_masked": "••••••••3000",
      "currency": "EUR",
      "current_balance": 18250.40,
      "is_active": true,
      "last_synced_at": "2026-11-18T06:12:44"
    }
  ]
}

Dasselbe in Python:

Python (requests)
import os
import requests

BASE = "https://app.companyfin.de"
HEADERS = {"X-API-Key": os.environ["COMPANYFIN_API_KEY"]}

response = requests.get(f"{BASE}/api/v1/public/transactions",
                        headers=HEADERS,
                        params={"start_date": "2026-10-01", "end_date": "2026-10-31", "limit": 100},
                        timeout=30)
response.raise_for_status()
data = response.json()
print(data["total"], "Transaktionen")

Liefert der erste Aufruf 401 oder 403, helfen die Fehlercodes in Abschnitt 8.

4. Konventionen: Beträge, Seiten, Fehler

  • Beträge: Bei der API v1 liefern Transaktionen, Belege und Konten Beträge als JSON-Zahl, die Berichte als String mit zwei Nachkommastellen ("119.00"). Bei der API v2 sind Beträge immer Strings mit Punkt als Dezimaltrenner; derzeit ist nur EUR zulässig. Rechnen Sie mit Beträgen in Ihrem System nicht mit Gleitkommazahlen, sondern mit einem Dezimaltyp.
  • Datum: JJJJ-MM-TT (ISO 8601), zum Beispiel 2026-10-31.
  • Seiten: Listen mit limit und offset (Standard 50, höchstens 500 bei API v1). Die Transaktionsliste liefert zusätzlich total. Die Listen der API v2 liefern bis zu 100 Einträge.
  • Strikte Eingaben: Die API v2 lehnt unbekannte Felder im JSON mit 422 ab. Tippfehler fallen so sofort auf.
  • Fehler: Fehlerantworten enthalten das Feld detail mit einer deutschen Meldung, die den Grund nennt.
  • Mandanten: Eine Organisation gibt es nicht als Parameter. Jeder Schlüssel ist fest an eine Organisation gebunden, ein Zugriff auf fremde Daten ist ausgeschlossen.

5. Lesende API v1

Alle Endpunkte sind GET und ändern nichts. Der Schlüssel braucht den jeweils genannten Scope. Die Berichte und Kennzahlen berechnen große Datenmengen; senden Sie diese Aufrufe nacheinander, nicht parallel.

Kennzahlen und Analysen

GET/api/v1/public/kpis/summaryread:kpis

Alle Kennzahlen des Dashboards, netto ohne Umsatzsteuer und abgestimmt mit GuV, Bilanz und Startup-P&L: Erträge, Aufwände, Ergebnis, Umsatzrendite, Kontostand, Burn Rate und Runway, Eigenkapital, Eigenkapitalquote, offene Belege, Abstimmungsquote, Vorsteuer, Umsatzsteuer und Zahllast. Nicht ermittelbare Kennzahlen sind null; bei EÜR-Organisationen sind Bilanzkennzahlen null.

  • start_date, end_date: optional: Zeitraum (JJJJ-MM-TT); ohne Angabe die gesamte Historie

GET/api/v1/public/kpis/analyticsread:analytics

Monatliche Zeitreihen (Erträge, Aufwände, Ergebnis, Umsatzsteuer und Vorsteuer, netto) und die Verteilung der Ausgaben nach Konten und Kategorien.

  • start_date, end_date: optional: Zeitraum (JJJJ-MM-TT)

Bankkonten und Kontenplan

GET/api/v1/public/accounts/bank-accountsread:accounts

Alle Bankkonten der Organisation mit Name, Bank, IBAN (auch maskiert als iban_masked), BIC, Währung, aktuellem Saldo, Kontotyp, Status und Zeitpunkt der letzten Synchronisation. Antwort: {"bank_accounts": [...]}.

GET/api/v1/public/accounts/chart-of-accountsread:accounts

Der Kontenplan (Systemkonten plus eigene Konten) mit Salden. Soll positiv, nur bestätigte Buchungen, netto; Umsatzsteuer auf den Steuerkonten. Die id eines Kontos wird für Buchungsentwürfe (API v2) benötigt. Antwort: {"accounts": [...]}.

  • account_class: optional: Kontenklasse 0 bis 9

Transaktionen

GET/api/v1/public/transactionsread:transactions

Paginierte Banktransaktionen, neueste zuerst. Antwort: total, limit, offset und transactions mit id, bank_account_id, booking_date, value_date, amount, currency, partner_name, partner_iban, purpose, match_status und created_at.

  • start_date, end_date: optional: Buchungsdatum von/bis
  • min_amount, max_amount: optional: Betragsspanne
  • match_status: optional: matched, unmatched oder suggested
  • q: optional: Volltextsuche in Name, Verwendungszweck und Empfänger
  • limit: optional: 1 bis 500, Standard 50
  • offset: optional: Standard 0

GET/api/v1/public/transactions/{transaction_id}read:transactions

Eine Transaktion mit den verknüpften Belegen (linked_receipts mit Lieferant, Datum, Betrag, Zuordnungsscore) und der Buchung (booking mit Soll-/Habenkonto, Steuerschlüssel und Status). 404, wenn die Transaktion nicht existiert oder nicht zu Ihrer Organisation gehört.

  • transaction_id: Pfad: ID der Transaktion

Belege

GET/api/v1/public/receiptsread:receipts

Belege und Rechnungen mit OCR- und Umsatzsteuerfeldern, Positionen, verknüpften Transaktionen und Buchungssätzen. Die Antwort enthält immer die vollständige strukturierte Extraktion.

  • receipt_id: optional: genau ein Beleg
  • q: optional: Suche in Lieferant, Kunde, Rechnungsnummer, Dateiname, Kategorie und Notizen
  • start_date, end_date: optional: Belegdatum von/bis
  • min_amount, max_amount: optional: Bruttobetrag von/bis
  • receipt_type: optional: incoming, outgoing, unknown oder other; mehrere Werte kommagetrennt
  • ocr_status: optional: pending, processing, success, review_needed oder error; mehrere kommagetrennt
  • match_status: optional: unmatched, matched oder confirmed; mehrere kommagetrennt
  • vendor_name, invoice_number: optional: enthält-Filter
  • limit: optional: 1 bis 500, Standard 50
  • offset: optional: Standard 0

Berichte (vorläufig)

GET/api/v1/public/reports/balance-sheetread:reports

Vorläufige Bilanz nach § 266 HGB zum Stichtag, vor Abschlussbuchungen. Nur für bilanzierende Organisationen, bei EÜR 409.

  • as_of: optional: Stichtag (JJJJ-MM-TT), Standard heute

GET/api/v1/public/reports/income-statementread:reports

Vorläufige GuV nach § 275 Abs. 2 HGB (Gesamtkostenverfahren). Nur für bilanzierende Organisationen, bei EÜR 409. Liegt from nach to, antwortet die API mit 422.

  • from: Pflicht: Beginn (JJJJ-MM-TT)
  • to: Pflicht: Ende (JJJJ-MM-TT)

GET/api/v1/public/reports/euerread:reports

Vorläufige Einnahmenüberschussrechnung eines Kalenderjahres. Nur für EÜR-Organisationen (cash_basis), bei Bilanzierung 409.

  • year: optional: 2000 bis 2100, Standard laufendes Jahr

GET/api/v1/public/reports/vat-returnread:reports

Vorläufige Umsatzsteuer-Voranmeldung eines Monats oder Quartals: Kennzahlen, Zahllast, Fälligkeit und offene Vorgänge. Es wird nichts an das Finanzamt übermittelt. Für Kleinunternehmer 409.

  • year: Pflicht: 2000 bis 2100
  • period: Pflicht: 01 bis 12 oder Q1 bis Q4

Beispiel: Transaktionsliste

Anfrage
curl -s "https://app.companyfin.de/api/v1/public/transactions?start_date=2026-10-01&end_date=2026-10-31&match_status=unmatched&limit=2" \
  -H "X-API-Key: $COMPANYFIN_API_KEY"
Antwort (Auswahl der Felder, Beispielwerte)
{
  "total": 7,
  "limit": 2,
  "offset": 0,
  "transactions": [
    {
      "id": 4711,
      "booking_date": "2026-10-14",
      "amount": -119.0,
      "currency": "EUR",
      "partner_name": "Beispiel Hosting GmbH",
      "purpose": "Rechnung 2026-1042",
      "match_status": "unmatched"
    }
  ]
}

6. Schreibende API v2

Die API v2 legt Belege, Buchungsentwürfe und Zuordnungsvorschläge an. Jeder Aufruf, der etwas anlegt oder ändert, braucht einen Idempotency-Key (siehe Abschnitt 8). Der Schlüssel muss an eine Integration gebunden sein; Entwürfe, Vorschläge und Belege sind nur für die Integration sichtbar, die sie angelegt hat.

Belege

POST/api/v2/receiptswrite:receipts

Lädt eine Rechnung oder einen Beleg hoch (PDF, Bild oder XRechnung/ZUGFeRD-XML) als multipart/form-data. CompanyFin liest den Beleg per OCR. Der Beleg wird als Entwurf angelegt: Er wird gelesen, aber nicht automatisch zugeordnet oder gebucht. Antwort 202 mit receipt_id, status „pending“ und processing_url. Wurde dieselbe Datei schon eingereicht, antwortet die API mit 409.

  • file: Pflicht (multipart): die Belegdatei. Es gilt das Upload-Limit der App.
  • Idempotency-Key: Pflicht (Header)

GET/api/v2/receipts/{receipt_id}/processingwrite:receipts

Verarbeitungsstand eines über diese Integration eingereichten Belegs: status (pending, processing, completed, review_needed, failed), error_code und updated_at. Belege anderer Integrationen sind nicht sichtbar (404).

  • receipt_id: Pfad: ID des Belegs

Buchungsentwürfe

POST/api/v2/booking-draftswrite:booking-drafts

Legt einen Buchungsentwurf an. Er bestätigt oder exportiert nichts und wartet in der Arbeitsliste, bis Sie ihn in der App freigeben. Antwort 201 mit dem Entwurf (Status „draft“, Version 1). Eigene Konten-IDs stammen aus dem Kontenplan (API v1), Steuerschlüssel stehen im Abschnitt 7.

  • booking_date: Pflicht: Buchungsdatum (JJJJ-MM-TT)
  • description: Pflicht: 1 bis 500 Zeichen; was wird gebucht und auf welcher Grundlage
  • lines: Pflicht: 1 bis 20 Zeilen mit debit_account_id, credit_account_id, amount {amount, currency}, optional tax_key (Standard „ohne“), tax_amount, invoice_number
  • receipt_id, transaction_id: optional: Verknüpfung mit Beleg bzw. Transaktion
  • Idempotency-Key: Pflicht (Header)

GET/api/v2/booking-draftsread:booking-drafts

Listet die Entwürfe dieser Integration, neueste zuerst. Entwürfe anderer Integrationen sind nicht sichtbar.

  • limit: optional: 1 bis 100, Standard 25

GET/api/v2/booking-drafts/{package_id}read:booking-drafts

Ein Entwurf dieser Integration mit Version und Zeilen. Die Version wird für Änderungen benötigt.

  • package_id: Pfad: ID des Entwurfs

PATCH/api/v2/booking-drafts/{package_id}write:booking-drafts

Ändert einen offenen Entwurf mit optimistischer Versionsprüfung. Wurde der Entwurf inzwischen geändert oder ist er nicht mehr offen, antwortet die API mit 409.

  • expected_version: Pflicht: Version, auf der Ihre Änderung beruht
  • booking_date, description, lines: mindestens eines davon; lines ersetzt die Zeilen vollständig
  • Idempotency-Key: Pflicht (Header)

Zuordnungsvorschläge

POST/api/v2/match-proposalswrite:match-proposals

Legt einen unverbindlichen Vorschlag an, welcher Beleg zu welcher Transaktion gehört. Es entsteht weder eine wirksame Verknüpfung noch eine Buchung; Sie entscheiden in der App. Antwort 201.

  • transaction_id, receipt_id: Pflicht: IDs der Transaktion und des Belegs
  • rationale: optional: Begründung, höchstens 1000 Zeichen
  • proposed_amount: optional: {amount, currency}, wenn nur ein Teilbetrag gemeint ist
  • Idempotency-Key: Pflicht (Header)

GET/api/v2/match-proposalsread:match-proposals

Listet die Vorschläge dieser Integration. status ist pending, withdrawn, accepted oder rejected.

  • limit: optional: 1 bis 100, Standard 25

GET/api/v2/match-proposals/{proposal_id}read:match-proposals

Ein Vorschlag dieser Integration mit Status und Version.

  • proposal_id: Pfad: ID des Vorschlags

POST/api/v2/match-proposals/{proposal_id}/withdrawwrite:match-proposals

Zieht einen eigenen, noch offenen Vorschlag zurück (Versionsprüfung).

  • expected_version: Pflicht: aktuelle Version des Vorschlags
  • Idempotency-Key: Pflicht (Header)

Steuerschlüssel für Entwurfszeilen

tax_keyBedeutungamount / tax_amount
ohneKeine Umsatzsteuer (Standard)tax_amount 0
VSt19, VSt7Vorsteuer 19 % bzw. 7 %Betrag brutto, tax_amount = enthaltene Steuer
USt19, USt7Umsatzsteuer 19 % bzw. 7 %Betrag brutto, tax_amount = enthaltene Steuer
RC19, RC7, RC19DSteuerschuld des Leistungsempfängers, § 13b UStGBetrag netto, tax_amount = geschuldete Steuer
IGE19, IGE7Innergemeinschaftlicher ErwerbBetrag netto, tax_amount = geschuldete Steuer

Bei RC… und IGE… braucht derselbe Entwurf zusätzlich die Steuerzeile ohne Schlüssel. Die Prüfung bei der Freigabe nennt, was fehlt. Besprechen Sie solche Fälle mit Ihrer Steuerberatung.

7. Beispiel-Abläufe

Beleg hochladen und Status abfragen

Der Upload nutzt multipart/form-data. Verwenden Sie pro Datei immer denselben Idempotency-Key, damit ein Wiederholungsversuch nichts doppelt anlegt.

curl
curl -s -X POST https://app.companyfin.de/api/v2/receipts \
  -H "X-API-Key: $COMPANYFIN_API_KEY" \
  -H "Idempotency-Key: rechnung-2026-1042.pdf" \
  -F "file=@rechnung-2026-1042.pdf"
Antwort (HTTP 202)
{
  "receipt_id": 812,
  "status": "pending",
  "processing_url": "/api/v2/receipts/812/processing"
}
Status abfragen
curl -s https://app.companyfin.de/api/v2/receipts/812/processing \
  -H "X-API-Key: $COMPANYFIN_API_KEY"

# {"receipt_id": 812, "status": "completed", "error_code": null, "updated_at": "2026-11-18T08:03:11"}

Fragen Sie den Status im Abstand weniger Sekunden ab, bis er completed, review_needed oder failed lautet. Bei review_needed braucht der Beleg Ihre Prüfung in der App.

Buchungsentwurf anlegen und ändern

Entwurf anlegen (HTTP 201)
curl -s -X POST https://app.companyfin.de/api/v2/booking-drafts \
  -H "X-API-Key: $COMPANYFIN_API_KEY" \
  -H "Idempotency-Key: abschluss-2026-rueckstellung" \
  -H "Content-Type: application/json" \
  -d '{
    "booking_date": "2026-12-31",
    "description": "Rückstellung Abschlusskosten 2026 gemäß Angebot vom 12.11.2026",
    "lines": [
      {
        "debit_account_id": 101,
        "credit_account_id": 202,
        "amount": { "amount": "1500.00", "currency": "EUR" },
        "tax_key": "ohne"
      }
    ]
  }'

Die Konten-IDs im Beispiel sind Platzhalter; die echten IDs liefert GET /api/v1/public/accounts/chart-of-accounts. Die Antwort enthält den Entwurf:

Antwort (Auswahl der Felder)
{
  "id": 3305,
  "booking_date": "2026-12-31",
  "status": "draft",
  "version": 1,
  "source": "public_api",
  "lines": [
    {
      "debit_account_id": 101,
      "credit_account_id": 202,
      "amount": { "amount": "1500.00", "currency": "EUR" },
      "tax_key": "ohne",
      "tax_amount": "0.00"
    }
  ]
}

Eine Änderung gibt die Version an, auf der sie beruht:

Entwurf ändern
curl -s -X PATCH https://app.companyfin.de/api/v2/booking-drafts/3305 \
  -H "X-API-Key: $COMPANYFIN_API_KEY" \
  -H "Idempotency-Key: abschluss-2026-rueckstellung-v2" \
  -H "Content-Type: application/json" \
  -d '{ "expected_version": 1, "description": "Rückstellung Abschlusskosten 2026 (Angebot vom 12.11.2026, 1.500 EUR)" }'

Freigeben können Sie den Entwurf in der App. Er erscheint in Ihrer Arbeitsliste unter „Braucht Sie“.

Zuordnungsvorschlag anlegen

curl
curl -s -X POST https://app.companyfin.de/api/v2/match-proposals \
  -H "X-API-Key: $COMPANYFIN_API_KEY" \
  -H "Idempotency-Key: match-812-4711" \
  -H "Content-Type: application/json" \
  -d '{ "transaction_id": 4711, "receipt_id": 812, "rationale": "Betrag, Datum und Rechnungsnummer stimmen überein" }'

Der Vorschlag erscheint mit Status pending und wartet auf Ihre Entscheidung. Ziehen Sie ihn bei Bedarf mit POST /api/v2/match-proposals/{id}/withdraw zurück.

8. Idempotenz, Limits und Fehlercodes

Idempotency-Key

Jede schreibende Anfrage der API v2 verlangt den Header Idempotency-Key (höchstens 255 Zeichen). Er verhindert Doppelbuchungen bei Wiederholungen nach einem Netzwerkfehler:

  • Gleicher Key, gleicher Inhalt: Sie erhalten die ursprüngliche Antwort zurück; es wird nichts doppelt angelegt.
  • Gleicher Key, anderer Inhalt: 409. Verwenden Sie für eine neue Aktion einen neuen Key.
  • Gleicher Key, erste Anfrage läuft noch: 409 mit Retry-After: 2. Wiederholen Sie die Anfrage nach der angegebenen Zeit.
  • Keys gelten je Integration und Vorgang. Ein stabiler Key pro Datei oder Aktion, etwa aus Dateiname oder Belegnummer abgeleitet, ist ideal.

Limits

  • Anfragen: derzeit 120 pro Minute und Schlüssel (Antwort 429 bei Überschreitung).
  • Berichte und Kennzahlen: Kennzahlen-, Analyse-, Bericht- und Kontenplan-Endpunkte laufen höchstens zu zweit. Bei Auslastung antwortet die API mit 503 und Retry-After.
  • Belegdateien: Es gilt das Upload-Limit der App; PDF, Bilder und XRechnung/ZUGFeRD-XML werden geprüft.

Fehlercodes

CodeBedeutungLösung
401Header fehlt, Schlüssel ungültig, deaktiviert oder abgelaufen.X-API-Key bzw. Authorization prüfen; Schlüssel in den Einstellungen kontrollieren.
403Kein Pro-Tarif, fehlender Scope oder bei API v2 ein Schlüssel ohne Integration.Tarif, Scopes und Integration des Schlüssels prüfen.
404Objekt existiert nicht, gehört nicht zu Ihrer Organisation oder (API v2) nicht zu Ihrer Integration.ID prüfen.
409Konflikt: bereits eingereichter Beleg, veraltete Version, nicht mehr offener Entwurf, Idempotency-Key mit anderem Inhalt, Bericht passt nicht zur Buchführungsart.Objekt neu lesen und mit aktueller Version wiederholen.
400 / 413Beleg-Upload: Datei leer, kein erlaubtes Belegformat, ungültiges PDF oder XML (400); Datei zu groß (413).Das Feld detail nennt den Grund.
422Ungültige Eingabe: Datum, Betrag, Konto, unbekanntes Feld, fehlender oder zu langer Idempotency-Key.Das Feld detail nennt den Grund.
429Zu viele Anfragen (derzeit 120 pro Minute und Schlüssel).Anfragen drosseln und nach kurzer Pause wiederholen.
503Server ausgelastet: Berichts- und Kennzahlen-Endpunkte laufen höchstens zu zweit. Die Antwort enthält Retry-After.Nach der angegebenen Zeit erneut versuchen und Berichts-Aufrufe nacheinander senden.

9. Sicherheit

  • Mandanten-Isolation: Der Schlüssel ist fest an Ihre Organisation gebunden. Ein Zugriff auf fremde Mandantendaten ist unmöglich.
  • Geringste Rechte: Vergeben Sie pro Anwendung einen eigenen Schlüssel mit nur den nötigen Scopes. So lässt sich ein Zugang einzeln sperren.
  • Befristet: Schlüssel mit Schreibrechten laufen spätestens nach 180 Tagen ab. Planen Sie die Erneuerung ein.
  • Schlüssel geheim halten: Nicht im Quellcode, in Repositories oder in Browser-Code ablegen. Der Schlüssel wird nur einmal angezeigt und bei uns nur als Hash gespeichert. Bei Verdacht auf Missbrauch sperren Sie ihn im Dashboard mit einem Klick.
  • Nachvollziehbar: Jede schreibende Aktion wird mit Schlüssel, Integration und Herkunft im Auditprotokoll gespeichert.
  • Unverbindlich: Über die API angelegte Belege, Entwürfe und Vorschläge werden erst durch Ihre Freigabe in der App wirksam. Exportieren, Perioden abschließen und endgültiges Löschen sind über die API nicht möglich.

Fachlich geprüft durch die CompanyFin Finanzredaktion

Dieser Beitrag wurde nach den aktuellen Vorgaben des Handelsgesetzbuchs (HGB), der Abgabenordnung (AO) und den GoBD redaktionell und steuerfachlich verfasst. Letzte redaktionelle Prüfung: 18. November 2026.

Häufig gestellte Fragen (FAQ)

Im Produktivsystem ist die interaktive OpenAPI-Oberfläche aus Sicherheitsgründen abgeschaltet. Diese Dokumentation beschreibt alle Endpunkte, Parameter und Antworten.

Nein. Die schreibende API legt Belege, Buchungsentwürfe und Zuordnungsvorschläge an. Diese sind unverbindlich und werden erst durch Ihre Freigabe in der App wirksam. Exportieren, Perioden abschließen und endgültiges Löschen sind über die API nicht möglich.

Beide nutzen denselben API-Schlüssel und dieselben Scopes. MCP ist für KI-Agenten gedacht und bietet zusätzlich Entscheidungs-Tools (z. B. Zahlungen zuordnen) mit Vertrauensstufen. Die REST API ist für eigene Systeme gedacht: lesend über v1, schreibend über v2 mit unverbindlichen Entwürfen.

Häufige Gründe: Die Organisation ist nicht im Pro-Tarif, dem Schlüssel fehlt der Scope für den Endpunkt, oder ein Endpunkt der API v2 wird mit einem Schlüssel ohne Integration aufgerufen. Die Fehlermeldung im Feld detail nennt den Grund.

Die REST API ist in allen Pro- und Enterprise-Plänen von CompanyFin ohne zusätzliche Gebühr enthalten. In der Testphase ist sie nicht verfügbar.

Buchhaltung ohne Frust und Medienbrüche

CompanyFin verknüpft Bankkonten, Beleg-OCR und den SKR04-Kontenrahmen. Erzeugen Sie fertige DATEV-Stapel mit Belegbildern auf Knopfdruck.

Passende Ratgeber & Dokumentationen