API-Dokumentation · Version 1

Rechnungen aus Ihren eigenen Systemen

Die REST-API spricht JSON, Beträge kommen als ganze Cent in Feldern mit der Endung Cents, Mengen und Preise als Dezimalzahlen in Zeichenketten, Datumswerte als YYYY-MM-DD. Basis-URL:

https://app.billingsuite.de/api/v1

Inhalt

01Authentifizierung
02Erste Rechnung per API
03MCP-Server
04CLI
05Peppol
06Fehlercodes

Alle Endpunkte

01Authentifizierung

Jede Anfrage braucht einen API-Schlüssel im Header Authorization: Bearer bs_live_…. Schlüssel erstellen Inhaber und Administratoren unter API und MCP. Der Schlüssel wird nur einmal angezeigt.

Recht	Erlaubt
read	Alle GET-Endpunkte
write	Entwürfe, Kunden, Produkte, Zahlungen anlegen und ändern
finalize	Abschließen und Stornieren (vergibt Nummern, unumkehrbar)
send	Versand per E-Mail und Peppol

Pro Schlüssel sind 120 Anfragen pro Minute erlaubt. Jede Antwort enthält X-Request-Id. POST-Anfragen, die etwas anlegen, akzeptieren Idempotency-Key: eine Wiederholung mit gleichem Schlüssel liefert dieselbe Antwort mit Idempotent-Replayed: true, statt doppelt anzulegen.

02Erste Rechnung per API

Vier Schritte: Kunde anlegen, Entwurf anlegen, abschließen, PDF laden. Der Entwurf lässt sich jederzeit in der App prüfen, bevor er eine Nummer bekommt.

1. Kunden anlegen

Anfrage

curl https://app.billingsuite.de/api/v1/customers \
  -H "Authorization: Bearer $BILLINGSUITE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a4e-kunde-brandt" \
  -d '{
    "kind": "company",
    "companyName": "Brandt Gebäudetechnik GmbH",
    "email": "buchhaltung@brandt-gt.de",
    "vatId": "DE318274650",
    "billingAddress": {
      "street": "Habsburgerstraße", "houseNumber": "12",
      "zip": "79104", "city": "Freiburg im Breisgau", "country": "DE"
    }
  }'

2. Rechnungsentwurf anlegen

Anfrage

curl https://app.billingsuite.de/api/v1/documents \
  -H "Authorization: Bearer $BILLINGSUITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "customerId": "c0a8012e-5b1f-4c7a-9d3e-2f6b8a1c4d90",
    "serviceDate": "2026-10-24",
    "items": [
      { "description": "Montage Empfangstresen", "quantity": "6", "unit": "HUR",
        "unitPriceNet": "78.00", "taxRate": "19" },
      { "description": "Eichenplatte geölt, 2,4 m", "quantity": "1", "unit": "C62",
        "unitPriceNet": "1240.00", "taxRate": "19" }
    ]
  }'

Antwort 201

{
  "id": "4b7e9c02-1d3a-4f55-8e21-6a0c9b3d7f18",
  "type": "invoice",
  "status": "draft",
  "number": null,
  "netCents": 170800,
  "taxCents": 32452,
  "grossCents": 203252,
  "currency": "EUR",
  "appUrl": "https://app.billingsuite.de/dokumente/4b7e9c02-1d3a-4f55-8e21-6a0c9b3d7f18"
}

Einheiten folgen UN/ECE Recommendation 20 (HUR Stunde, C62 Stück). Steuerfall, Zahlungsziel und Texte kommen aus den Einstellungen und dem Kunden, wenn Sie sie nicht mitschicken.

3. Abschließen und 4. PDF laden

Anfrage

curl -X POST https://app.billingsuite.de/api/v1/documents/4b7e9c02-1d3a-4f55-8e21-6a0c9b3d7f18/finalize \
  -H "Authorization: Bearer $BILLINGSUITE_API_KEY"

# Antwort: { "status": "finalized", "number": "RE-2026-0075", ... }

curl https://app.billingsuite.de/api/v1/documents/4b7e9c02-1d3a-4f55-8e21-6a0c9b3d7f18/pdf \
  -H "Authorization: Bearer $BILLINGSUITE_API_KEY" -o RE-2026-0075.pdf

