Перейти к основному содержимому

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

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
}
}
}
ParameterDescriptionTypeRequirementsExplanation
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
}
}
}
ParameterDescriptionTypeExplanation
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
}
ParameterDescriptionTypeRequirementsExplanation
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
}
}
}
]
}
ParameterDescriptionTypeExplanation
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"
}
}
ParameterDescriptionTypeRequirementsExplanation
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"
}
}
ParameterDescriptionTypeExplanation
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"
}
ParameterDescriptionTypeRequirementsExplanation
bonusIdидентификатор бонусной кампанииstringобязательныйуникальный идентификатор бонусной кампании, формат uuid
cidидентификатор брендаstringобязательныйуникальный идентификатор

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

HTTP/1.1 200 OK
{
"bonusId": "00ed751a-a2ec-4077-beb0-db2cb795894e"
}
ParameterDescriptionTypeExplanation
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"
}
ParameterDescriptionTypeRequirementsExplanation
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"
}
ParameterDescriptionTypeExplanation
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"
}
ParameterDescriptionTypeRequirementsExplanation
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"
}
ParameterDescriptionTypeExplanation
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"
}
ParameterDescriptionTypeRequirementsExplanation
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"
}
ParameterDescriptionTypeExplanation
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"
}
ParameterDescriptionTypeRequirementsExplanation
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"
}
}
]
}
ParameterDescriptionTypeExplanation
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Текст ошибкиПовторная отправкаОписание
400Bad request: playerIds array exceeds 100 elementsNoВ списке игроков playerIds не должно быть больше 100 элементов.
400Bad request: betCount must be non-negativeNoЗначение betCount не должно быть отрицательным.
400Bad request: bonus is disabledNoПопытка выдать игрокам выключенный бонус.
400Missing required fieldNoОдно или несколько необходимых полей отсутствует в запросе.
400Invalid requestNoОбщая ошибка валидации запроса. Пожалуйста, обратитесь к тех поддержке провайдера.
404Bonus not foundNoУказанное значение bonusId не было найдено в базе.
404Job bonus assignment not foundNoУказанное значение jobBonusAssignment не было найдено в базе.
404Bonus config not foundNoУказанное значение bonusConfigId не было найдено в базе.
429Too many requestsYesКлиент послал слишком много запросов за определенный промежуток времени. Троттлинг в действии.
429Monthly quota reached: create free bet. Contact your integration manager.YesДостигнут месячный лимит для создания фрибет бонуса.
429Monthly quota reached: assign bonus. Contact your integration manager.YesДостигнут месячный лимит для выдачи фрибет бонуса игрокам.
500Internal server errorYesНеожиданная ошибка от сервера. Если она не уходит после нескольких попыток, обратитесь к тех поддержке провайдера.