Integración de socios en el ecosistema

1) Roles y modelos de participación

Operadores/marcas: escaparates, cálculos, KYC/AML, responsabilidad de la experiencia del usuario.
Estudios/RGS/Agregadores de contenido: juegos/streams, catálogos, herramientas de promoción.
Proveedores de pago/carteras: PSP, APM, crypto, charjbeki.
KYC/AML/Antifraude: verificación, hojas de trineo, puntuación de riesgo.
Afiliados/redes de marketing: tráfico, postback, atribución.
ISV/integradores: módulos adicionales, aplicaciones de marketplace.

Modelos: referral/resell, white-label/OEM, marketplace/app-store, hub & spoke (federación).

2) «Pasaporte de socio» y paquete de inicio

Por qué: una única fuente de verdad sobre derechos, zonas, versiones, SLO, claves y procesos.

yaml partner_passport. v1:
partner_id: "kyc-omega"
type: "KYC/AML"
regions: ["EU","TR","LATAM"]
contracts: { msa: "2025-01-10", dpa: "2025-01-10", sla: "99. 9/30d" }
api_versions: ["identity. v1","events. v1","webhook. v1"]
auth: { oidc_client_id: "p_omega", scopes: ["kyc:read","kyc:write"] }
webhooks: { signature: "Ed25519", retry: "exp", dedupe: true, ttl_s: 300 }
rate_limits: { rps: 100, burst: 300 }
pii_policy: { minimization: true, retention: "180d", geo_pinning: ["EU"] }
recon: { window_days: 7, epsilon: 0. 002 }
owners: { biz: "ecosystem-biz", tech: "integrations" }
status: "sandbox"

3) Onboarding: proceso «de la aplicación a la producción»

1. Screening: cuestionario, KYC del socio, fuentes de datos/tráfico, check-in.
2. Tratados: MSA/DPA/SLA/OLA, comercio (CPA/RevShare/Hybrid/net-basis).
3. T-start: entrega de llaves/cliente OIDC, acceso a la caja de arena, conjunto de pruebas.
4. Pruebas de conformación: esquemas de eventos, webhooks, límites, idempotencia.
5. Revisión de seguridad: firma de artefactos, SBOM/SLSA (si SDK/cliente).
6. Piloto/canario: volumen/geo limitado, monitoreo reforzado.
7. Go-live: traducción de estado, SLO-dashboards, plan de respuesta.
8. QBR/MBR: revisiones regulares de KPI, incidentes, hojas de ruta.

4) Contratos de datos y esquemas de eventos

Principios: minimización, versiones (semver), compatibilidad 'vN/vN + 1', firmas.

yaml event. common. v1:
id: uuid occurred_at_utc: timestamp source_partner_id: string trace_id: uuid type: enum        # e. g., "kyc. approved. v1"
payload: object signature: ed25519 version: "1. 0. x"

Catálogos e informes: JSON Schema/Avro, control de campos obligatorios, TTL/Retenshen, Legal Hold.
Estabilidad: cambios de breaking sólo a través de nuevos tipos/versiones con ventana de depreción.

5) Autenticación, autorización, secretos

OAuth2/OIDC: tokens de vida corta, PoP/DPoP siempre que sea posible.
mTLS para servidor-servidor.
Webhooks firmados: Ed25519/HMAC; anti-replay ('X-Timestamp', ventana 5 min.).
PoLP/ABAC: scoups/atributos: 'partner', 'region', 'dataset', 'env'.
Rotación de claves: bidireccional, con ventana de compatibilidad y registro de auditoría.

python def verify(req):
if abs(now()-req. h["X-Timestamp"])>300: return 401 if not sig_ok(req. body, req. h["X-Signature"], partner_pubkey): return 401 if seen(req. json["event_id"]): return 200 store(req. json); mark_seen(req. json["event_id"]); return 200

6) Idempotencia, límites, sostenibilidad

Idempotency-Key: `partner_id + external_id + op_type`.
Rate limiting/quotas: RPS, burst, «heat start», disminuyendo los coeficientes de degradación.
Políticas Retry: expositor + jitter, dedoop en recepción.
Patrones outbox/inbox: entrega garantizada, dedoup, auditoría.
Backpressure: colas, DLQ con retoque separado.

7) Observabilidad y SLO

Метки: `partner`, `region`, `api_version`, `route`, `env`.
SLI: disponibilidad, p95/99 latency, error-rate, delivery-within-window, recon-diff.
SLO & burn rate: por socio/nodo; alertas por exceso.
Tracks: end-to-end 'trace _ id'; sampling de colas y errores (tail sampling).
Sintética: comprobaciones externas de endpoints/firmas/TTL.

rego package partner. release deny["SLO at risk"] { input. slo_forecast. error_burn > 1. 0 }
deny["Missing schema tests"] { input. tests. schemas_passed == false }

8) Cumplimiento y privacidad

