Lokale Automatisierungs-API

Was die API ist – und was sie nicht ist

Die Automatisierungs-API ist ein lokaler HTTP-Server, den Billance auf deinem Computer startet. Sie verwaltet Ausgangsdokumente und Eingangsbelege, Zahlungen und Stammdaten und kann E-Rechnungen prüfen oder auslesen. Sie ist kein Cloud-Endpunkt und kein fertiger Konnektor für einen bestimmten ERP-Anbieter, sondern eine technische Schnittstelle für eigene Skripte, Workflows und lokale Unternehmenssoftware.

Der Zugriff ist bewusst eng gefasst: Der Server hört auf 127.0.0.1, also ausschließlich auf Programme desselben Computers. Geräte im LAN, Cloud-Dienste und Browser-Anwendungen können nicht direkt zugreifen – Browser erhalten absichtlich keine CORS-Freigabe. Jede fachliche Anfrage braucht den Bearer-Token, den dir Billance in den Einstellungen anzeigt; ohne Token erreichbar sind nur der Wurzelpfad und die OpenAPI-Spezifikation.

Der Vertrag wird nicht beschrieben, sondern ausgeliefert: Die Einstellungen enthalten eine durchsuchbare Endpunktübersicht mit Parametern, Beispiel-Payloads und kopierbaren cURL-Befehlen, und unter <BASE-URL>/openapi.json liegt die OpenAPI-3.1-Spezifikation für Werkzeuge und generierte Clients. Verwende immer die Spezifikation deiner installierten Version, damit dein Client zum tatsächlichen Vertrag der App passt.

In fünf Schritten verbunden

1. 1

   API aktivieren

   In den Einstellungen unter Integrationen den lokalen Server einschalten.

2. 2

   Port festlegen

   Den Standardport 47115 übernehmen oder einen freien Port zwischen 1024 und 65535 wählen, falls ein anderes Programm ihn belegt.

3. 3

   Basis-URL und Token übernehmen

   Beides in dein Automatisierungswerkzeug kopieren; der Token gehört in einen Secret Store, niemals in Quellcode, Repository oder Logs.

4. 4

   Verbindung testen

   Ein Aufruf von /health mit dem Authorization-Header liefert Status, API- und App-Version sowie die verfügbaren Fähigkeiten.

5. 5

   Endpunkte erkunden

   Die Endpunktübersicht in den Einstellungen und die OpenAPI-Spezifikation zeigen Parameter, Beispiel-Payloads und cURL-Befehle.

Was die API abdeckt

• Ausgangsdokumente anlegen

  POST /invoices mit documentType und vollständigem formData – das Formularmodell entspricht dem Editor der App.

• Alle sieben Dokumenttypen

  invoice, offer, confirmation, delivery_note, credit_note, recurring und reminder stehen zur Verfügung.

• Erzeugen und exportieren

  POST /invoices/{id}/generate nutzt dieselben Vorlagen, Schriften, Zahlungsprofile und E-Rechnungsregeln wie die Oberfläche; der Export liefert PDF, ZUGFeRD, XRechnung, UBL oder JSON.

• Statuswechsel mit klaren Fehlern

  finalize für den ersten Übergang, status für die weiteren; nicht erlaubte Wechsel liefern 409 mit dem stabilen Code invalid_status_transition.

• Zahlungen automatisch verrechnet

  Zahlungen gehen an /invoices/{id}/payments; bezahlter Betrag, Restbetrag, Status und Skonto berechnet Billance selbst.

• Stammdaten pflegen

  /recipients und /products bieten Listen-, Anlage-, Änderungs- und Löschzugriffe; Schreibzugriffe gelten immer für das aktive Firmenprofil.

• Eingangsbelege und Anhänge

  Über /receipts verwaltest du Eingangsrechnungen; Originaldateien lädst du als Base64 hoch – PDF, PNG, JPEG, WebP, HEIC, TIFF und XML bis 50 MB.

• E-Rechnungen prüfen und auslesen

  POST /import/validate prüft PDF- oder XML-Dateien, POST /import/einvoice liefert zusätzlich strukturierte Rechnungsdaten – beide legen bewusst kein Dokument automatisch an.

• Fehler nach RFC 7807

  Antworten kommen als application/problem+json mit stabilem code, den du auswerten kannst, statt Text zu parsen.

Token, Grenzen und Fehlercodes

Der Token gewährt Zugriff auf deine lokalen Billance-Daten. Entsprechend eng sind die Grenzen gezogen – und entsprechend sorgfältig gehört er behandelt.

Speichere den Token nie im Quellcode, in Repositories oder Logs. Nach einer Erneuerung wird der alte Token sofort ungültig, und alle Clients müssen aktualisiert werden.

Worauf es bei einer stabilen Integration ankommt

Ein paar Regeln entscheiden darüber, ob eine Anbindung nach dem zweiten Update noch funktioniert.

• Vor jedem PUT lesen

  PUT /invoices/{id} ersetzt die Formulardaten vollständig. Lies den aktuellen Entwurf zuerst und sende ihn vollständig zurück, damit unbekannte oder später ergänzte Felder erhalten bleiben.

• IDs im Quellsystem speichern

  So findet deine Software ein Dokument nach einem Neustart wieder, statt es ein zweites Mal anzulegen.

• Nach Timeouts erst lesen

  Prüfe per GET, ob der Schreibvorgang schon angekommen ist, bevor du ihn wiederholst.

• Konflikte bewusst behandeln

  Ein 409 ist eine fachliche Aussage – etwa eine Sperre festgeschriebener Daten – und kein Grund, es einfach erneut zu versuchen.

• Parallelität begrenzen

  Nach einem 429 mit Backoff weiterarbeiten statt mit unveränderter Rate weiterzuschicken.

• Nur formData verwenden

  Neue Integrationen nutzen ausschließlich formData; data ist nur ein veralteter Kompatibilitätsalias.

Für LAN-, Cloud- oder Mobilzugriffe brauchst du eine eigene, abgesicherte Vermittlungsschicht mit Authentifizierung, Verschlüsselung, Berechtigungen und Datenschutzkonzept.

Wo die API läuft

Die Automatisierungs-API ist eine Funktion der Desktop-Anwendung, weil sie einen lokalen Server auf deinem Rechner braucht.

Gratis oder Premium

Fehlt der Premium-Zugriff, antwortet die API mit 403 premium_required statt stillschweigend nichts zu tun.

Häufige Fragen zur Automatisierungs-API

Weiterlesen