API: Wiederholungen, Konflikte und Synchronisierung sicher behandeln

Zuverlässige Integrationen mit der lokalen Automatisierungs-API

Dieses Kapitel betrifft API-Clients und HTTP-Anfragen. Speichere die von Billance gelieferten IDs im Quellsystem. Nutze die OpenAPI-Spezifikation der installierten Version unter <BASE-URL>/openapi.json und halte das aktive Firmenprofil bewusst fest. Erfolgreiche Schreibzugriffe bestätigen die lokale Speicherung; der Cloud-Sync kann später scheitern.

Wiederholungen mit Idempotency-Key

POST-Schreibzugriffe sowie PUT und DELETE akzeptieren optional Idempotency-Key: 1–128 druckbare ASCII-Zeichen. Die reinen /import/validate- und /import/einvoice-Anfragen verwenden ihn nicht. Für jede neue fachliche Operation vergibst du einen neuen Schlüssel; für einen erneuten Versuch verwendest du denselben Schlüssel, dieselbe Methode, denselben Pfad, dieselben Queryparameter und denselben JSON-Inhalt.

Billance bewahrt das Ergebnis sieben Tage auf. Eine fertige Wiederholung liefert das gespeicherte Ergebnis mit Idempotency-Replayed: true. Andere Inhalte mit demselben Schlüssel liefern HTTP 409 idempotency_key_reused. Ein ungeklärter Erstversuch liefert HTTP 409 idempotency_pending: Prüfe den aktuellen Datenbestand, bevor du einen neuen Schlüssel verwendest. Auch bei einem Timeout ohne Idempotenz darfst du nicht einfach erneut anlegen; suche zuerst nach dem Dokument. Ein erneuertes Zugriffstoken bildet einen neuen Schlüsselkontext.

Änderungen mit ETag absichern

Einzelne Lesezugriffe auf Rechnungen, Empfänger, Produkte und Belege liefern einen ETag. Die allgemeinen PUT-/DELETE-Endpunkte derselben Ressourcen akzeptieren If-Match. Beispiel für eine Rechnung:

curl --fail-with-body -sS -D invoice-headers.txt \
  -H "Authorization: Bearer $BILLANCE_API_TOKEN" \
  "$BASE_URL/invoices/$INVOICE_ID" --output current-invoice.json

Übernimm den vollständigen ETag einschließlich Anführungszeichen in den Header If-Match. Lies formData aus current-invoice.json, ändere gezielt die gewünschten Felder und sende das vollständige formData an PUT /invoices/{id}. Ohne If-Match gibt es keinen Schutz vor einer inzwischen erfolgten Änderung. HTTP 412 revision_conflict bedeutet: neu lesen, Änderungen abgleichen und bewusst erneut schreiben. Finalisierte Rechnungen bleiben unabhängig davon unveränderlich. Zahlungs-, Status- und andere Unterendpunkte haben eigene Regeln; gehe nicht davon aus, dass sie If-Match unterstützen.

Listen und Firmenprofile

Rechnungslisten liefern immer items, page, pageSize, totalItems, totalPages. Bei Empfängern, Produkten und Belegen aktiviert page oder pageSize die paginierte Antwort; ohne beide Parameter enthält die Antwort nur items. Standard-Seitengröße ist 50, maximal 200. Lies jede Seite; eine Liste ist kein konsistenter Snapshot während paralleler Änderungen.

Lesezugriffe können je Endpunkt profileId unterstützen. Schreibzugriffe gelten für das aktive Firmenprofil. Serverseitige IDs, Profilzuordnung und Zeitstempel kannst du nicht frei überschreiben. Rechnungs- und Belegzugriffe auf ein anderes Profil können 409 profile_not_active liefern; Stammdatenzugriffe schützen die Profilzuordnung über ihre Repository-Regeln. Ein Profilwechsel in der App kann deinen Workflow beeinflussen.

Rate Limits, Fehler und Cloud-Sync

Das HTTP-Limit beträgt 120 Anfragen pro Minute je lokalem Client; auch öffentliche Aufrufe zählen. HTTP 429 liefert Retry-After: 60. Begrenze Parallelität und verwende Backoff. 400 bad_request betrifft ungültige Anfragefelder; 422 validation_failed betrifft fachliche Prüfung oder Erzeugung. RFC-7807-Fehler kommen als application/problem+json; entscheide anhand von status und code. Ein HTTP 200 vom Validator ist kein Nachweis einer gültigen Rechnung.

GET /sync/status liefert den Anbieterstatus, keine Zustellbestätigung eines einzelnen Datensatzes. Plane lokale Verarbeitung und spätere Synchronisierung getrennt. Die API ist ausschließlich über 127.0.0.1 erreichbar; keine direkte Cloud-/LAN-Anbindung und keine CORS-Freigabe.

API-Testbereich

In der App kannst du Pfad-/Queryparameter sowie dokumentierte Header eingeben und JSON bearbeiten. Schreibende Aufrufe erfordern Bestätigung. Ohne manuell gesetzten Idempotency-Key vergibt der Testknopf für schreibende Aufrufe einen neuen Schlüssel: Ein zweiter Klick ist dann eine neue Operation. Für einen Wiederholungstest trage selbst denselben Schlüssel ein. Der Testeditor unterstützt maximal 1 MiB Requesttext und zeigt höchstens 96 KiB Antworttext; größere Uploads oder Downloads führst du mit cURL aus. Die API akzeptiert JSON-Bodies bis 70 MiB; Belegdateien sind auf 50 MiB begrenzt.