Evento semántico en lugar de datos sin procesar del proveedor (Evento Semantico EN Lugar DE Datos Sin Procesar Del Proveedor)

Vimos en la sección anterior que el orquestador no debería ver el SDK de PSP en absoluto. El mismo límite vuelve a aparecer un paso más allá de la llamada síncrona: el webhook del proveedor.

Un webhook de PSP normalmente lleva su propio modelo de datos interno: nombre de tipo de evento específico del proveedor, códigos de estado específicos del proveedor, estructura de objetos específica del proveedor. Poner esta carga útil tal como está en la cola de mensajes o en el flujo de eventos significa filtrar el esquema del proveedor a todos los consumidores posteriores.```text PSP Webhook { type: 'charge.succeeded', data: { object: {...} } } ▼ Provider Gateway (çeviri) ▼ Semantik event PaymentCaptured { paymentId, amount, currency }

## Conceptos en la primera mención```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` es la terminología interna de un proveedor; `PaymentCaptured` es la realidad de tu dominio. Los dos no cambian al mismo tiempo: el proveedor puede cambiar el nombre del evento, el nombre del evento semántico permanece constante.

## Costo de transportar la carga útil sin procesar tal como está

La forma más rápida de integración es enviar el intermediario de mensajes sin analizar el cuerpo del webhook. Funciona a corto plazo: el consumidor también analiza la misma carga útil. Pero esto propaga los cambios de esquema del proveedor directamente a cada consumidor. Cuando la PSP cambia el nombre de un dominio, un evento fuera de su control daña la mayoría de sus sistemas a la vez.```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
```## ¿Qué hace y qué no hace la capa de traducción?

La capa de traducción asigna códigos de estado específicos del proveedor a una enumeración semántica, normaliza campos inconsistentes o faltantes y completa los datos faltantes (por ejemplo, monto, moneda) del registro local si es necesario. Lo que no debería hacer es tomar una decisión empresarial: la respuesta a la pregunta "¿Por qué falló este pago? ¿Qué debería hacerse?" es trabajo del orquestador, no del nivel de traducción.```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 tabla de mapeo es una herramienta de diseño concreta.

El proveedor puede tener docenas de tipos de eventos; su conjunto de eventos semánticos debería ser mucho más pequeño y estable.

| Evento de proveedor | Evento semántico |
| --- | --- |
| carga.exitosa | PagoCapturado |
| carga.fallida | Pago fallido |
| cargo.disputa.creada | Pago en disputa |
| intención_pago.requires_action | Acción de pago requerida |

Esta tabla debe poder leerse en la revisión del código; Cuando llega un nuevo evento de proveedor, la pregunta "a qué evento semántico corresponde" debe ser una decisión de una sola línea, no una cadena if-else dispersa por todo el código base.

## La garantía de pedido y reenvío sigue siendo válida

La capa de traducción también debe manejar escenarios en los que el webhook llega repetidamente o fuera de orden. El proveedor puede enviar el mismo webhook dos veces debido a un error de red; Al generar un evento semántico, esto requiere que la generación del evento sea idempotente: el mismo evento semántico no debe volver a emitirse (ni diseñarse para que sea idempotente en sentido descendente) cuando aparece el mismo ID de webhook por segunda vez.

## Distinciones frecuentemente confusas```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
```## Traducción semántica con pase sin formato

| Criterio | Pase crudo | semántica traducción |
| --- | --- | --- |
| Información del proveedor de Downstream | Requerido | Innecesario |
| Vulnerabilidad al cambio de esquema | Alto | Bajo |
| Datos brutos para diagnóstico | Podría perderse | Almacenado en Puerta de enlace |
| Agregar nueva PSP | Afecta a los consumidores | Sólo afecta a la tabla de mapeo |

## Lista de verificación al diseñar la capa de traducción

1. ¿Algún consumidor intermedio lee un dominio o código de estado específico del proveedor?
2. ¿La tabla de mapeo está definida en un solo lugar o dispersa por toda la base del código?
3. ¿La carga útil del webhook sin procesar se almacena en el propio archivo de la puerta de enlace para realizar diagnósticos?
4. Cuando llega dos veces el mismo webhook, ¿se transmite dos veces el mismo evento semántico?
5. ¿Qué sucede cuando llega un nuevo tipo de evento de proveedor si aún no se ha mapeado? ¿Se traga silenciosamente o produce una alerta visible?

La quinta pregunta es particularmente importante: los eventos desconocidos absorbidos silenciosamente son una de las formas más insidiosas de pérdida de datos en producción.

## Lo que debes recordar de este artículo

1. Downstream nunca debería ver el nombre del evento o el código de estado del proveedor.
2. La capa de traducción es una tabla de mapeo y una lógica de normalización, no toma decisiones comerciales.
3. La carga útil sin procesar se almacena para diagnóstico, pero solo dentro de los propios límites de la puerta de enlace.
4. Los eventos de proveedores desconocidos no deben tragarse en silencio, sino que deben producir una señal visible.

> La forma más sencilla de comprender si un evento es semántico o no es leer su nombre en el diccionario de su propio dominio, no en la documentación del proveedor.

En la siguiente sección, profundizamos en la información de fallas que contienen estos eventos semánticos: no todos los `PaymentFailed` tienen el mismo significado, necesitamos una taxonomía de fallas.