Specifikace adapter integrace

Tento dokument je veřejný kontrakt pro integraci casino platformy s UCRM. Ať už zapojujete jakoukoli platformu, postupujte podle této specifikace.

Obsah

1. Přehled kontraktu
2. Kanonické eventy
3. Bonus flow
4. KYC flow
5. Bezpečnost (HMAC + replay)

Stručně

UCRM se připojuje k vaší casino platformě dvěma toky:

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

Inbound do UCRM (vy implementujete webhook senders):

• /v1/events — každá akce hráče (signup, deposit, bet, KYC change, RG change). Bearer API key auth.
• /v1/adapters/<slug>/webhooks/bonus-events — bonus lifecycle z vaší platformy. HMAC-podepsané.
• /v1/adapters/<slug>/webhooks/kyc-events — KYC lifecycle z vaší platformy. HMAC-podepsané.

Outbound z UCRM (vy vystavujete adapter endpointy):

• POST <your-base>/v1/bonuses/grant — vystavit bonus na wallet hráče.
• POST <your-base>/v1/bonuses/cancel — zrušit aktivní bonus.
• GET <your-base>/v1/bonuses/{id} — aktuální status bonusu (pro reconciliation).
• (KYC + RG outbound calls — když tenant.kyc_model in {crm_owns, dual} nebo RG features aktivní)

Adapter contract je bidirectional ale loosely coupled — platforma, která nepodporuje outbound bonus issuance, může integrovat event-only (jen sledujeme eventy; bonusy se kompletně spravují na platform UI).

Co potřebujete před startem

Item	Jak získat
API klíč	UCRM admin: Settings → API keys → Create. Format: ucrm_pk_<env>_<id>_<secret>
Adapter slug	Koordinováno s UCRM týmem. Lowercase, hyphenated. Příklad: acme-prod.
HMAC sdílený secret	Jeden per environment, vyměňováno out-of-band. UCRM ukládá pod UCRM_ADAPTER_<SLUG>_WEBHOOK_SECRET env var.
Webhook URL	Vaše inbound URL kam UCRM POSTuje adapter callbacks (cancel-bonus atd.).
Test tenant	UCRM provisionuje sandbox tenant se seedovanými test hráči.

Capability declaration

Váš adapter deklaruje statické capabilities při registraci:

{
  "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 pro tenant = tenant.config ∩ adapter.capabilities. Pokud feature není podporována na žádné straně, UCRM buď:

• Hard-blocks když je gap kritický (verticals mismatch, KYC model mismatch na crm_owns)
• Falls back na CRM-only enforcement když je gap recoverable (RG features → capability_mock pattern)

Versioning

Tato specifikace je verzována v lockstep s UCRM apps/api schema. Breaking changes vyžadují major version bump + deprecation notice. Aktuální verze: v1.

Spec doc na docs.casinocrm.io je vždy autoritativní. PDF / Markdown export reflektuje snapshot.

Support kanály

• Slack — kanál pouze pro operátory; požádejte UCRM tým o invite
• GitHub Issues — bug reports + feature requests
• Email — integrations@casinocrm.io