Règles et intégration
Fiabiliser les événements de conversion et de remboursement
Évitez doubles commissions et pertes de mise à jour avec des identifiants stables, une recette des reprises et un rapprochement métier.
Avant de commencer
Un événement reçu n’est pas encore une commission correcte. Le même message peut revenir, un remboursement peut arriver avant la fin d’un traitement et un service peut répondre alors que l’enregistrement métier a échoué. Cette méthode aide responsables programme et intégration à définir les preuves nécessaires. Les propriétés exactes du transport doivent être confirmées dans la documentation de votre fournisseur ; Stripe sert ici d’exemple technique documenté.
Distinguer les trois identifiants
Séparez identifiant du message, identifiant de l’opération métier et identifiant du partenaire. Le premier permet de reconnaître une nouvelle livraison du même message ; le deuxième relie commande, facture, annulation et export ; le troisième porte l’attribution. Dans la grille de recette, ajoutez type d’événement, version et date métier. Ne déduisez pas un identifiant de commande fiable à partir d’un montant et d’une adresse client.
Vérifier le message avant traitement
Utilisez le mécanisme d’authenticité documenté pour votre fournisseur, notamment la vérification de signature lorsqu’elle est disponible. Ne remplacez pas les secrets ni leur configuration pendant une recette éditoriale. Définissez ce qui est enregistré en cas de signature invalide et évitez de publier des données personnelles dans les journaux. Une réponse HTTP favorable ne prouve pas que le message était légitime ou que l’opération métier a abouti.
Rendre les reprises sans effet double
Définissez ce que le système doit faire quand le même événement revient : retrouver le résultat existant plutôt que créer une nouvelle commission. Gardez un enregistrement du traitement et un lien vers l’opération métier. Les clés d’idempotence d’une API et la déduplication d’événements reçus répondent à des problèmes différents. La documentation Stripe les décrit séparément ; ne supposez pas que l’un protège automatiquement l’autre.
Accepter les événements hors ordre
Un transport peut ne pas garantir l’ordre attendu. Décrivez un remboursement reçu alors que la commande n’est pas encore disponible localement. Préparez une attente contrôlée ou une récupération depuis le système source, selon ses possibilités. Une mise à jour ancienne ne doit pas effacer un état plus récent sans règle explicite. Conservez heure d’occurrence et heure de réception afin d’expliquer la chronologie.
Tester panne et reprise
Dans un environnement autorisé, simulez un service indisponible, une réponse retardée et une réception répétée. Vérifiez les délais et limites de reprise du fournisseur. Une relance manuelle peut coexister avec une relance automatique : leur interaction doit être comprise. Définissez qui peut rejouer une opération, avec quelle preuve et quel contrôle après traitement. Le résultat attendu est une seule conséquence métier, pas simplement un statut de message réussi.
Rapprocher les états avec le métier
Comparez régulièrement commandes et factures du système source avec opérations éligibles dans la plateforme. Distinguez retard normal, refus documenté et perte réelle. Rapprochez nombres et montants par devise ; un total monétaire seul masque les doublons compensés par des absences. Gardez un échantillon d’identifiants de bout en bout pour les achats, remboursements partiels et annulations.
Préparer une preuve exploitable en incident
Pour chaque divergence, rassemblez référence métier, type, dates, version, état attendu et état observé sans exposer de secret. Indiquez le premier maillon dont le résultat diffère. Reliez cette fiche au guide d’incident de suivi et désignez propriétaire et délai de résolution. Après correction, rejouez le cas et les cas voisins : une réparation du remboursement ne doit pas doubler les achats.
Réponses pratiques
Les questions à trancher avant de signer
Un code HTTP 200 signifie-t-il que la commission est correcte ?
Il signale une réponse du point de réception. Il faut encore vérifier traitement, référence métier, éligibilité et état final. Le sens exact de l’accusé de réception dépend de l’intégration.
L’idempotence d’une requête API supprime-t-elle tous les doublons ?
Non. Elle concerne l’opération et le périmètre définis par l’API. La réception répétée d’événements nécessite ses propres contrôles. Testez les deux chemins séparément.
Sources et références
Ce guide aide à poser de meilleures questions et à structurer une décision vérifiable. Il est fourni à titre pédagogique et ne constitue pas un conseil juridique, fiscal ou financier. Les règles des plateformes, les conditions de marché, les capacités techniques et les critères d’éligibilité peuvent évoluer. Confirmez toute décision importante auprès de sources officielles à jour et, lorsque les conséquences le justifient, de professionnels qualifiés connaissant votre marché et votre organisation.