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

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 вимірюються, розрахунки звіряються, а зміни управляються через версії і гейти - екосистема зростає швидко і безпечно, а кожен новий партнер посилює цінність мережі.