Интеграция партнеров в экосистему

1) Роли и модели участия

Операторы/бренды: витрины, расчеты, KYC/AML, ответственность за пользовательский опыт.
Студии/RGS/Агрегаторы контента: игры/стримы, каталоги, промоинструменты.
Платежные провайдеры/кошельки: PSP, APM, крипто, чарджбеки.
KYC/AML/Антифрод: верификация, санк-листы, риск-скоринг.
Аффилиаты/маркетинговые сети: трафик, постбэки, атрибуция.
ISV/интеграторы: дополнительные модули, приложения маркетплейса.

Модели: referral/resell, white-label/OEM, marketplace/app-store, hub&spoke (федерация).

2) «Паспорт партнера» и стартовый пакет

Зачем: единый источник правды о правах, зонах, версиях, SLO, ключах и процессах.

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) Онбординг: процесс «от заявки до production»

1. Screening: анкета, KYC партнера, источники данных/трафика, санк-чек.
2. Договоры: MSA/DPA/SLA/OLA, коммерция (CPA/RevShare/Hybrid/net-basis).
3. Тех-старт: выдача ключей/клиента OIDC, доступ в песочницу, набор тестов.
4. Conformance-тесты: схемы событий, вебхуки, лимиты, идемпотентность.
5. Security review: подпись артефактов, SBOM/SLSA (если SDK/клиент).
6. Пилот/канарейка: ограниченный объем/гео, усиленный мониторинг.
7. Go-live: перевод статуса, SLO-дашборды, план реагирования.
8. QBR/MBR: регулярные обзоры KPI, инциденты, дорожные карты.

4) Контракты данных и схемы событий

Принципы: минимизация, версии (semver), совместимость `vN/vN+1`, подписи.

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"

Каталоги и отчеты: JSON Schema/Avro, контроль обязательных полей, TTL/ретеншен, Legal Hold.
Стабильность: breaking-изменения только через новые типы/версии с окном deprecation.

5) Аутентификация, авторизация, секреты

OAuth2/OIDC: короткоживущие токены, PoP/DPoP по возможности.
mTLS для сервер-сервер.
Подписанные вебхуки: Ed25519/HMAC; анти-replay (`X-Timestamp`, окно 5 мин.).
PoLP/ABAC: скоупы/атрибуты: `partner`, `region`, `dataset`, `env`.
Ротация ключей: двусторонняя, с окном совместимости и аудиторским журналом.

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) Идемпотентность, лимиты, устойчивость

Idempotency-Key: `partner_id + external_id + op_type`.
Rate limiting/quotas: RPS, burst, «теплый старт», понижающие коэффициенты при деградации.
Retry-политики: экспонента + джиттер, дедуп на приеме.
Паттерны outbox/inbox: гарантированная доставка, дедуп, аудит.
Backpressure: очереди, DLQ с отдельным ретеншеном.

7) Наблюдаемость и SLO

Метки: `partner`, `region`, `api_version`, `route`, `env`.
SLI: доступность, p95/99 latency, error-rate, delivery-within-window, recon-diff.
SLO & burn rate: на партнер/узел; алерты по превышению.
Трассировки: сквозной `trace_id`; сэмплирование хвостов и ошибок (tail sampling).
Синтетика: внешние проверки эндпоинтов/подписей/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) Комплаенс и приватность

Geo-pinning: данные чувствительных доменов не покидают разрешенные регионы.
PII-минимизация и псевдонимизация: `user_pseudo_id` вместо прямых ПД.
Сроки хранения: TTL/ILM; crypto-erasure по ключам (пер-партнер/пер-регион).
Права субъекта: маршрутизация DSAR к источнику, журнал исполнения.
Журналы доступа и аудит: кто видел, когда, зачем; неизменяемые логи.

9) Расчеты, атрибуция и reconciliation

