---
title: "API: Wiederholungen, Konflikte und Synchronisierung sicher behandeln"
description: "API: Wiederholungen, Konflikte und Synchronisierung sicher behandeln. HTTP-Aufrufe und Beispiele für die lokale Billance-API."
url: "https://billance.de/de/hilfe/help-center/api-zuverlaessige-integrationen"
language: "de"
---

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

```bash
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.
