Abstracción de proveedores sin fugas SDK (kit de desarrollo de software): el límite de la puerta de enlace (Abstraccion DE Proveedores Sin Fugas Sdk Kit DE Desarrollo DE Software El Limite DE La Puerta DE Enlace)

En la sección anterior vimos la diferencia entre evidencia de pago y estado de pago: La evidencia del PSP es algo diferente a la decisión del propio sistema. La pregunta de esta sección trata sobre un límite más fundamental: ¿el organizador de pago debería ver el SDK de una PSP?

La respuesta corta es no. Todo lo que el Orchestrator sabe debería ser esto: un pago solicitado, un resultado devuelto. Qué PSP produjo este resultado con qué versión de SDK y qué cliente HTTP; No es trabajo del orquestador, sino responsabilidad del gateway del proveedor.```text Checkout Orchestrator │ ChargeRequest (semantik) ▼ Provider Gateway │ PSP SDK / HTTP client ▼ PSP A veya PSP B

## Conceptos en la primera mención```text
📦 Provider Gateway
PSP SDK'sını, kimlik doğrulamasını ve provider'a özgü akışları sahiplenen tek servis.

📦 Semantik Arayüz
Orchestrator'ın gördüğü, hiçbir provider tipine referans vermeyen sözleşme.

📦 Anti-Corruption Layer
Dış sistemin veri modelinin, kendi domain dilinizi kirletmesini engelleyen çeviri katmanı.

📦 Adapter
Provider'a özgü isteği semantik isteğe, provider'a özgü yanıtı semantik sonuca çeviren kod.
```La 'fuga de SDK' no es un tecnicismo aquí: en el momento en que el tipo `ChargeObject` de una PSP aparece en el código del orquestador, cambiar esa PSP ya no significa cambiar un solo archivo, sino tocar profundamente dentro del orquestador.

## Por qué la fuga de SDK es una deuda furtiva

Al configurar una puerta de enlace de proveedor, la forma más corta es mover los objetos SDK de PSP al orquestador tal como está: importar el tipo `ChargeResponse` y usarlo directamente, leer un campo, verificar el estado. Es rápido en la primera semana. Pero tan pronto como este tipo ingresa a la firma del orquestador, se crea un vínculo de versión oculto entre los dos servicios: el SDK se actualiza, el nombre de dominio cambia, el orquestador encuentra un error de compilación o, peor aún, un error lógico silencioso.```text
❌ Orchestrator kodu
if (pspResponse.charges.data[0].outcome.network_status === 'approved') { ... }

✓ Orchestrator kodu
if (chargeResult.status === ChargeStatus.Captured) { ... }
```La segunda línea no contiene ningún nombre de proveedor. La puerta de enlace del proveedor sabe qué área de qué PSP mirar; El orquestador sólo conoce el resultado semántico.

## Por qué los flujos de tarjetas y billeteras comparten la misma interfaz pero no el mismo flujo

El pago con tarjeta es mayormente sincrónico: la solicitud se envía, el resultado de autorización/rechazo regresa en unos pocos cientos de milisegundos. Los pagos dirigidos por billetera o banco (flujos donde el usuario es redirigido a la página de PSP) son asincrónicos: la primera solicitud devuelve solo un estado "pendiente" y una URL de redireccionamiento; El resultado real llega minutos después a través de un webhook.```text
Kart akışı
  ChargeRequest → [senkron çağrı] → ChargeResult (Captured/Declined)

Wallet akışı
  ChargeRequest → ChargeResult (Pending + redirectUrl)
         ...
  Webhook → ChargeResult (Captured/Failed) [asenkron, sonradan]
```La interfaz semántica representa ambos con la misma forma `ChargeResult`; El campo que lleva la diferencia es `status` (`Pending` existe como tercer caso). A Orchestrator no le importa en absoluto la pregunta "¿Esta PSP utiliza redireccionamiento?"; Sólo responde a la pregunta "¿el resultado ahora es definitivo o está pendiente?"

## Qué campos nunca se deben cruzar al diseñar la interfaz

Los códigos de error específicos del proveedor, los ID de objetos específicos del proveedor (por ejemplo, el formato de ID de cargo interno de PSP) y las estructuras de metadatos específicos del proveedor nunca deberían filtrarse fuera de la interfaz semántica. En cambio, la puerta de enlace mantiene esta información en sus propios registros, en su propia área de diagnóstico; El orquestador solo devuelve un resultado que coincide con su ID de correlación.```text
Gateway içinde tutulan (dışarı sızmaz)
  provider_raw_code, provider_object_id, provider_response_headers

Orchestrator'a geçen (semantik)
  ChargeResult { status, amount, currency, providerRef }
````providerRef` es la única excepción: es una cadena de referencia opaca, almacenada para soporte y diagnóstico, pero nunca ramificada.

## Distinciones frecuentemente confusas```text
❌ SDK'yı bir sınıfa sarmak (wrap) yeterlidir
✓ Sarmalama tip sızıntısını çözmez; davranış hâlâ provider'a özgü kalabilir

❌ Abstraction = interface tanımlamak
✓ Abstraction = orchestrator'ın hiçbir zaman bilmemesi gereken şeyi seçmek

❌ Tek PSP varsa abstraction gereksizdir
✓ Tek PSP'de bile abstraction, test edilebilirlik ve mock'lanabilirlik sağlar
```## Diferencia entre Wrapper y abstracción real

| Criterio | Envoltorio fino | Abstracción semántica |
| --- | --- | --- |
| Fuga en la punta | Generalmente tienen | Ninguno |
| ¿Se ve afectado el orquestador cuando se cambia de PSP? | Sí | No |
| Quién gestiona la diferencia tarjeta/billetera | Orquestador | Puerta de enlace |
| Comprobabilidad | Mock de PSP debe | El resultado pseudosemántico es suficiente |

## Lista de verificación al diseñar la interfaz

1. ¿Se menciona directamente el nombre, dominio o código de error de alguna PSP en `ChargeResult`?
2. ¿Puede el Orchestrator manejar correctamente el caso `Pending` sin saber si una transmisión usa redireccionamiento o no?
3. ¿Es necesario cambiar una sola línea en el código del orquestador al agregar una nueva PSP? La abstracción tiene fugas si es necesario.
4. ¿Puede la prueba de Gateway generar dos veces todos los estados semánticos sin siquiera conectarse a la PSP real?
5. ¿Algún campo opaco distinto de `providerRef` ingresa a la lógica de decisión del orquestador?

Las respuestas de sí o no a estas preguntas reducen el debate sobre la arquitectura de una cuestión abstracta de "código limpio" a una prueba de límites mensurable.

## Lo que debes recordar de este artículo

1. Provider Gateway es el único propietario del SDK y de todos los detalles específicos del proveedor.
2. El orquestador solo conoce la intención (ChargeRequest) y el resultado semántico (ChargeResult).
3. Los flujos de tarjetas y billeteras comparten la misma interfaz; La diferencia es el estado `Pending` en el campo `status`.
4. Ningún campo opaco o específico del proveedor que no sea `providerRef` debe cruzar el límite.

> La verdadera prueba de una abstracción es que el código del orquestador no cambia en absoluto cuando agrega un nuevo proveedor.

En la siguiente sección, trasladaremos este límite al lado del evento: ¿deben los webhooks generados por la puerta de enlace llegar al orquestador como una carga útil del proveedor sin procesar o como un evento semántico?