Интеграция с серверной частью

Bonus API введение

примечание

Провайдер - сторона предоставляющая игры (Aviatrix).

Партнер - сторона интегрирующая игры.

Бренд - вебсайт казино партнера, на котором пользователи играют в игры и делают ставки.

В данной секции описаны методы, которые уже реализованы на стороне провайдера. Они могут быть вызваны партнером для отображения бонусных конфигураций, менеджмента бонусов и отображения актуального статуса бонуса игроков.

к сведению

Бонусы, созданные в данном API, подчиняются тем же правилам, что и мануальные бонусы. Любые ставки, совершенные с использованием данных бонусов, на 100% вычитаются из общего оборота игры.

Bonus API методы

к сведению

Все POST запросы содержат HTTP заголовок X-Auth-Signature, необходимый для подтверждения подлинности хоста. Эта операция позволяет отказаться от IP whitelist при интеграции, так как последний лишает возможности провайдера оперативно масштабироваться (горизонтально), не предупреждая при этом бренд.

подсказка

Базовый URL можно получить по запросу у интеграционного менеджера.

/CreateBonusConfig

Метод используется для создания новой бонусной конфигурации.

Внимание

При создании бонусной конфигурации для разных игр в одном запросе можно указать только игры одной категории: крэш игры или слот игры.

Примеры комбинаций игр:

• nft-aviatrix
• second-chance
• nft-aviatrix, second-chance
• aviatrix-fruits

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/CreateBonusConfig HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "cid": "some-brand-id",
  "config": {
    "type": "free_bets",
    "validFrom": "2020-12-03T12:15:30.000Z",
    "validTo": "2020-12-03T12:15:30.000Z",
    "gameSettings": [
      {
      "gameId": "some-game-id",
      "minOddsWagering": 50.0,
      "maxOddsWagering": 150.0
      }
    ],
    "isPlayable": false,
    "wagering": {
      "multiplier": 10,
      "useBonusMoney": true
    }
  }
}

Parameter	Description	Type	Requirements	Explanation
cid	идентификатор бренда	string	обязательный	уникальный идентификатор
config.type	тип бонусной конфигурации	string	обязательный	доступные значения: free_bets
config.validFrom	начало действия бонусной конфигурации	timestamp	обязательный	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.validTo	конец действия бонусной конфигурации	timestamp	обязательный	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.gameSettings	список настроек для конкретной игры	array	обязательный	настройки бонусов для конкретного типа игры; одновременно можно указать только игры одной категори: крэш игры или слот игры
gameId	идентификатор игры	string	обязательный	примеры идентификаторов: nft-aviatrix, second-chance, aviatrix-fruits. С полным списком можно ознакомиться на странице всех продуктов
minOddsWagering	минимальный коэффициент для вейджеринга	double	опциональный	коэффициент в формате minor currency unit; допустимый диапазон: [0, 10000]; пример: 1.95 -> 195; не поддерживается aviatrix-fruits
maxOddsWagering	максимальный коэффициент для вейджеринга	double	опциональный	коэффициент в формате minor currency unit; допустимый диапазон: [0, 10000]; пример: 1.95 -> 195; не поддерживается aviatrix-fruits
config.isPlayable	включена ли игра с бонусного баланса	bool	обязательный	если да то можно играть с бонусного баланса
wagering.multiplier	коэффициент вейджеринга	integer	обязательный	целочисленный коэффициент для вейджеринга, например 30
wagering.useBonusMoney	влияет ли бонусный баланс на вейджеринг	bool	обязательный	если да то игра с бонусного баланса тоже влияет на вейджеринг бонуса

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
  "cid": "some-brand-id",
  "config": {
    "type": "free_bets",
    "validFrom": "2020-12-03T12:15:30.000Z",
    "validTo": "2020-12-03T12:15:30.000Z",
    "gameSettings": [
      {
      "gameId": "some-game-id",
      "minOddsWagering": 50.0,
      "maxOddsWagering": 150.0
      }
    ],
    "isPlayable": false,
    "wagering": {
      "multiplier": 10,
      "useBonusMoney": true
    }
  }
}

