Перейти до основного вмісту

Огляд контракту

Translator note: machine-translated baseline. Needs human review by a native UK speaker. EN source is canonical.

Три категорії flow​

1. Event ingestion (ви → casinocrm.io)​

Кожна дія гравця стає подією. Використайте SDK або викличте /v1/events напряму:

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"
  }
}

Повертає 202 з ingestion_id. Подія потрапляє до ClickHouse + гравець upsert-иться у Postgres протягом секунд.

Для batch ingestion (рекомендовано для high-volume операторів):

POST https://ingest.casinocrm.io/v1/events/batch
Content-Type: application/json
{
  "events": [ ... до 100 подій ... ]
}

2. Outbound adapter виклики (casinocrm.io → ви)​

Коли CRM видає бонус / скасовує бонус / запитує platform status, він викликає ваш adapter endpoint. Ви маєте виставити:

POST  <your-base>/v1/bonuses/grant   - видати бонус на платформі
POST  <your-base>/v1/bonuses/cancel  - скасувати активний бонус
GET   <your-base>/v1/bonuses/:id     - запит статусу (reconciliation)

Auth: HMAC-SHA256 підписаний від casinocrm.io, спільний secret на обох сторонах. Див. Безпека.

3. Webhook callbacks (ви → casinocrm.io)​

Після того як ваша платформа кредитує / wager-ить / завершить бонус, надішліть 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 дедуплікує по (adapter_slug, event_id), перевіряє HMAC, потім оновлює bonus_grants.status.

Idempotency​

Кожен мутуючий виклик повинен бути ідемпотентним і на вашій стороні:

  • Event ingestion — casinocrm.io дедуплікує через заголовок Idempotency-Key на /v1/events (опційно). Без нього replay-и продукують кілька ingestion_ids — ваш event timestamp + transaction_id мають бути унікальними.
  • Adapter виклики (casinocrm.io → ви) — casinocrm.io передає наш grant_id як correlation key. Ваша платформа має його зберігати + відмовляти duplicate-и (повертати 409 з code: "DUPLICATE_GRANT").
  • Webhooks (ви → casinocrm.io) — casinocrm.io дедуплікує по event_id. Якщо випадково надішлете ту саму подію двічі, replay поверне 200 + applied: false + replay: true.

Retries​

  • casinocrm.io → ви (adapter виклики): 3 retries з exponential backoff (1s / 4s / 16s) на 5xx + network errors. Non-retriable на 4xx + code: "DUPLICATE_GRANT".
  • Ви → casinocrm.io (webhooks): retry на non-2xx. Рекомендовано 5 retries з exponential backoff до 1 години. Відповідь casinocrm.io завжди швидка (<200ms), тому timeout-и рідкісні.

Error семантика​

casinocrm.io повертає помилки з типізованим кодом:

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

Коли ваш adapter повертає помилки назад до casinocrm.io, використовуйте той самий shape. Розрізняйте:

  • Retriable: 5xx, network errors, rate limit-и (429). casinocrm.io буде retry.
  • Non-retriable: 4xx з config / validation помилками. casinocrm.io логує + показує в admin UI.