Lokale Automatisierungs-API verwenden

Automatisiere Billance auf diesem Computer

Mit der lokalen Automatisierungs-API verbindest du eigene Skripte, Workflows oder lokale Unternehmenssoftware mit Billance. Sie verwaltet Ausgangsdokumente und Eingangsbelege, Zahlungen und Stammdaten und kann E-Rechnungen prüfen oder auslesen.

Wichtig: Die API ist eine Premium-Funktion. Sie läuft ausschließlich auf diesem Computer und nur, solange die Billance-Desktop-App geöffnet ist. Sie ist weder ein Cloud-Endpunkt noch ein fertiger Konnektor für einen bestimmten ERP-Anbieter.

Schnellstart

1. Öffne Einstellungen → Integrationen → Lokale Automatisierungs-API.
2. Aktiviere den lokalen Server.
3. Übernimm den Port oder wähle einen freien Port zwischen 1024 und 65535.
4. Kopiere Basis-URL und Zugriffstoken in dein Automatisierungswerkzeug.
5. Führe den Verbindungstest aus.

Geräte im LAN, Cloud-Dienste und Browser-Anwendungen können nicht direkt zugreifen. Browser erhalten absichtlich keine CORS-Freigabe.

Verbindung testen

Ersetze <TOKEN> durch den in Billance angezeigten Token:

curl \
  -H "Authorization: Bearer <TOKEN>" \
  "http://127.0.0.1:47115/api/integration/v1/health"

Bei Erfolg enthält die Antwort "status": "ok", die API- und App-Version sowie die verfügbaren Fähigkeiten.

Token sicher behandeln

Jede geschützte Anfrage benötigt diesen Header:

Authorization: Bearer blc_DEIN_TOKEN

Der Token gewährt Zugriff auf deine lokalen Billance-Daten. Deshalb:

• Speichere ihn nie im Quellcode, in Git-Repositories oder Logs.
• Nutze Umgebungsvariablen oder den Secret Store deines Werkzeugs.
• Erneuere ihn sofort, falls er versehentlich weitergegeben wurde.
• Aktualisiere danach alle Clients: Der alte Token wird sofort ungültig.

Ohne Token erreichbar sind nur GET / und GET /openapi.json. Auch GET /health benötigt einen Token.

Vertrag und Endpunkte entdecken

Die Einstellungen enthalten eine durchsuchbare Endpunktübersicht mit Parametern, bearbeitbarem JSON, kopierbaren cURL-Befehlen und einem Testknopf. Der Testknopf führt den Aufruf gegen die laufende lokale API aus und zeigt HTTP-Status und Antwort direkt darunter. Schreibende Aktionen erfordern zuvor eine zusätzliche Bestätigung; sie verändern echte lokale Daten. Die OpenAPI-3.1-Spezifikation steht für Tools und generierte Clients unter dieser Adresse bereit:

<BASE-URL>/openapi.json

Verwende immer die Spezifikation deiner installierten Billance-Version, damit dein Client zum tatsächlichen Vertrag der App passt.

Ausgangsdokumente

Zum Anlegen sende POST /invoices mit documentType und vollständigem formData. formData entspricht dem Billance-Editor: Absender, Empfänger, Positionen, Steuerregeln, Zahlungsdaten, Textblöcke und dokumentartspezifische Angaben.

Unterstützte documentType-Werte sind invoice, offer, confirmation, delivery_note, credit_note, recurring und reminder. Neue Integrationen verwenden ausschließlich formData; data ist nur ein veralteter Kompatibilitätsalias.

Achtung bei PUT: Lies den aktuellen Entwurf zuerst und sende anschließend das vollständige formData zurück. So bleiben unbekannte oder später ergänzte Felder erhalten. Finalisierte Dokumente sind wegen der GoBD-Sperre nicht mehr änderbar.

Für einfache Rechnungen genügt POST /invoices/simple mit invoiceNumber, invoiceDate, einem recipient mit Name und Adresse sowie items mit Name, Menge, Einzelpreis und Steuersatz. Optional sind paymentDueDays, currency, outputMode (pdf oder zugferd_en16931) und designTemplateId. Billance übernimmt die Verkäuferangaben aus dem aktiven Firmenprofil. Für weitere E-Rechnungsangaben nutze das vollständige formData.

Zuverlässig schreiben und synchronisieren

Sende bei schreibenden Anfragen einen eindeutigen Idempotency-Key (1–128 druckbare ASCII-Zeichen). Wiederhole nach einem Transportfehler exakt dieselbe Anfrage mit demselben Schlüssel. Billance bewahrt das Ergebnis sieben Tage auf; andere Inhalte mit demselben Schlüssel liefern 409 idempotency_key_reused. Ein noch ungeklärter Erstversuch liefert 409 idempotency_pending. Die reinen Import- und Validierungsanfragen verwenden diesen Header nicht.

Einzelne GET-Antworten enthalten ein ETag. Sende es bei allgemeinen PUT-/DELETE-Anfragen als If-Match, damit eine inzwischen geänderte Ressource mit 412 revision_conflict abgelehnt wird. Ohne If-Match bleibt das bisherige Verhalten erhalten.