Parameter	Description	Type	Explanation
bonusConfigId	идентификатор бонусной конфигурации	string	уникальный идентификатор, формат uuid
cid	идентификатор бренда	string	уникальный идентификатор
config.type	тип бонусной конфигурации	string	доступные значения: free_bets
config.validFrom	начало действия бонусной конфигурации	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.validTo	конец действия бонусной конфигурации	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.gameSettings	список настроек для конкретной игры	array	настройки бонусов для конкретного типа игры; одновременно можно указать только игры одной категори: крэш игры или слот игры
gameId	идентификатор игры	string	примеры идентификаторов: nft-aviatrix, second-chance, aviatrix-fruits. С полным списком можно ознакомиться на странице всех продуктов
minOddsWagering	минимальный коэффициент для вейджеринга	double	коэффициент в формате minor currency unit; допустимый диапазон: [0, 10000]; пример: 1.95 -> 195; не поддерживается aviatrix-fruits
maxOddsWagering	максимальный коэффициент для вейджеринга	double	коэффициент в формате minor currency unit; допустимый диапазон: [0, 10000]; пример: 1.95 -> 195; не поддерживается aviatrix-fruits
config.isPlayable	включена ли игра с бонусного баланса	bool	если да то можно играть с бонусного баланса
wagering.multiplier	коэффициент вейджеринга	integer	целочисленный коэффициент для вейджеринга, например 30
wagering.useBonusMoney	влияет ли бонусный баланс на вейджеринг	bool	если да то игра с бонусного баланса тоже влияет на вейджеринг бонуса

/GetBonusConfigs

Метод используется для отображения существующих бонусных конфигураций бренда.

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/GetBonusConfigs HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "cid": "some-brand-id",
  "showActiveOnly": false
}

Parameter	Description	Type	Requirements	Explanation
cid	идентификатор бренда	string	обязательный	уникальный идентификатор
showActiveOnly	фильтрационный флаг	bool	опциональный	позволяет отобразить только активные бонусные конфигурации

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "values": [
    {
      "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
      "cid": "some-brand-id",
      "config": {
        "type": "free_bets",
        "validFrom": "2020-12-03T12:15:30.000Z",
        "validTo": "2020-12-03T12:15:30.000Z",
        "gameSettings": [
          {
          "gameId": "some-game-id",
          "minOddsWagering": 50.0,
          "maxOddsWagering": 150.0
          }
        ],
        "isPlayable": false,
        "wagering": {
          "multiplier": 10,
          "useBonusMoney": true
        }
      }
    }
  ]
}

Parameter	Description	Type	Explanation
values	список бонусных конфигураций	array	могут присутствовать просроченные, активные и неактивные бонусные конфигурации
bonusConfigId	идентификатор бонусной конфигурации	string	уникальный идентификатор, формат uuid
cid	идентификатор бренда	string	уникальный идентификатор
config.type	тип бонусной конфигурации	string	доступные значения: free_bets
config.validFrom	начало действия бонусной конфигурации	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.validTo	конец действия бонусной конфигурации	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
config.gameSettings	список настроек для конкретной игры	array	настройки бонусов для конкретного типа игры; одновременно можно указать только игры одной категори: крэш игры или слот игры
gameId	идентификатор игры	string	примеры идентификаторов: nft-aviatrix, second-chance, aviatrix-fruits. С полным списком можно ознакомиться на странице всех продуктов
minOddsWagering	минимальный коэффициент для вейджеринга	double	коэффициент в формате minor currency unit; допустимый диапазон: [0, 10000]; пример: 1.95 -> 195; не поддерживается aviatrix-fruits
maxOddsWagering	максимальный коэффициент для вейджеринга	double	коэффициент в формате minor currency unit; допустимый диапазон: [0, 10000]; пример: 1.95 -> 195; не поддерживается aviatrix-fruits
config.isPlayable	включена ли игра с бонусного баланса	bool	если да то можно играть с бонусного баланса
wagering.multiplier	коэффициент вейджеринга	integer	целочисленный коэффициент для вейджеринга, например 30
wagering.useBonusMoney	влияет ли бонусный баланс на вейджеринг	bool	если да то игра с бонусного баланса тоже влияет на вейджеринг бонуса

