APIs & Webhooks
Teil von Doppelte Aktionen verhindern
Rechnungen nach einem Wiederholungsversuch nicht erneut anlegen
Nach einem Timeout kann eine Rechnung bereits existieren. So ordnen Sie den ursprünglichen Auftrag zu und vermeiden eine zweite Anlage.
Ein Timeout beweist nicht, dass keine Rechnung entstand: Sie kann bereits angelegt sein, obwohl der Workflow keine Antwort erhielt. Legen Sie sie deshalb nicht mit einem neuen Auftrag erneut an. Ordnen Sie zuerst den ursprünglichen Auftrag und sein mögliches Ergebnis zu.
Den Rechnungsauftrag kennzeichnen
Legen Sie vor dem API-Aufruf fest, welche fachliche Absicht genau einen Rechnungsentwurf erzeugen soll – etwa die Abrechnung eines Auftrags für einen bestimmten Abschnitt. Speichern Sie dafür eine interne Auftragskennung. Sie bleibt bei einem Wiederholungsversuch gleich; ein ausdrücklich neuer Rechnungsauftrag erhält eine neue Kennung.
Halten Sie Bearbeitungsstatus und, sobald bekannt, die Rechnungskennung fest. „Anfrage gesendet“ beweist keinen Erfolg, ein Timeout keinen Fehlschlag.
Eine unklare Antwort abgleichen
- Laden Sie den ursprünglichen Rechnungsauftrag.
- Prüfen Sie eine bereits gespeicherte Rechnungskennung im Zielsystem.
- Fehlt sie, suchen Sie nur dann nach einer übermittelten stabilen Referenz, wenn das Zielsystem diese Referenz speichert und zuverlässig auffindbar macht.
- Unterstützt die Ziel-API einen Idempotenzschlüssel, wiederholen Sie eine zulässige Anfrage mit demselben API-Schlüssel und denselben Parametern. Ordnen Sie diesen Schlüssel dem internen Auftrag zu.
- Bleibt das Ergebnis unklar, halten Sie den Fall zur Prüfung an.
Stripe unterstützt Idempotenzschlüssel für POST-Anfragen. Es speichert auch die Antwort eines begonnenen Aufrufs, der mit einem 500-Fehler endet; eine Wiederholung mit demselben Schlüssel kann denselben Fehler zurückgeben.
Schlüssel können entfernt werden, sobald sie mindestens 24 Stunden alt sind. Danach kann ihre Wiederverwendung eine neue Anfrage auslösen. Der Idempotenzschlüssel ersetzt daher keine länger benötigte Zuordnung zwischen Auftrag und Rechnung.
Anlage und Folgeschritte getrennt absichern
Bei Stripe erzeugt der dokumentierte Anlageendpunkt zunächst einen Rechnungsentwurf. Finalisierung und Versand sind weitere Aktionen. Prüfen Sie für jede wirksame Stufe Status und Ergebniskennung getrennt.
Kundenname oder Betrag allein weisen eine Rechnung nicht eindeutig einem Auftrag zu: Zwei berechtigte Rechnungen können dieselben Angaben tragen. Wenn weder eine zuverlässige Suche noch ein wirksamer Idempotenzschutz verfügbar ist, muss eine unklare Anlage sichtbar zur Prüfung offenbleiben.
Prüfen Sie vor dem Produktivstart mit Testdaten eine verlorene Antwort nach erfolgreicher Anlage, zwei gleichzeitige Läufe und einen bewusst neuen Auftrag mit ähnlichen Angaben. Maßgeblich ist die Zahl der Rechnungsentwürfe im Zielsystem.
Wichtige Fakten zur sicheren Rechnungserstellung
- Stripe-Anfrage mit Fehler 500
- Antwort wird gespeichert; Wiederholung mit gleichem Schlüssel liefert dieselbe Antwort
- Rechnungsentwurf vs. Versand
- Zwei getrennte Schritte in Stripe – jeweils einzeln zu überprüfen