Erfolgreiche Schreibanfragen bestätigen die lokale Speicherung. GET /sync/status zeigt den aktuellen Cloud-Sync-Anbieterstatus; das ist keine Zustellbestätigung für den einzelnen Datensatz. Rechnungslisten sind paginiert. Bei Empfängern, Produkten und Belegen aktiviert page oder pageSize die SQL-seitige Paginierung mit Gesamtzahlen; maximal 200 Einträge pro Seite.

PDF-Design auswählen

Mit GET /invoice-designs rufst du die eigenen und eingebauten PDF-Designs des aktiven Firmenprofils ab. Die Antwort enthält pro Design unter anderem id, name und isDefault. ?profileId=<id> wählt ein anderes Profil für diesen Lesezugriff.

Sende die gewünschte ID als designTemplateId im äußeren JSON von POST /invoices, POST /invoices/simple oder PUT /invoices/{id}. Die API prüft vor dem Speichern, ob das Design zum aktiven Firmenprofil gehört. Ohne ID gilt dessen Standarddesign. Im vollständigen PUT entfernt designTemplateId: null die bisherige Auswahl; ein fehlendes äußeres Feld übernimmt die Auswahl aus formData._designTemplateId. Die API-Antwort zeigt die gespeicherte Auswahl als designTemplateId an.

Das Design steuert die PDF-Darstellung auch bei ZUGFeRD. Reine XML-Dateien haben kein PDF-Design. Eine unbekannte oder fremde Design-ID liefert 422 validation_failed.

Erzeugen, exportieren und finalisieren

POST /invoices/{id}/generate nutzt dieselben Vorlagen, Schriften, Zahlungsprofile und E-Rechnungsregeln wie die Oberfläche. Über GET /invoices/{id}/export sind pdf, zugferd, xrechnung, ubl und json verfügbar; nicht jede Dokumentart unterstützt jedes Dateiformat.

Für den ersten Statusübergang verwende POST /invoices/{id}/finalize. Weitere erlaubte Übergänge gehen an POST /invoices/{id}/status:

{
  "status": "cancelled",
  "note": "Stornierung durch externen Workflow"
}

Nicht erlaubte Statuswechsel liefern 409 mit dem stabilen Fehlercode invalid_status_transition. Zahlungen sendest du an POST /invoices/{id}/payments; Billance berechnet bezahlten Betrag, Restbetrag, Status und Skonto automatisch.

Stammdaten und Eingangsbelege

/recipients und /products bieten Listen-, Anlage-, Änderungs- und Löschzugriffe. Schreibzugriffe gelten immer für das aktive Firmenprofil. Serverseitig vergebene IDs, Profilzuordnung und Zeitstempel kannst du nicht überschreiben; Rechnungs- und Belegzugriffe auf ein anderes Profil werden mit 409 profile_not_active abgelehnt; bei Stammdaten schützen die Repository-Regeln die Profilzuordnung.

Über /receipts verwaltest du Eingangsrechnungen und Belege. Originaldateien lädst du mit POST /receipts/{id}/attachment hoch:

{
  "fileName": "eingangsrechnung.pdf",
  "base64Content": "JVBERi0xLjQ..."
}

Unterstützt sind PDF, PNG, JPEG, WebP, HEIC, TIFF und XML bis 50 MB. Billance speichert sie geschützt, berechnet einen SHA-256-Hash und gibt keine lokalen Dateisystempfade aus. Finalisierte Originale können nicht ersetzt oder entfernt werden. Über /receipts/{id}/payments erfasst du Belegzahlungen; Teilzahlung, Überzahlung und Skonto berechnet Billance automatisch.

E-Rechnungen und Fehler

• POST /import/validate prüft PDF- oder XML-Dateien gegen die unterstützten EN-16931-Regeln.
• POST /import/einvoice liefert zusätzlich strukturierte Rechnungsdaten.
• Beide Endpunkte erwarten Base64-Inhalt und fileType mit pdf oder xml; sie legen absichtlich kein Ausgangsdokument automatisch an.

Fehler folgen RFC 7807 (application/problem+json). Werte den stabilen code aus, nicht nur den lesbaren Text:

Wenn etwas nicht funktioniert

1. Billance ist geöffnet, du bist angemeldet und Premium ist aktiv.
2. Die API ist eingeschaltet und dein Client verwendet die exakt angezeigte Basis-URL samt Port.
3. Die Anfrage kommt vom selben Computer über 127.0.0.1.
4. Der Header lautet exakt Authorization: Bearer <TOKEN>.
5. Kein anderes Programm belegt den Port; wähle sonst in den Einstellungen einen anderen.
6. Wurde der Token erneuert, aktualisiere den Secret Store deines Clients.

Für zuverlässige Integrationen: Speichere Billance-IDs im Quellsystem, behandle 409-Konflikte bewusst, prüfe nach Timeouts vor einem erneuten Schreibversuch per GET und begrenze Parallelität mit Backoff nach 429. Für LAN-, Cloud- oder Mobilzugriffe brauchst du eine eigene, abgesicherte Vermittlungsschicht mit Authentifizierung, Verschlüsselung, Berechtigungen und Datenschutzkonzept.

Weitere API-Anleitungen

Die verwandten Artikel erklären den vollständigen API-Ablauf bis zum PDF, E-Rechnungen über die API sowie sichere Wiederholungen und Konflikte. Die App enthält zusätzlich eine aufklappbare Feld- und Antwortreferenz aus ihrer OpenAPI-Spezifikation und auswählbare API-Beispiele.