/CreateFreeBet

Метод используется для создания новой бонусной кампании в рамках существующей бонусной конфигурации.

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/CreateFreeBet HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "cid": "some-brand-id",
  "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
  "name": "Some Campaign Name",
  "bonus": {
    "betCount": 5,
    "currencySettings": {
      "EUR": {
        "amount": 5,
        "maxPromoWinAmount": 10000,
        "maxBetWageringAmount": 200
      },
      "USD": {
        "amount": 6,
        "maxPromoWinAmount": 12000,
        "maxBetWageringAmount": 400
      }
    },
    "validTo": "2020-12-03T12:15:30.000Z"
  }
}

Parameter	Description	Type	Requirements	Explanation
cid	идентификатор бренда	string	обязательный	уникальный идентификатор
bonusConfigId	идентификатор бонусной конфигурации	string	обязательный	уникальный идентификатор, формат uuid
name	имя бонусной кампании	string	обязательный	название бонусной кампании
bonus.betCount	количество бонусных ставок	integer	обязательный	бонусные ставки доступные игроку для игры
bonus.currencySettings	список настроек для конкретной валюты	map	обязательный	валюта бонусных ставок, формат ISO-4217-3
amount	сумма бонусной ставки	integer	обязательный	сумма в формате minor currency unit, пример: 1.95$ -> 195; не может быть меньше минимальной и больше максимальной ставки в рамках данного бренда
maxPromoWinAmount	максимальная сумма выигрыша	integer	обязательный	сумма в формате minor currency unit, пример: 1.95$ -> 195; не может быть больше максимального выигрыша в рамках данного бренда
maxBetWageringAmount	максимальная сумма для вейджеринга	integer	опциональный	сумма в формате minor currency unit, пример: 1.95$ -> 195
bonus.validTo	конец действия бонусной кампании	timestamp	обязательный	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "cid": "some-brand-id",
  "bonusConfigId": "6f41bd2a-4621-42e5-883c-647b8995684d",
  "name": "Some Campaign Name",
  "bonus": {
    "betCount": 5,
    "currencySettings": {
      "EUR": {
        "amount": 5,
        "maxPromoWinAmount": 10000,
        "maxBetWageringAmount": 200
      },
      "USD": {
        "amount": 6,
        "maxPromoWinAmount": 12000,
        "maxBetWageringAmount": 400
      }
    },
    "validTo": "2020-12-03T12:15:30.000Z"
  }
}

Parameter	Description	Type	Explanation
bonusId	идентификатор бонусной кампании	string	уникальный идентификатор бонусной кампании, формат uuid
cid	идентификатор бренда	string	уникальный идентификатор
bonusConfigId	идентификатор бонусной конфигурации	string	уникальный идентификатор, формат uuid
name	имя бонусной кампании	string	название бонусной кампании
bonus.betCount	количество бонусных ставок	integer	бонусные ставки доступные игроку для игры
bonus.currencySettings	список настроек для конкретной валюты	map	валюта бонусных ставок, формат ISO-4217-3
amount	сумма бонусной ставки	integer	сумма в формате minor currency unit, пример: 1.95$ -> 195; не может быть меньше минимальной и больше максимальной ставки в рамках данного бренда
maxPromoWinAmount	максимальная сумма выигрыша	integer	сумма в формате minor currency unit, пример: 1.95$ -> 195; не может быть больше максимального выигрыша в рамках данного бренда
maxBetWageringAmount	максимальная сумма для вейджеринга	integer	сумма в формате minor currency unit, пример: 1.95$ -> 195
bonus.validTo	конец действия бонусной кампании	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/DisableBonus

