Возможности

Фриспины

Фриспины оператора — спины, которые вы дарите игроку с фиксированной ставкой. Они разыгрываются в собственном клиенте игры (как бесплатные раунды, бонусные спины или бесплатные ставки — в зависимости от провайдера) и ничего не стоят игроку.

• Доступны для игр с free_spins: true в /games/health (445 из 446 игр).
• Методы — POST /gameActions.do с полем method; нужны partner, api_key и разрешённый IP.
• Те же функции есть на экране Free spins админ-панели (Админ: операции).

Методы#

Поддерживается необязательный заголовок Idempotency-Key (Соглашения). Устаревшие методы freespins_set и freespins_delete, а также freespins_get без id отвечают METHOD_RETIRED.

Создание выдачи#

curl -s -X POST https://notell-api.com/gameActions.do \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: promo-2026-10-player-123' \
  -d '{
    "method": "freespins_create",
    "partner": "YOUR_PARTNER_ID",
    "api_key": "YOUR_API_KEY",
    "player_id": "player-123",
    "currency": "UAH",
    "symbol": "gates-of-olympus",
    "count": 10,
    "bet": "1.00",
    "expires_at": "2026-11-01T12:00:00Z",
    "external_id": "promo-2026-10",
    "meta": {"campaign": "autumn"}
  }'

{
  "status": "ok",
  "grant": {
    "grant_id": "7b1c0e52-…",
    "external_id": "promo-2026-10",
    "player_id": "player-123",
    "currency": "UAH",
    "symbol": "gates-of-olympus",
    "provider": "pragmatic",
    "total": 10,
    "remaining": 10,
    "played": 0,
    "bet": "1.00",
    "total_win": "0.00",
    "status": "active",
    "created_at": "2026-10-15T10:00:00.000Z",
    "expires_at": "2026-11-01T12:00:00.000Z",
    "finished_at": null
  }
}

Форма выдачи в админ-панели показывает допустимые ставки выбранной игры и, если максимум проекта выше нативного максимума игры, расширенные ставки до него.

Объект выдачи#

Жизненный цикл и статусы#

active --последний спин рассчитан--> used
active --наступил expires_at-------> expired     (неиспользованные спины сгорают)
active --freespins_cancel----------> cancelled

• У игрока может быть несколько выдач на игру. Первой играется выдача, которая истекает раньше (при равенстве — более старая).
• Пока выдача активна, игрок может играть в этой игре только фриспины: платные спины, ante-ставки и покупки бонуса игра отклоняет (FREE_SPINS_ACTIVE), пока выдача не использована, не истекла или не отменена.
• Раунд, уже начатый к моменту истечения или отмены выдачи, завершается и начисляется как обычно; итоговый callback ждёт его.
• Раунды фриспинов проходят ту же RTP-логику, что и платные, и входят в окно адаптивного RTP игрока с номинальной ставкой (Управление RTP).

Взаимодействие с кошельком#

Каждый раунд фриспинов отправляет вашему кошельку bet с суммой 0 и meta.is_freespins: true; выигрышный раунд отправляет win с той же meta. Ваш кошелёк должен принимать нулевую ставку. Подробнее: Callbacks кошелька.

Итоговый callback#

Когда выдача завершается (used, expired или cancelled), платформа отправляет ровно один callback freespins_finished на адрес вашего кошелька и повторяет его, пока вы не ответите ok (задержки 10 с × 2^{попытки}, не более 1 часа):

{
  "method": "freespins_finished",
  "grant_id": "7b1c0e52-…",
  "external_id": "promo-2026-10",
  "player_id": "player-123",
  "currency": "UAH",
  "game": "gates-of-olympus",
  "status": "used",
  "total": 10,
  "played": 10,
  "bet": "1.00",
  "total_win": "23.50",
  "finished_at": "2026-10-15T12:30:00.000Z",
  "api_key": "YOUR_API_KEY"
}

Используйте его, чтобы закрыть акцию у себя и отчитаться по общему выигрышу. Сам выигрыш уже начислен обычными операциями win.

Другие методы#

# одна выдача по вашему external id
curl -s -X POST https://notell-api.com/gameActions.do -H 'Content-Type: application/json' \
  -d '{"method":"freespins_get","partner":"YOUR_PARTNER_ID","api_key":"YOUR_API_KEY","external_id":"promo-2026-10"}'

# список активных выдач игрока
curl -s -X POST https://notell-api.com/gameActions.do -H 'Content-Type: application/json' \
  -d '{"method":"freespins_list","partner":"YOUR_PARTNER_ID","api_key":"YOUR_API_KEY","player_id":"player-123","status":"active"}'

# отмена (повтор возвращает ту же выдачу)
curl -s -X POST https://notell-api.com/gameActions.do -H 'Content-Type: application/json' \
  -d '{"method":"freespins_cancel","partner":"YOUR_PARTNER_ID","api_key":"YOUR_API_KEY","grant_id":"7b1c0e52-…"}'

freespins_get и freespins_cancel требуют ровно одно из grant_id и external_id.

Ошибки#

UNAUTHORIZED, IP_NOT_ALLOWED, INVALID_REQUEST, GAME_NOT_FOUND, FREE_SPINS_UNSUPPORTED, INVALID_COUNT, INVALID_FREE_SPIN_BET, PROJECT_BET_LIMIT, INVALID_EXPIRY, DUPLICATE_EXTERNAL_ID, GRANT_NOT_FOUND, METHOD_RETIRED, IDEMPOTENCY_CONFLICT — см. справочник ошибок.