Geo-pinning: los datos de dominios sensibles no salen de las regiones permitidas.
Minimización PII y pseudonimización: 'user _ pseudo _ id' en lugar de PD directos.
Períodos de almacenamiento: TTL/ILM; crypto-erasure por llaves (partner/per-región).
Derechos del sujeto: enrutamiento DSAR al origen, registro de ejecución.
Registros de acceso y auditoría: quién vio cuándo, por qué; registros inmutables.

9) Cálculos, atribución y reconciliación

Base de cálculo: net vs gross, tipos de cambio, impuestos, bonificaciones.
Atribución: ventanas (click/view), prioridad de canal, dedoup por 'event _ id/click _ id'.
Reconciliation: informes bilaterales, ε -doble, SLA de cierre de discrepancias (≤5 p. d.).

sql
SELECT a. event_id
FROM partner_report a
LEFT JOIN internal_events b ON a. event_id=b. event_id
WHERE a. date BETWEEN:from AND:to AND b. event_id IS NULL;

10) Versificación de API y control de cambios

Semver: 'v1' es una rama estable; breaking → 'v2' con doble soporte ≥90 días.
Proceso de depreciación: anuncio de la bandera → en el pasaporte → sintético/alertas → desconexión.
SDK/conectores: firma de lanzamientos, SBOM, compatibilidad, guidas migratorias.

11) Enrutamiento y federación (si hay varios socios del mismo tipo)

SOR (Smart Order Routing): precio/calidad/latencia/cumplimiento/reputación.
Fairness: límites de participación en el volumen de negocios, tie-break por SLA/reputación.
Degradación: caída honesta, deterioro transparente (notificaciones/pancartas).

12) Playbucks de incidentes

12. 1 «Traif diagrama de webhook»

yaml detect: "schema_validation_error_rate>0. 5%"
steps:
- "auto-pause partner webhooks"
- "fallback to cached/default behavior"
- "notify partner; open war-room"
- "provide diff & test vectors; hotfix window 24h"
kpi: ["RTA<=1h","residual_errors<0. 1%"]

12. 2 «Fracaso de SLO en PSP/KYC»

1. Redistribuir a través de SOR →

2. Habilitar la degradación graceful en el flujo →

3. Aplicar límites/cuotas →

4. Arranca un préstamo de SLA y un incidente posterior.

12. 3 «Discrepancia en los cálculos»

1. Freeze pagos en el rango de →

2. Re-conducir eventos de outbox →

3. Conciliación/ ε de corrección →

4. Acto conjunto y descongelación.

13) Marketplace/portal de socios

Certificación de integraciones: listas de cheques, etiquetas de calidad (Oro/Plata/Bronce).
Directorio de conectores: búsqueda/filtros por mercado/tipo/versión de la API.
Autogen-SDK/speks: OpenAPI/AsyncAPI, ejemplos, colecciones Postman.
Autoservicio: claves, webhooks, límites, registros, marcos de prueba.

14) Métricas de madurez de las integraciones

Time-to-Integrate (TTI): mediana de los días previos al prod.
Coverage: una proporción de los mercados/características apoyados por el socio.
SLO pass-rate: mes a mes por socio/región.
Recon-health: velocidad de cierre de discrepancias, ε residual.
Security posture: frecuencia de rotación de claves, SBOM coverage.
Costo/egress: $/req y $/GB por partners, eficiencia SOR.

15) Anti-patrones

«Primero conectamos, los estándares luego» → el zoológico de las integraciones.
Circuitos únicos para cada socio → una explosión de complejidad.
Sólo la atribución de cookies sin S2S → pérdidas y disputas.
No hay idempotencia/límites → retoques duplicados/tormenta.
PII en logs/webhooks → riesgos regulatorios.
Una «superintegración» sin alternativas → un riesgo de concentración.
Cambios de API sin ventana de depreciación y sintéticos → accidente en la venta.

16) Check-list del arquitecto de las integraciones

1. ¿El pasaporte del socio está lleno (contratos, regiones, versiones, llaves, SLO)?
2. Los esquemas de eventos e informes son validados por el paquete de prueba, ¿hay un sandbox?
3. OAuth/OIDC, firma de mandato de webhooks y anti-replay incluidos?
4. ¿Se implementan idempotencia, límites, outbox/inbox y DLQ?
5. ¿SLO/SLA dashboards, tracks, alertas burn-rate configuradas?
6. ¿Reconciliation y las ventanas de cálculo/atribución están formalizadas?
7. ¿Geo-pinning/TTL/crypto-erasure y enrutamiento DSAR in situ?
8. ¿Está documentado el proceso Semver, Deprecation y el soporte de doble versión?
9. ¿Se han comprobado los incidentes de playbooks (circuito de deriva, falla de SLO, recon-diff)?
10. Plan de salida: ¿deshabilitar claves, exportar datos, migrar a second-source?

Conclusión

La integración de socios es un transportador de producción: estándares → verificación → observabilidad → mejora. Cuando el pasaporte de un socio está completo, los eventos y contratos están tipificados, la autenticación y las firmas son obligatorias, los SLOs se miden, los cálculos se verifican y los cambios se gestionan a través de versiones y gateways: el ecosistema crece de forma rápida y segura, y cada nuevo socio refuerza el valor de la red.