> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igamingace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bonus Call Register

注册接口会为指定玩家启动一次奖金活动。你需要指定是免费旋转奖金（预定义免费旋转）还是常规奖金回调（保证中奖金额）。每位玩家同一时间只能有一个进行中的奖金回调。奖金在任一已配置游戏中完成后，不会再在同一次注册的其他游戏中触发。

## Request

**Endpoint:** `POST /v1/bonus-call/register`

**Headers**

| Name            | Value                |
| :-------------- | :------------------- |
| `Authorization` | `Bearer <API_TOKEN>` |
| `Content-Type`  | `application/json`   |
| `Accept`        | `application/json`   |

### Request body

<ParamField body="platformId" type="string" required>
  您为此奖励请求自定义的唯一标识符。
</ParamField>

<ParamField body="providerId" type="number" required>
  奖励生效所属游戏供应商的数字 ID。
</ParamField>

<ParamField body="gameId" type="number" required>
  指定哪些游戏可触发该奖励事件。
</ParamField>

<ParamField body="playerId" type="string" required>
  玩家在您系统中的唯一标识符。
</ParamField>

<ParamField body="bonusType" type="number" required>
  要注册的奖金类型。

  * `1` — Free Spin Bonus. 玩家会获得固定次数的免费旋转；`callAmount` 作为最高可赢上限。仅适用于 Pragmatic Play。
  * `2` — Regular Bonus Call. 活动结束时，玩家保证赢得 `callAmount`。该常规奖金目前未启用；当前仅支持免费旋转奖金。
</ParamField>

<ParamField body="callAmount" type="number" required>
  与奖金关联的货币金额。

  * `bonusType = 1`: 玩家在所有免费旋转中可赢的最高金额。
  * `bonusType = 2`: 玩家将精确赢得该金额。
</ParamField>

<ParamField body="expireAt" type="string" required>
  奖金过期的时间戳，格式为 `YYYY-MM-DD HH:mm:ss`（例如：`"2026-12-01 23:59:59"`）。
</ParamField>

<ParamField body="metaData" type="object">
  附加配置，用于加成。当 `bonusType = 1` 时必填。

  <Expandable title="metaData fields">
    <ParamField body="metaData.spinAmount" type="number" required>
      发放的免费旋转次数。最小值：`1`，最大值：`100`。
    </ParamField>

    <ParamField body="metaData.baseBetAmount" type="number" required>
      基础投注金额。例如：对于 2 美元的免费旋转，请使用 `baseBetAmount: 2`
    </ParamField>
  </Expandable>
</ParamField>

### Example request

```bash theme={null}
curl --request POST \
  --url https://api.igamingace.com/v1/bonus-call/register \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "issueId": "promo_oct_001",
    "providerId": 1,
    "gameId": 655,
    "playerId": "player_88888",
    "bonusType": 1,
    "callAmount": 500,
    "expireAt": "2026-12-01 23:59:59",
    "metaData": {
      "spinAmount": 20,
      "baseBetAmount": 2
    }
  }'
```

<Note>
  对于常规奖励调用（`bonusType = 2`），可以完全省略 metaData。对于免费旋转奖励（`bonusType = 1`），则必须同时提供 `metaData.spinAmount` 和 `metaData.baseBetAmount`。
</Note>

***

## Response

成功时，API 会返回你应保存的 issueId，以便之后跟踪或取消该奖金。

<ResponseField name="success" type="bool">
  `true` 表示 API 调用已成功处理且无错误。
</ResponseField>

<ResponseField name="message" type="string">
  一段简短的确认字符串，通常为 `"OK"`。
</ResponseField>

<ResponseField name="data" type="object">
  结果载荷。

  <Expandable title="data fields">
    <ResponseField name="data.issueId" type="long">
      已登记奖金调用的唯一标识符。请保存该值——你需要用它来查询状态或取消该奖金。
    </ResponseField>
  </Expandable>
</ResponseField>

### Example response

```json theme={null}
{
  "success": true,
  "message": "OK",
  "data": {
    "issueId": 10001
  }
}
```