База расчета: net vs gross, курсы валют, налоги, бонусы.
Атрибуция: окна (click/view), приоритет каналов, дедуп по `event_id/click_id`.
Reconciliation: двусторонние отчеты, ε-допуск, SLA закрытия расхождений (≤5 р.д.).

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) Версионирование API и управление изменениями

Semver: `v1` — стабильная ветка; breaking → `v2` с двойной поддержкой ≥90 дней.
Deprecation-процесс: анонс → флаг в паспорте → синтетика/алерты → отключение.
SDK/коннекторы: подпись релизов, SBOM, совместимость, миграционные гайды.

11) Маршрутизация и федерация (если несколько партнеров одного типа)

SOR (Smart Order Routing): цена/качество/латентность/комплаенс/репутация.
Fairness: ограничения доли оборота, tie-break по SLA/репутации.
Degradation: честный fallback, прозрачное ухудшение (уведомления/баннеры).

12) Плейбуки инцидентов

12.1 «Дрэйф схемы вебхука»

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 «Провал SLO у PSP/KYC»

1. Перераспределить через SOR →

2. Включить graceful-degradation в потоке →

3. Применить лимиты/квоты →

4. Завести кредит по SLA и пост-инцидент.

12.3 «Расхождение в расчетах»

1. Freeze выплат по диапазону →

2. Re-drive событий из outbox →

3. Сверка/ε-коррекции →

4. Совместный акт и разморозка.

13) Маркетплейс/портал партнеров

Сертификация интеграций: чек-листы, бейджи качества (Gold/Silver/Bronze).
Каталог коннекторов: поиск/фильтры по рынкам/типам/версии API.
Автоген-SDK/спеки: OpenAPI/AsyncAPI, примеры, Postman-коллекции.
Self-service: ключи, webhooks, лимиты, журналы, тест-фреймы.

14) Метрики зрелости интеграций

Time-to-Integrate (TTI): медиана дней до prod.
Coverage: доля рынков/функций, поддержанных партнером.
SLO pass-rate: помесячно по партнеру/региону.
Recon-health: скорость закрытия расхождений, остаточный ε.
Security posture: частота ротаций ключей, SBOM coverage.
Cost/egress: $/req и $/GB по партнерам, эффективность SOR.

15) Анти-паттерны

«Сначала подключим, стандарты потом» → зоопарк интеграций.
Уникальные схемы на каждого партнера → взрыв сложности.
Только cookie-атрибуция без S2S → потери и споры.
Нет идемпотентности/лимитов → дубликаты/шторм ретраев.
PII в логах/вебхуках → регуляторные риски.
Одна «супер-интеграция» без альтернатив → концентрационный риск.
Изменения API без окна deprecation и синтетики → аварии в проде.

16) Чек-лист архитектора интеграций

1. Паспорт партнера заполнен (контракты, регионы, версии, ключи, SLO)?
2. Схемы событий и отчетов валидируются тест-паком, есть песочница?
3. OAuth/OIDC, мандатная подпись вебхуков и анти-replay включены?
4. Идемпотентность, лимиты, outbox/inbox и DLQ реализованы?
5. Дашборды SLO/SLA, трассировки, алерты burn-rate настроены?
6. Reconciliation и окна расчетов/атрибуции формализованы?
7. Geo-pinning/TTL/crypto-erasure и маршрутизация DSAR на месте?
8. Semver, deprecation-процесс и двойная поддержка версий задокументированы?
9. Плейбуки инцидентов проверены (дрейф схем, SLO-провал, recon-дифф)?
10. Exit-план: отключение ключей, экспорт данных, миграция на second-source?

Заключение

Интеграция партнеров — это производственный конвейер: стандарты → проверка → наблюдаемость → улучшение. Когда паспорт партнера полон, события и контракты типизированы, аутентификация и подписи обязательны, SLO измеряются, расчеты сверяются, а изменения управляются через версии и гейты — экосистема растет быстро и безопасно, а каждый новый партнер усиливает ценность сети.