Přeskočit na hlavní obsah

Přehled kontraktu

Tři kategorie flow​

1. Event ingestion (vy → casinocrm.io)​

Každá akce hráče se stává událostí. Použijte SDK nebo volejte /v1/events přímo:

POST https://ingest.casinocrm.io/v1/events
Authorization: Bearer ucrm_pk_prod_TJxd_<secret>
Content-Type: application/json

{
  "event": "deposit_confirmed",
  "external_id": "casino_player_001",
  "anonymous_id": "anon_xyz",
  "timestamp": "2026-05-08T10:00:00Z",
  "properties": {
    "amount": 5000,
    "currency": "EUR",
    "transaction_id": "tx_abc",
    "payment_method": "card"
  }
}

Vrátí 202 s ingestion_id. Událost dorazí do ClickHouse + hráč je upsertnut v Postgresu během sekund.

Pro batch ingestion (doporučeno pro high-volume operátory):

POST https://ingest.casinocrm.io/v1/events/batch
Content-Type: application/json
{
  "events": [ ... až 100 událostí ... ]
}

2. Outbound adapter volání (casinocrm.io → vy)​

Když CRM vystaví bonus / zruší bonus / dotazuje platform status, volá váš adapter endpoint. Musíte vystavit:

POST  <your-base>/v1/bonuses/grant   - vystavit bonus na platformě
POST  <your-base>/v1/bonuses/cancel  - zrušit aktivní bonus
GET   <your-base>/v1/bonuses/:id     - dotaz na stav (reconciliation)

Auth: HMAC-SHA256 podepsaný ze strany casinocrm.io, sdílený secret na obou stranách. Viz Bezpečnost.

3. Webhook callbacks (vy → casinocrm.io)​

Poté, co vaše platforma připíše / wageruje / dokončí bonus, pošlete webhook:

POST https://api.casinocrm.io/v1/adapters/acme-prod/webhooks/bonus-events
X-casinocrm.io-Signature: <hex-hmac-sha256>
X-casinocrm.io-Timestamp: <unix-seconds>
Content-Type: application/json

{
  "event": "bonus.completed",
  "event_id": "evt_unique_uuid",
  "ts": "2026-05-08T12:00:00Z",
  "grant_id": "ucrm_grant_uuid",
  "platform_bonus_id": "platform_bonus_id",
  "data": { "completed_at": "...", "total_wagered": 30000 }
}

casinocrm.io deduplikuje na (adapter_slug, event_id), ověří HMAC a pak update bonus_grants.status.

Idempotence​

Každé mutující volání by mělo být idempotentní i na vaší straně:

  • Event ingestion — casinocrm.io deduplikuje přes hlavičku Idempotency-Key na /v1/events (volitelné). Bez ní replays produkují více ingestion_ids — váš event timestamp + transaction_id by měly být jedinečné.
  • Adapter volání (casinocrm.io → vy) — casinocrm.io předává naše grant_id jako correlation key. Vaše platforma by měla tento klíč ukládat a duplicity odmítat (vrátit 409 s code: "DUPLICATE_GRANT").
  • Webhooks (vy → casinocrm.io) — casinocrm.io deduplikuje na event_id. Pokud omylem pošlete stejnou událost dvakrát, replay vrátí 200 + applied: false + replay: true.

Retries​

  • casinocrm.io → vy (adapter volání): 3 retries s exponential backoff (1s / 4s / 16s) na 5xx + network errors. Non-retriable na 4xx + code: "DUPLICATE_GRANT".
  • Vy → casinocrm.io (webhooks): retryujte na non-2xx. Doporučeno 5 retries s exponential backoff až 1 hodinu. Odpověď casinocrm.io je vždy rychlá (<200ms), takže timeouty jsou vzácné.

Error sémantika​

casinocrm.io vrací chyby s typovaným kódem:

{
  "error": {
    "code": "PLATFORM_REJECTED",
    "message": "Player is self-excluded",
    "details": { "platform_code": "PLAYER_BLOCKED" }
  }
}

Když váš adapter vrací chyby zpátky do casinocrm.io, použijte stejný shape. Rozlišujte:

  • Retriable: 5xx, network errors, rate limity (429). casinocrm.io bude retryovat.
  • Non-retriable: 4xx s config / validation errors. casinocrm.io loguje + zobrazí v admin UI.