Das PDF ist eine ZUGFeRD-Rechnung (EN 16931). Für Behörden liefert /xml?format=xrechnung_cii die XRechnung.

03MCP-Server

Der MCP-Server unter https://app.billingsuite.de/api/mcp verbindet KI-Assistenten mit Ihrem Unternehmen. Er nutzt denselben API-Schlüssel und dieselben Rechte. Assistenten legen immer Entwürfe an; finalize_document und send_document verlangen confirm: true und Ihre ausdrückliche Anweisung.

{
  "mcpServers": {
    "billingsuite": {
      "url": "https://app.billingsuite.de/api/mcp",
      "headers": { "Authorization": "Bearer bs_live_…" }
    }
  }
}

Beispiel für eine Anweisung: „Lege für Brandt Gebäudetechnik eine Rechnung über 6 Stunden Montage zu 78 Euro an und zeig mir den Entwurf.“

04CLI

Die Kommandozeile billingsuite nutzt die REST-API. Sie liest den Schlüssel aus BILLINGSUITE_API_KEY oder aus der Konfiguration, die billingsuite login anlegt. Exit-Codes: 0 erfolgreich, 1 Fehler der API, 2 falsche Eingabe.

Installation

npm install -g @billingsuite/cli
billingsuite login

Beispiele

# Offene Rechnungen anzeigen
billingsuite documents list --type invoice --status overdue

# Rechnung als Entwurf anlegen (Beschreibung;Menge;Einheit;Preis;USt)
billingsuite documents create --type invoice --customer K-10023 \
  --item "Montage Empfangstresen;6;Std.;78;19" \
  --item "Eichenplatte geölt, 2,4 m;1;Stk.;1240;19"

# Abschließen, versenden, PDF speichern
billingsuite documents finalize RE-2026-0075
billingsuite documents send RE-2026-0075
billingsuite documents pdf RE-2026-0075 --out RE-2026-0075.pdf

# Zahlung erfassen
billingsuite payments record RE-2026-0075 --amount 1951.32

05Peppol

POST /documents/{id}/peppol erzeugt eine UBL-Datei nach Peppol BIS Billing 3.0. Empfänger-Schema und ID kommen aus der Peppol-ID am Kunden, zum Beispiel 0204:991-12345-67. Derzeit wird die Datei exportiert; ein Access Point ist nicht angebunden. Nach dem Hochladen bei Ihrem Dienstleister markieren Sie die Rechnung als versendet.

06Fehlercodes

Fehler haben immer dieselbe Form. Bei 401 ist die Antwort für fehlende, falsche und widerrufene Schlüssel identisch.

Antwort 403

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Diesem API-Schlüssel fehlt das Recht finalize.",
    "details": { "requiredScope": "finalize" }
  }
}

Status	Code	Bedeutung
400	VALIDATION_ERROREingabe ungültig. details nennt jedes Feld mit Grund.	Eingabe ungültig. details nennt jedes Feld mit Grund.
401	UNAUTHORIZEDSchlüssel fehlt, ist falsch, abgelaufen oder widerrufen.	Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen.
403	FORBIDDENDem Schlüssel fehlt das Recht, zum Beispiel finalize.	Dem Schlüssel fehlt das Recht, zum Beispiel finalize.
404	NOT_FOUNDNicht vorhanden oder gehört zu einem anderen Unternehmen.	Nicht vorhanden oder gehört zu einem anderen Unternehmen.
409	CONFLICTZustand passt nicht, zum Beispiel ein abgeschlossenes Dokument ändern.	Zustand passt nicht, zum Beispiel ein abgeschlossenes Dokument ändern.
413	PAYLOAD_TOO_LARGEJSON über 1 MB oder Datei über 4 MB.	JSON über 1 MB oder Datei über 4 MB.
422	IDEMPOTENCY_MISMATCHGleicher Idempotency-Key mit anderem Inhalt.	Gleicher Idempotency-Key mit anderem Inhalt.
429	RATE_LIMITEDMehr als 120 Anfragen pro Minute. Retry-After beachten.	Mehr als 120 Anfragen pro Minute. Retry-After beachten.
500	INTERNALUnerwarteter Fehler. Mit X-Request-Id an den Support.	Unerwarteter Fehler. Mit X-Request-Id an den Support.