Метод используется для деактивации существующей бонусной кампании.

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/DisableBonus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	идентификатор бонусной кампании	string	обязательный	уникальный идентификатор бонусной кампании, формат uuid
cid	идентификатор бренда	string	обязательный	уникальный идентификатор

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e"
}

Parameter	Description	Type	Explanation
bonusId	идентификатор бонусной кампании	string	уникальный идентификатор бонусной кампании, формат uuid

/AssignBonus

Метод используется для начисления бонусов конкретным игрокам

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/AssignBonus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "playerIds": ["player1", "player2", "player3"],
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	идентификатор бонусной кампании	string	обязательный	уникальный идентификатор бонусной кампании, формат uuid
playerIds	список идентификаторов игроков	array of strings	обязательный	игроки, которым необходимо выдать бонус в рамках указанной бонусной кампании
cid	идентификатор бренда	string	обязательный	уникальный идентификатор

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "bonusJobId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "status": "pending",
  "createdAt": "2020-12-03T12:15:30.000Z"
}

Parameter	Description	Type	Explanation
bonusJobId	идентификатор процесса	string	уникальный идентификатор процесса по начислению или лишению бонусов у игроков, формат uuid
bonusId	идентификатор бонусной кампании	string	уникальный идентификатор бонусной кампании, формат uuid
status	статус выполнения процесса	string	возможные значения: pending, completed, failed
createdAt	время старта выполнения процесса	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/GetAssignBonusStatus

Метод используется для получения статуса процесса по начислению бонусов игрокам

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/GetAssignBonusStatus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "jobBonusAssignmentId": "99999",
  "cid": "123"
}

Parameter	Description	Type	Requirements	Explanation
jobBonusAssignmentId	идентификатор процесса	string	обязательный	уникальный идентификатор процесса по начислению или лишению бонусов у игроков, формат uuid
cid	идентификатор бренда	string	обязательный	уникальный идентификатор

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "bonusJobId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "status": "pending",
  "createdAt": "2020-12-03T12:15:30.000Z"
}

Parameter	Description	Type	Explanation
bonusJobId	идентификатор процесса	string	уникальный идентификатор процесса по начислению или лишению бонусов у игроков, формат uuid
bonusId	идентификатор бонусной кампании	string	уникальный идентификатор бонусной кампании, формат uuid
status	статус выполнения процесса	string	возможные значения: pending, completed, failed
createdAt	время старта выполнения процесса	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/RevokeBonus

Метод используется для выключения бонусов конкретным игрокам

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/RevokeBonus HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "playerIds": ["player1", "player2", "player3"],
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	идентификатор бонусной кампании	string	обязательный	уникальный идентификатор бонусной кампании, формат uuid
playerIds	список идентификаторов игроков	array of strings	обязательный	игроки, у которых необходимо отозвать выданный ранее бонус
cid	идентификатор бренда	string	обязательный	уникальный идентификатор

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "bonusJobId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "status": "pending",
  "createdAt": "2020-12-03T12:15:30.000Z"
}

Parameter	Description	Type	Explanation
bonusJobId	идентификатор процесса	string	уникальный идентификатор процесса по начислению или лишению бонусов у игроков, формат uuid
bonusId	идентификатор бонусной кампании	string	уникальный идентификатор бонусной кампании, формат uuid
status	статус выполнения процесса	string	возможные значения: pending, completed, failed
createdAt	время старта выполнения процесса	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339

/GetPlayerBonusAssignment

Метод используется для отображения статуса бонуса у конкретных игроков

Пример запроса

Внимание

Заголовки запроса, указанные в примере, обязательны: Accept, Content-Type, X-Auth-Signature

