Patrones de interacción de los participantes

(Sección: Ecosistema y Red)

1) Contexto y objetivos

Hay muchos actores en el ecosistema (operadores, proveedores, servicios de pago y KYC, afiliados, reguladores, comunidades, desarrolladores). Los «patrones de interacción» son formas sostenibles de compartir valor y datos que garantizan la interoperabilidad, la seguridad, la rentabilidad y la escalabilidad.

• Reduzca los costos de transacción y el tiempo de integración.
• Mejorar la fiabilidad y la observabilidad de los flujos entre nodos.
• Equilibrar velocidad (latencia) y consistencia (consistencia).
• Coser el cumplimiento y los incentivos económicos en los protocolos de interacción.

2) Taxonomía de los participantes y roles

Operadores/tenantes: el servicio final para los usuarios, son propietarios de onboarding y UX.
Proveedores/estudios/sitios de contenido: proporcionan directorios/API/eventos, SLA para la emisión.
Servicios de pago/riesgo: autorización, compensación, charjbacks, puntuación, límites.
Socios/afiliados: conducen el tráfico, generan webhooks de conversión, reciben informes.
Reguladores/auditorías: requieren registros, informes, localización de datos.
Comunidades/desarrolladores: amplían SDK, crean aplicaciones/bots/integraciones.

3) Canales de comunicación y transporte

Consultas sincrónicas: NAT/gRPC para RQ/RS, WebSockets/SSE para eventos en vivo.
Buses asíncronos: Kafka/AMQP/streaming services, Pub/Sub para eventos de dominio.
Webhooks: canal push a un socio externo (obligatorio: firma, timeouts, retraos).
Interfaces de archivo/batch: NACHA/CSV/Parquet para reporting y backfill.
Edge/PoP: almacenamiento en caché, WAF, rate-limits, validación de firma, reducción de latencia.

4) Interacciones básicas (patrones de nivel de protocolo)

1. Request/Response (RQ/RS)

Usar para «soluciones ahora»: autorización de pago, verificación de límites, configuraciones.
Técnicas: timeouts, circuit-breaker, retries con jitter, llaves idempotentes.

2. Publish/Subscribe (Event-driven)

Para difundir los hechos: «la transacción se ha completado», «el balance ha cambiado», «el evento del juego».
Técnicas: particionamiento clave (por user_id/tenant_id), dedoup por clave de mensaje, almacenamiento de registro a largo plazo.

3. Comando/Respuesta (Comandos asíncronos)

Comando «hazlo» con respuesta/correlación diferida por correlation_id.
Técnicas: patrón de outbox, publicación garantizada, equipos de compensación.

4. Webhook Callback

Recepción de notificaciones de afiliados con entrega repetida (at-least-once).
Técnicas: firma de consulta, timestamp + anti-replay, idempotencia en el receptor.

5. Batch/Delta Sync

Cierres nocturnos, reporting, re-sincronización de manuales.
Técnicas: snapshots + incrementos, sumas de comprobación, esquemas de versionamiento.

5) Coordinación de procesos: orquestación vs coreografía

Coreografía (evento): los participantes responden a eventos de dominio sin un coordinador central.

Ventajas: conectividad débil, escalabilidad. Contras: más difícil de rastrear/incidentes.
Orquestación (sagas): el coordinador gestiona los pasos y las compensaciones.

Pros: control transparente, previsibilidad. Contras: punto de concentración de la lógica.

Saga (transacciones compensatorias): secuencia de pasos con acciones reversibles en caso de fallas. Para finanzas/balances: se prefiere un líder estricto y minimizar las operaciones compensatorias.

6) Consistencia y datos

Strong: pagos, límites, estados KYC (un solo líder, write-through, invariantes sincrónicos).
Eventual/Timeline: telemetría, catálogos, eventos de marketing (replicación asíncrona).
CRDT/versioning: para conflictos raros en escenarios multi-master.
Outbox/CDC: para que el evento «siempre» se publique junto con la entrada en la DB.
Identificadores: globales, ordenables (ULID/KSUID), con prefijos regionales para el diagnóstico.

7) Confiabilidad y sostenibilidad

Idempotencia: clave a nivel de solicitud/mensaje, dedoup en el receptor.
Retrai: retroceso exponencial con jitter; límite de tiempo de vida de la operación.
Tiempo de espera y presupuesto de retraso: p95/p99 para rutas críticas.
Backpressure: limitar el paralelismo, las colas, la priorización.
Degrade modes: funcionalidad parcial en caso de fallos (caché, operaciones retrasadas).
Chaos/GameDays: ejercicios regulares con simulación de fallos de integraciones y canales.

8) Seguridad, confianza, cumplimiento

