Événement sémantique au lieu de données brutes du fournisseur (Evenement Semantique Au Lieu DE Donnees Brutes Du Fournisseur)

Nous avons vu dans la section précédente que l'orchestrateur ne devait pas du tout voir le SDK PSP. La même limite apparaît à nouveau au-delà de l'appel synchrone : le webhook du fournisseur.

Un webhook PSP comporte généralement son propre modèle de données interne : nom du type d'événement spécifique au fournisseur, codes d'état spécifiques au fournisseur, structure d'objet spécifique au fournisseur. Placer cette charge utile telle quelle dans la file d'attente de messages ou le flux d'événements signifie divulguer le schéma du fournisseur à tous les consommateurs en aval.```text PSP Webhook { type: 'charge.succeeded', data: { object: {...} } } ▼ Provider Gateway (çeviri) ▼ Semantik event PaymentCaptured { paymentId, amount, currency }

## Concepts à la première mention```text
📦 Semantik Event
İş diliyle adlandırılmış, provider'a hiç referans vermeyen olay: PaymentCaptured, PaymentFailed.

📦 Ham Provider Payload
PSP'nin webhook body'sinde gönderdiği, kendi iç modelini taşıyan orijinal veri.

📦 Çeviri Katmanı (Translator)
Ham payload'ı okuyup semantik event'e dönüştüren, gateway içinde yaşayan bileşen.

📦 Event Sözleşmesi Sahipliği
Semantik event'in alanlarını ve anlamını kimin belirlediği; burada her zaman gateway.
````charge.succeeded` est la terminologie interne d'un fournisseur ; `PaymentCaptured` est la réalité de votre domaine. Les deux ne changent pas en même temps : le fournisseur peut changer le nom de l'événement, le nom sémantique de l'événement reste constant.

## Coût du transport de la charge utile brute telle quelle

Le moyen le plus rapide d’intégrer consiste à pousser le courtier de messages sans analyser le corps du webhook. Cela fonctionne à court terme : le consommateur analyse également la même charge utile. Mais cela propage les modifications du schéma du fournisseur directement à chaque consommateur. Lorsque la PSP renomme un domaine, un événement indépendant de votre volonté interrompt la plupart de vos systèmes en même temps.```text
Ham payload yayılırsa
  PSP şema değişikliği → N tüketici aynı anda etkilenir

Semantik event yayılırsa
  PSP şema değişikliği → sadece gateway'in çeviri katmanı güncellenir
```## Que fait la couche de traduction et que ne fait-elle pas ?

La couche de traduction mappe les codes d'état spécifiques au fournisseur à une énumération sémantique, normalise les champs incohérents ou manquants et complète les données manquantes (par exemple, montant, devise) de l'enregistrement local si nécessaire. Ce qu'il ne devrait pas faire, c'est prendre une décision commerciale : la réponse à la question « Pourquoi ce paiement a-t-il échoué, que faut-il faire » est le travail de l'orchestrateur, pas celui de la couche de traduction.```text
Webhook geldi
  → provider event tipini oku
  → statü eşleme tablosuna bak
  → semantik event oluştur
  → local correlation id ile eşle
  → yayınla (Outbox üzerinden)
```## La table de cartographie est un outil de conception concret

Le fournisseur peut avoir des dizaines de types d'événements ; votre ensemble d'événements sémantiques doit être beaucoup plus petit et stable.

| Événement du fournisseur | Événement sémantique |
| --- | --- |
| charge.réussie | PaiementCapturé |
| charge.failed | Échec du paiement |
| charge.dispute.créé | PaiementContesté |
| payment_intent.requires_action | PaiementActionObligatoire |

Ce tableau doit être lisible lors de la révision du code ; Lorsqu'un nouvel événement de fournisseur arrive, la question « à quel événement sémantique cela correspond » doit être une décision sur une seule ligne, et non une chaîne if-else dispersée dans la base de code.

## Garantie de commande et de relivraison toujours valable

La couche de traduction doit également gérer les scénarios dans lesquels le webhook arrive à plusieurs reprises ou dans le désordre. Le fournisseur peut envoyer le même webhook deux fois en raison d'une erreur réseau ; Lors de la génération d'un événement sémantique, cela nécessite que la génération d'événement soit idempotente : le même événement sémantique ne doit pas être réémis (ou conçu pour être idempotent en aval) lorsque le même identifiant de webhook apparaît une seconde fois.

## Distinctions souvent confuses```text
❌ Webhook = Event
✓ Webhook bir bildirim tetikleyicisidir; semantik event iş dilindeki gerçektir

❌ Ham payload'ı saklamak gereksizdir
✓ Ham payload tanılama için saklanır, ama yalnızca gateway'in kendi arşivinde

❌ Eşleme tablosu bir kere yazılır, bitmiştir
✓ Provider yeni event tipleri ekledikçe tablo canlı bir sözleşmedir
```## Traduction sémantique avec passe brute

| Critère | Passe brute | Traduction sémantique |
| --- | --- | --- |
| Informations sur le fournisseur en aval | Obligatoire | Inutile |
| Vulnérabilité au changement de schéma | Élevé | Faible |
| Données brutes pour le diagnostic | Pourrait se perdre | Stocké dans la passerelle |
| Ajouter une nouvelle PSP | Affecte les consommateurs | Affecte uniquement la table de mappage |

## Liste de contrôle lors de la conception de la couche de traduction

1. Des consommateurs en aval lisent-ils un domaine ou un code de statut spécifique au fournisseur ?
2. La table de mappage est-elle définie à un seul endroit ou dispersée dans la base de code ?
3. La charge utile brute du webhook est-elle stockée dans la propre archive de la passerelle à des fins de diagnostic ?
4. Lorsque le même webhook arrive deux fois, le même événement sémantique est-il diffusé deux fois ?
5. Que se passe-t-il lorsqu'un nouveau type d'événement de fournisseur arrive s'il n'a pas encore été mappé : est-il avalé silencieusement ou produit-il une alerte visible ?

La cinquième question est particulièrement importante : les événements inconnus ignorés en silence constituent l’une des formes les plus insidieuses de perte de données en production.

## Ce qu'il faut retenir de cet article

1. L'aval ne doit jamais voir le nom de l'événement ou le code d'état du fournisseur.
2. La couche de traduction est une table de mappage et une logique de normalisation, elle ne prend pas de décisions commerciales.
3. La charge utile brute est stockée à des fins de diagnostic, mais uniquement dans les limites de la passerelle.
4. Les événements inconnus du prestataire ne doivent pas être avalés silencieusement, mais doivent produire un signal visible.

> Le moyen le plus simple de comprendre si un événement est sémantique ou non est de lire son nom dans votre propre dictionnaire de domaine, et non dans la documentation du fournisseur.

Dans la section suivante, nous approfondissons les informations d'échec véhiculées par ces événements sémantiques : tous les `PaymentFailed` n'ont pas la même signification, nous avons besoin d'une taxonomie d'échec.