POST /bonus/v1/GetPlayerBonusAssignment HTTP/1.1
Content-Type: application/json
Accept: application/json
X-Auth-Signature: <signature>

{
  "bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e",
  "playerIds": ["player1", "player2", "player3"],
  "cid": "some-brand-id"
}

Parameter	Description	Type	Requirements	Explanation
bonusId	идентификатор бонусной кампании	string	обязательный	уникальный идентификатор бонусной кампании, формат uuid
playerIds	список идентификаторов игроков	array of strings	обязательный	игроки, у которых хотим узнать статус указанной бонусной кампании
cid	идентификатор бренда	string	обязательный	уникальный идентификатор

Пример ответа от сервера

HTTP/1.1 200 OK
{
  "assignments": [
    {
      "playerBonusAssignmentId": "71ac9c1b-faa7-4b77-ba49-beed09f3fb00",
      "playerId": "player1",
      "createdAt": "2025-06-11T16:48:55Z",
      "validTo": "2020-12-03T12:15:30.000Z",
      "freeBet": {
        "betCountPlaced": 5,
        "betCountLimit": 10,
        "status": "active"
      }
    }
  ]
}

Parameter	Description	Type	Explanation
assignments	список статусов бонуса для игроков	array	список, в котором показано актуальное состояние бонуса для каждого игрока переданного в запросе
playerBonusAssignmentId	идентификатор назначения бонуса юзеру	string	уникальный идентификатор связи бонус-игрок, формат uuid
playerId	идентификатор игрока	string	идентификатор игрока на стороне партнера
createdAt	время начисления бонуса игроку	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
validTo	конец действия бонуса у игрока	timestamp	формат: yyyy-MM-dd’T’HH:mm:ss.SSSZ / RFC3339
freeBet.betCountPlaced	количество сыгранных бонусных ставок	integer	количество бонусных ставок, которые игрок уже сыграл на данный момент
freeBet.betCountLimit	количество бонусных ставок выданных игроку	integer	количество бонусных ставок, которые игроку были выданы в рамках бонусной кампании
freeBet.status	статус вейджеринга бонусных ставок у игрока	string	возможные значения: preassigned, pending, active, wagering, completed, expired, deassigned, unwagered, canceled

Bonus API обработка ошибок

В общем случае при возникновении ошибки сервер провайдера будет возвращать ответ в формате:

{
  "code": 400,
  "message": "error text"
}

Описание ошибок

HTTP Status	Текст ошибки	Повторная отправка	Описание
400	Bad request: playerIds array exceeds 100 elements	No	В списке игроков playerIds не должно быть больше 100 элементов.
400	Bad request: betCount must be non-negative	No	Значение betCount не должно быть отрицательным.
400	Bad request: bonus is disabled	No	Попытка выдать игрокам выключенный бонус.
400	Missing required field	No	Одно или несколько необходимых полей отсутствует в запросе.
400	Invalid request	No	Общая ошибка валидации запроса. Пожалуйста, обратитесь к тех поддержке провайдера.
404	Bonus not found	No	Указанное значение bonusId не было найдено в базе.
404	Job bonus assignment not found	No	Указанное значение jobBonusAssignment не было найдено в базе.
404	Bonus config not found	No	Указанное значение bonusConfigId не было найдено в базе.
429	Too many requests	Yes	Клиент послал слишком много запросов за определенный промежуток времени. Троттлинг в действии.
429	Monthly quota reached: create free bet. Contact your integration manager.	Yes	Достигнут месячный лимит для создания фрибет бонуса.
429	Monthly quota reached: assign bonus. Contact your integration manager.	Yes	Достигнут месячный лимит для выдачи фрибет бонуса игрокам.
500	Internal server error	Yes	Неожиданная ошибка от сервера. Если она не уходит после нескольких попыток, обратитесь к тех поддержке провайдера.