Autenticación/autorización: OAuth2/OIDC, mTLS para S2S, tokens de breve vida.
Firma de mensajes/webhooks: HMAC + timestamp + nonce.
Privacidad/localización: PII/PCI en la «zona de confianza» de la región, minimizando el campo de datos en eventos (minimización de datos).
Auditoría y registros inmutables: correlación por trace_id, retención de pruebas de entrega/lectura.
Secretos y claves: KMS per-region, rotación, policy-as-code.
Antifraude y riesgo: puntuación en la entrada, límites por participante/canal, señales de comportamiento.

9) Economía de interacciones e incentivos

Contratos de monetización: RevShare/regalías, tarifas API (tiered), multas/notas de crédito para SLA.
Uso justo: cuotas, ratios-límites, prioridad por nivel de afiliación.
Enrutamiento costoso: si varios proveedores equivalen a SLA, elija uno más económico.
Informes transparentes: estados de envío, desorden de consumo, límites de autoservicio.

10) Observabilidad y SLO

Seguimiento: trace_id/span_id de extremo a extremo en RQ/RS y eventos.
Métricas: latency p50/p95/p99, error rate, valor de cola, porcentaje de visitas en caché, egresos.
Registros: estructurados, con tenant_id/partner_id/region/release.
Alerting: SLO por canal e integración; priorizar el impacto empresarial (por ejemplo, pagos> telemetría).

11) Plantillas de contratos modelo

1. NAT/gRPC contrato:

Versionar SemVer, campos obligatorios: idempotency-key, request-id, trace-context.
Respuestas: códigos de error deterministas, retry-hints, link al estado de la operación asíncrona.

2. Contrato de eventos:

Поля: event_id, occurred_at, producer, subject_id, version, schema_ref.
Garantías: al menos una vez, lote clave, TTL/retention.

3. Webhook contrato:

Títulos: signature, timestamp, nonce, delivery-id.
Comportamiento: 2xx = confirmación; retraídas con backoff a horas N, idempotencia en el receptor.

12) Patrones de ondeo de socios

Sandbox y llaves de prueba, catálogo público de API/eventos, Postman/SDK, ejemplos.
Portal de autoservicio: creación de webhooks, configuración de filtros de eventos, visualización de registros de entrega.
Railes de guardia integrados: límites de impago, advertencias antes de la auto-graduación.
Certificación de integraciones: listas de cheques, autovías de contratos, «marketplace» de estado.

13) Riesgos y anti-patrones

«Cadena de dominó» sincronizada: RPC largos a través de sistemas extraños → feiles en cascada.
Falta de idempotencia: toma de pago/evento.
Esquemas sin versionar: rompen a los consumidores en lanzamientos.
Una «verdad maestra» global para todo el dominio: una consistencia interregional costosa/frágil.
Economía opaca: los socios no ven consumo → conflictos y desconfianza.

14) Métricas de la salud de las interacciones

El éxito de las entregas de eventos (%) y el valor promedio de la entrega.
p95/p99 retrasos en rutas críticas (pago, cálculo de resultados).
Errores 4xx/5xx en la integración/canal, incidentes MTTR.
Proporción de tomas tratadas de forma idempotente, nivel de visitas en caché.
Costo por 1k solicitudes/eventos y egress por partner.
Conversión de onboarding partners: tiempo de «clave a primer éxito».

15) Lista de verificación de implementación

1. Clasificar las interacciones: sincronizado vs evento, criticidad de consistencia.
2. Identifique SLO y temporizadores, active Circuit-breakers y backoff.
3. Introduzca la idempotencia en todas partes (llaves, dedoop, replays).
4. Formalice las versiones de los esquemas/contratos y la política «expand → migrate → contract».
5. Incluya firmas y anti-replay para webhooks, KMS per-region.
6. Construya la vigilancia de extremo a extremo y los portales de autoservicio.
7. Automatice la certificación de socios y las pruebas de regresión de contratos.
8. Integrar la economía: cuotas, límites, informes, enrutamiento costoso.
9. Lleve a cabo JuegosDays regularmente para integraciones (degradación de canales, retrés masivos).
10. Revise la matriz de dominios una vez al trimestre: dónde reforzar el strong, dónde debilitar.

16) FAQ

¿Qué elegir: orquestación o coreografía? Para procesos complejos y críticos - orquestación; para una amplia escala - coreografía con contratos claros.
¿Cómo evitar las «tomas»? Llaves idempotentes + dedoop en el receptor + lógica «exactly-once-like» en los consumidores.
¿Cómo agilizar el onboarding de socios? Sandbox, scripts SDK/ejemplo listos, comprobaciones automáticas de webhooks y páginas de estado.
¿Cómo puedo incrustar el cumplimiento? Minimice los campos PII en los eventos, almacene las operaciones clave en «zonas de confianza» y mantenga una auditoría sin cambios.

Resumen: Los patrones de interacción no son sólo protocolos, sino también un conjunto de estímulos económicos, reiles de guardia y observabilidad. Formalizar los contratos, dividir los dominios por consistencia, hacer idempotencia y retraerse «por defecto», dar a los socios herramientas transparentes y métricas... y el ecosistema crecerá de forma sostenible y predecible.