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.

| Einstellung | Standardwert | Bedeutung | | --- | --- | --- | | Basis-URL | http://127.0.0.1:47115/api/integration/v1 | Gemeinsamer Präfix aller API-Pfade | | Netzwerkzugriff | 127.0.0.1 | Nur Programme auf demselben Computer können zugreifen | | Authentifizierung | Bearer-Token | Für alle Daten- und Schreibzugriffe erforderlich |

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, Beispiel-Payloads und kopierbaren cURL-Befehlen. 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.

| Zweck | Route | Hinweis | | --- | --- | --- | | Entwurf anlegen | POST /invoices | Nutze documentType und vollständiges formData | | Entwurf lesen | GET /invoices/{id} | Vor jedem vollständigen Update abrufen | | Entwurf ersetzen | PUT /invoices/{id} | Ersetzt die Formulardaten vollständig | | Dokument erzeugen | POST /invoices/{id}/generate | Erstellt das konfigurierte PDF oder E-Rechnungsartefakt | | Export herunterladen | GET /invoices/{id}/export?format=pdf | Einmaliger Download; weitere Formate siehe OpenAPI |

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.

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; ein Schreibzugriff auf ein anderes Profil wird mit 409 profile_not_active abgelehnt.

Ü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:

| Status | Code | Bedeutung | | --- | --- | --- | | 401 | unauthorized | Token fehlt oder ist ungültig | | 403 | premium_required | Premium-Zugriff ist nicht verfügbar | | 404 | not_found | Ressource oder lokale Originaldatei fehlt | | 409 | profile_not_active, receipt_locked, invalid_status_transition | Fachlicher Konflikt oder GoBD-Sperre | | 413 / 415 / 422 | payload_too_large, unsupported_media_type, validation_failed | Anfrage, Dateityp oder Daten ungültig | | 429 | rate_limited | Mehr als 120 Anfragen innerhalb einer Minute |

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.