Специфікація adapter integration

Цей документ — публічний контракт для інтеграції казино-платформи з UCRM. Яку б платформу ви не підключали, дотримуйтесь цієї специфікації від початку до кінця.

Зміст

Коротко

UCRM підключається до вашої казино-платформи двома потоками:

        ┌─────────────┐                        ┌─────────────┐
        │   PLATFORM  │  ── webhook events ──→ │    UCRM     │
        │             │  ←─ adapter calls ─── │             │
        └─────────────┘                        └─────────────┘

Inbound у UCRM (ви реалізуєте webhook senders):

/v1/events — кожна дія гравця (signup, deposit, bet, KYC change, RG change). Bearer API key auth.
/v1/adapters/<slug>/webhooks/bonus-events — bonus lifecycle із вашої платформи. HMAC-підписано.
/v1/adapters/<slug>/webhooks/kyc-events — KYC lifecycle із вашої платформи. HMAC-підписано.

Outbound від UCRM (ви виставляєте adapter endpoints):

POST <your-base>/v1/bonuses/grant — видати бонус на wallet гравця.
POST <your-base>/v1/bonuses/cancel — скасувати активний бонус.
GET <your-base>/v1/bonuses/{id} — поточний статус бонусу (для reconciliation).
(KYC + RG outbound calls — коли tenant.kyc_model in {crm_owns, dual} або RG features увімкнено)

Adapter contract є bidirectional, але loosely coupled — платформа, яка не підтримує outbound bonus issuance, може інтегруватись event-only (ми лише трекаємо події; бонусами повністю керує платформа).

Що потрібно до старту

Item	Як отримати
API key	UCRM admin: Settings → API keys → Create. Format: `ucrm_pk_<env>_<id>_<secret>`
Adapter slug	Узгоджено з UCRM team. Lowercase, hyphenated. Приклад: `acme-prod`.
HMAC shared secret	Один на середовище, обмінюється out-of-band. UCRM зберігає в `UCRM_ADAPTER_<SLUG>_WEBHOOK_SECRET` env var.
Webhook URL	Ваш inbound URL, куди UCRM POSTить adapter callbacks (cancel-bonus тощо).
Test tenant	UCRM provisions sandbox tenant із seeded test players.

Capability declaration

Ваш adapter оголошує статичні capabilities при реєстрації:

{
  "slug": "acme-prod",
  "displayName": "Acme Platform",
  "capabilities": {
    "verticals": ["casino", "sportsbook"],
    "bonus": { "issue": true, "cancel": true, "query_status": true },
    "kyc":   { "initiate": false, "query": true, "update": false, "webhooks": true },
    "rg_features": ["self_exclusion", "deposit_limit_daily", "loss_limit_daily", "session_limit_minutes"],
    "wallet": { "balance_pull": true, "balance_push": false },
    "signature_scheme": "hmac_sha256"
  }
}

Effective capabilities для tenant = tenant.config ∩ adapter.capabilities. Якщо feature не підтримується з обох боків, UCRM або:

Hard-blocks, коли gap критичний (verticals mismatch, KYC model mismatch на crm_owns)
Падає до CRM-only enforcement, коли gap recoverable (RG features → capability_mock pattern)

Versioning

Ця специфікація версіонується в lockstep з UCRM apps/api schema. Breaking changes потребують major version bump + deprecation notice. Поточна версія: v1.

Spec doc на docs.casinocrm.io завжди є authoritative. PDF / Markdown export відображає snapshot.

Канали підтримки

Slack — канал лише для операторів; запитайте UCRM team про invite
GitHub Issues — bug reports + feature requests
Email — integrations@casinocrm.io

Зміст​

Коротко​

Що потрібно до старту​

Capability declaration​

Versioning​

Канали підтримки​