Schnittstelle

Die Bücher eines Betriebs lesen und Buchungsentwürfe vorbereiten, aus einem eigenen Programm, einer Tabelle oder einem KI-Werkzeug. Eine Adresse, ein Token, JSON.

Gebucht, bezahlt, eingereicht und abgeschlossen wird nicht über die Schnittstelle. Ein Programm bereitet vor; entschieden wird im Arbeitsbereich von einem Menschen. Das ist keine fehlende Funktion, sondern die Linie, an der dieses Produkt gebaut ist.

In drei Schritten

Token holen. Im Arbeitsbereich unter Einstellungen › Schnittstelle: Name vergeben, ankreuzen was es darf, Gültigkeit wählen. Der Schlüssel wird einmal angezeigt und nirgends gespeichert.
Aufruf machen. Das Token als Authorization: Bearer …mitschicken. Mehr Kopfzeilen braucht es beim Lesen nicht.
Dranbleiben. Läuft es in einem KI-Werkzeug, nimm den MCP-Endpunkt weiter unten. Dieselben Aufrufe, als Werkzeuge.

curl -s https://bilanzi.ch/api/v1/invoices \
  -H "Authorization: Bearer $BILANZI_TOKEN"

Was es gibt

Jedes Token gehört zu genau einem Betrieb; eine Kennung des Betriebs steht deshalb in keinem Weg. Beträge sind Zeichenketten mit zwei Nachkommastellen, Daten sind ISO-8601, und gelistet wird in Seiten zu höchstens hundert Zeilen: ?limit=50&after=…, wobei after die Kennung aus nextAfter der letzten Antwort ist.

Aufruf	Was er tut	Geltungsbereich
`GET /api/v1/entity`	Den Betrieb lesen, zu dem das Token gehört: Name, Rechtsform, Währung.	`entity:read`
`GET /api/v1/accounts`	Den Kontenplan lesen.	`ledger:read`
`GET /api/v1/ledger`	Gebuchte Buchungen mit ihren Zeilen lesen.	`ledger:read`
`GET /api/v1/contacts`	Kunden und Lieferanten lesen.	`contacts:read`
`GET /api/v1/invoices`	Ausgangsrechnungen mit Stand und offenem Betrag lesen.	`invoices:read`
`GET /api/v1/documents`	Belege auflisten: Name, Typ, Grösse, Prüfsumme, Herkunft. Ohne Lohnbelege, und ohne die Datei selbst.	`documents:read`
`POST /api/v1/booking-drafts`	Einen Buchungsentwurf vorbereiten. Gebucht wird er nicht: das entscheidet ein Mensch im Arbeitsbereich.	`booking-drafts:write`

Die vollständige Beschreibung als OpenAPI 3.1 steht unter /api/v1/openapi.json. Daraus erzeugst du dir einen Client, ohne hier abzuschreiben.

Einen Entwurf anlegen

Der einzige schreibende Aufruf. Er verlangt einen Idempotency-Key: ein Wiederholversuch nach einer abgebrochenen Verbindung gibt dieselbe Antwort zurück statt ein zweites Mal anzulegen. Derselbe Schlüssel mit anderem Inhalt ist ein Fehler, kein zweiter Entwurf.

curl -s -X POST https://bilanzi.ch/api/v1/booking-drafts \
  -H "Authorization: Bearer $BILANZI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rechnung-4711" \
  -d '{
    "postingDate": "2026-09-12",
    "currency": "CHF",
    "sourceReference": "RE-4711",
    "description": "Telefonrechnung September",
    "lines": [
      { "accountId": "…", "side": "debit",  "amount": "48.00" },
      { "accountId": "…", "side": "credit", "amount": "48.00" }
    ]
  }'

Soll und Haben müssen aufgehen, die Konten zum Betrieb gehören und die Währung die des Betriebs sein. Danach liegt der Entwurf im Arbeitsbereich unter Mehr › Entwürfe, wo ihn jemand prüft und bucht.

Für KI-Werkzeuge: MCP

Derselbe Zugang spricht das Model Context Protocol über HTTP. In Claude Desktop, Claude Code, Cursor oder einem anderen Werkzeug mit MCP-Unterstützung trägst du ein:

{
  "mcpServers": {
    "bilanzi": {
      "type": "http",
      "url": "https://bilanzi.ch/api/mcp",
      "headers": { "Authorization": "Bearer BLZ_TOKEN_HIER" }
    }
  }
}

Danach kennt das Werkzeug die Werkzeuge bilanzi_entity_get, bilanzi_accounts_list, bilanzi_ledger_list, bilanzi_contacts_list, bilanzi_invoices_list, bilanzi_documents_list und bilanzi_booking_draft_create, und es sieht nur die, für die dein Token einen Geltungsbereich hat.

Wenn etwas schiefgeht

Jeder Fehler ist ein JSON-Objekt mit error.code und error.message. Der Code ist für dein Programm, der Satz für dich.

Status	Code	Heisst
401	`authorization_required`, `api_token_invalid`	Kein Token mitgeschickt, oder es ist zurückgezogen oder abgelaufen.
403	`api_scope_missing`	Das Token darf diesen Aufruf nicht. Neues Token mit dem Häkchen erstellen.
429	`api_rate_limited`	Mehr als 120 Aufrufe in einer Minute mit demselben Token. Die Antwort trägt `Retry-After`; wer sich daran hält, kommt gleich wieder durch.
409	`idempotency_conflict`	Derselbe Schlüssel wurde schon mit einem anderen Inhalt benutzt.
422	`journal_unbalanced`, `account_unavailable`	Der Entwurf geht nicht auf oder nennt ein fremdes Konto.

Grenzen, ehrlich genannt

Kein Schreiben ausser Entwürfen. Buchen, Zahlungen auslösen, Lohn rechnen, MWST einreichen und abschliessen bleibt beim Menschen.
Kein Lohn. Personendaten gehen nicht über diese Schnittstelle, auch nicht lesend. Belege, die als Lohnbelege gekennzeichnet sind, erscheinen deshalb in /documents gar nicht: der Filter steht in der Datenbank, nicht im Aufruf.
Belege ohne Datei. /documents nennt Name, Typ, Grösse, Prüfsumme und Herkunft eines Belegs, gibt aber weder die Datei noch ihren Ablageort heraus. Die Datei holst du im Arbeitsbereich.
Ein Betrieb je Token. Wer mehrere Betriebe anbindet, erstellt mehrere Token.
Ein Jahr höchstens. Danach läuft ein Token ab und wird ersetzt.
120 Aufrufe je Minute und Token. Reichlich für eine Tabelle, die stündlich Zahlen holt, und für ein KI-Werkzeug; wenig für eine Schleife ohne Abbruch. Darüber kommt 429 mit Retry-After.