Status 

Die Unterstützung für Idempotenz-Keys ist derzeit teilweise vorhanden. Ausgewählte interne Retry-Mutationen – zum Beispiel die Order-Billing-Retry- und Refund-Billing-Retry-Flows – akzeptieren bereits einen Idempotenz-Key und nutzen ihn zur Deduplizierung von Downstream-Aufrufen an Zahlungsprozessoren. Es gibt noch kein standardisiertes idempotencyKey-Argument über alle kundenorientierten Create-Mutationen im Zonos Graph; das ist auf der Roadmap. Bis es verfügbar ist, nutzen Sie die unten beschriebenen Muster, um Mutationen retry-sicher zu halten.

Standardmäßig sichere Mutationen 

Einige Mutationen sind von Natur aus idempotent, weil sie per Upsert anhand eines stabilen von Ihnen bereitgestellten Identifiers arbeiten. Wenn Sie diese mit denselben Eingaben aufrufen, ist das Ergebnis dasselbe – es besteht kein Risiko, Duplikate zu erstellen.

• Mutationen, die einen eindeutigen vom Händler bereitgestellten Identifier akzeptieren (zum Beispiel eine externalId einer Bestellung), geben bei wiederholtem Aufruf den bestehenden Datensatz zurück, anstatt einen neuen zu erstellen.
• Nur-Lese-Operationen (Queries) sind immer sicher wiederholbar.

Wenn Sie Ihren eigenen stabilen Identifier an die Ressource anhängen können, die Sie erstellen, bevorzugen Sie diesen Weg.

Muster für nicht von Natur aus idempotente Mutationen 

Bei Mutationen, die Ressourcen ohne vom Händler bereitgestellten Key erstellen, behandeln Sie sie von Ihrer Seite als höchstens einmal:

1. Persistieren Sie die Anfrage vor dem Senden. Schreiben Sie eine Zeile in Ihre eigene Datenbank (Status pending), bevor der Netzwerkaufruf erfolgt.
2. Senden Sie die Mutation. Bei Erfolg speichern Sie die zurückgegebene Ressourcen-ID bei Ihrer Pending-Zeile (Status committed).
3. Bei Netzwerkfehler nicht blind wiederholen. Fragen Sie den Zonos Graph ab, um zu prüfen, ob die Ressource erstellt wurde (zum Beispiel durch Auflisten von Ressourcen, die in den letzten Minuten für Ihr Konto erstellt wurden, oder durch Abfrage einer korrelierbaren zugehörigen Ressource). Wiederholen Sie nur, wenn Sie bestätigen können, dass die Ressource nicht vorhanden ist.
4. Nutzen Sie eine Unique Constraint in Ihrer eigenen Datenbank auf dem Geschäftsschlüssel, der die Anfrage repräsentiert, damit ein doppelter Retry aus Ihrer Anwendung keine Doppelübermittlung verursachen kann.

Webhook-Zustellung ist mindestens einmal 

Wenn Sie Zonos-Webhooks verarbeiten, gestalten Sie Handler idempotent – dasselbe Ereignis kann mehrfach zugestellt werden. Deduplizieren Sie anhand der Ereignis-ID. Siehe Webhooks für das Ereignis-ID-Feld.

Wohin die Plattform sich entwickelt 

Die zugrunde liegende Plattform führt Idempotenz-Key-Flows bereits produktiv für Billing-Retries aus: Der Key begrenzt einen Retry-Versuch und verhindert doppelte Zahlungsprozessor-Aufrufe. Wir arbeiten daran, dasselbe Muster als optionales idempotencyKey-Argument bei kundenorientierten Create-Mutationen bereitzustellen. Wenn angegeben, gibt der Graph bei jedem nachfolgenden Aufruf mit demselben Key innerhalb eines Aufbewahrungsfensters die ursprüngliche Antwort zurück. Diese Seite wird aktualisiert, sobald die Funktion allgemein verfügbar ist.

Wenn standardisierte Idempotenz-Keys bei kundenorientierten Mutationen Ihre Integration blockieren, kontaktieren Sie den Support.