Statut 

La prise en charge des clés d'idempotence est partielle aujourd'hui. Certaines mutations de nouvelle tentative internes — par exemple, les flux de nouvelle tentative de facturation de commande et de remboursement — acceptent déjà une clé d'idempotence et l'utilisent pour dédupliquer les appels au processeur de paiement en aval. Il n'existe pas encore d'argument idempotencyKey standardisé sur toutes les mutations de création côté client sur le Graph Zonos ; cela fait partie de la feuille de route. Jusqu'à sa disponibilité, utilisez les modèles ci-dessous pour garder les mutations sûres à réessayer.

Mutations sûres par défaut 

Certaines mutations sont naturellement idempotentes car elles effectuent un upsert à partir d'un identifiant stable que vous fournissez. Lorsque vous les appelez avec les mêmes entrées, le résultat est identique — il n'y a aucun risque de créer des doublons.

• Les mutations qui prennent un identifiant unique fourni par le commerçant (par exemple, un externalId de commande) renverront l'enregistrement existant lors d'un nouvel appel plutôt que d'en créer un nouveau.
• Les opérations en lecture seule (requêtes) sont toujours sûres à réessayer.

Lorsque vous pouvez associer votre propre identifiant stable à la ressource que vous créez, privilégiez cette approche.

Modèles pour les mutations qui ne sont pas naturellement idempotentes 

Pour les mutations qui créent des ressources sans clé fournie par le commerçant, traitez-les comme au plus une fois de votre côté :

1. Persistez la requête avant l'envoi. Écrivez une ligne dans votre propre base de données (statut pending) avant l'appel réseau.
2. Envoyez la mutation. En cas de succès, enregistrez l'identifiant de la ressource renvoyée sur votre ligne en attente (statut committed).
3. En cas d'erreur réseau, ne réessayez pas aveuglément. Interrogez le Graph Zonos pour déterminer si la ressource a été créée (par exemple, en listant les ressources créées au cours des dernières minutes pour votre compte, ou en interrogeant une ressource associée que vous pouvez corréler). Ne réessayez que si vous pouvez confirmer que la ressource n'est pas présente.
4. Utilisez une contrainte d'unicité dans votre propre base de données sur la clé métier qui représente la requête, afin qu'une nouvelle tentative en double depuis votre propre application ne puisse pas soumettre deux fois.

La livraison des webhooks est au moins une fois 

Lorsque vous consommez les webhooks Zonos, concevez des gestionnaires idempotents — le même événement peut être livré plus d'une fois. Dédupliquez par l'identifiant de l'événement. Consultez Webhooks pour le champ d'identifiant d'événement.

Orientation de la plateforme 

La plateforme sous-jacente exécute déjà des flux de clés d'idempotence en production pour les nouvelles tentatives de facturation : la clé délimite la portée d'une nouvelle tentative et empêche les appels en double au processeur de paiement. Nous travaillons à exposer le même modèle sous forme d'argument idempotencyKey optionnel sur les mutations de création côté client. Lorsqu'il est fourni, le Graph renverra la réponse originale pour tout appel ultérieur avec la même clé dans une fenêtre de rétention. Cette page sera mise à jour lorsque la fonctionnalité sera généralement disponible.

Si des clés d'idempotence standardisées sur les mutations côté client bloquent votre intégration, contactez le support.