批次发送 FreeSpin 平台卡
发送 FREE SPIN 卡给指定玩家，支援多玩家多游戏一次发送
補充：FREE SPIN 卡 : 免费旋转卡、乘倍免费旋转卡（cardType 1, 2）
API 信息
- 端点：
POST /v2/items/usesimplefreespin/batch - 认证：Bearer Token
- 加密：请求使用 AES-256-GCM 加密，响应为明文 JSON
请求
请求标头
POST /v2/items/use HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-agentid: integratorNBTest04
x-timestamp: 1769746894501
x-nonce: 56ffd5ecd8a3a4457863a0bd7c298fb2
x-signature: 904e97bee2589b93e9747eed0346c68b23d8ff8b568dabaf4b94a5e89093df67
请求参数
解密后 Request
{
"cipherText": "G0ZMDELeJwx+7JcIfIFOLJjkSzANPu6krGM2uw==..."
}
加密前的参数
{
"usernames": ["alice01", "bob02"],
"gameCodes": ["VP_230001_1", "VP_230002_1"],
"spinIds": [
"spin_alice_g1_0001",
"spin_alice_g2_0002",
"spin_bob_g1_0003",
"spin_bob_g2_0004"
],
"round": 10,
"itemBet": 100,
"multiple": 2,
"maxWinAmount": 5000,
"expiredTime": "2026-04-30T12:00:00.000Z"
}
| 欄位 | 类型 | 必填 | 说明 |
|---|---|---|---|
usernames | string Array | 是 | 玩家账号 |
gameCodes | string Array | 是 | 游戏代码 |
spinIds | string Array | 否 | 平台卡唯一識别码，未填则由系统自动生成 |
round | number | 是 | 回合数，上限为 100 |
maxWinAmount | number | 否 | 最大贏得金额 |
itemBet | number | 否 | 平台卡下注金额，可参照 BetList 填写，若未填写则预设使用最小 Bet |
multiple | number | 否 | 免费旋转倍数，可填 1/2/3/5 倍，若未填写则预设使用1倍 |
expiredTime | string | 否 | 卡片过期时间 |
响应
成功响应
{
"code": 0,
"message": "No error.",
"data": {
"successList": [
{
"username": "alice01",
"gameCode": "VP_230001_1",
"spinId": "spin_alice_g1_0001",
"code": 0,
"message": "No error.",
"itemId": "generated-item-id1"
},
{
"username": "alice01",
"gameCode": "VP_230003_1",
"spinId": "spin_alice_g1_0001",
"code": 0,
"message": "No error.",
"itemId": "generated-item-id2"
}
],
"failedList": [
{
"username": "bob02",
"gameCode": "VP_230001_1",
"spinId": "spin_bob_g2_0004",
"code": 8,
"message": "The User is not exist"
},
{
"username": "bob02",
"gameCode": "VP_230003_1",
"spinId": "spin_bob_g2_0004",
"code": 8,
"message": "The User is not exist"
}
]
},
"logUUID": "c6a85c7b-6108-4c88-95fb-fd79a1bda0a1"
}
| 欄位 | 类型 | 说明 |
|---|---|---|
code | number | 响应代码，0 表示成功 |
message | string | 响应讯息 |
data.successList | Object Array | 道具发送成功清单 |
data.failedList | Object Array | 道具发送失敗清单 |
logUUID | string | 请求追蹤 ID，用于问题排查和日誌查询 |
- 道具发送清单参数说明
| 欄位 | 类型 | 说明 |
|---|---|---|
username | number | 玩家账号 |
gameCode | string | 游戏代码 |
spinId | string | 平台卡唯一識别码 |
code | number | 道具发送结果响应代码 |
message | string | 道具发送结果响应讯息 |
itemId | string | 系统內平台卡 ID，仅在道具成功发送清单产生 |
错误响应
错误代码
| 状态码 | 说明 | 处理建议 |
|---|---|---|
| 5 | Game is not found | 游戏不存在、已下线或不支援该币别，请确认 gameCode 是否正确 |
| 8 | The User is not exist | 会员不存在，请先創建会员 |
| 78 | Operator card spinId was used | 请更换 spinId，若有疑问则聯絡客服处理 |
| 86 | Game is restricted | 请参考游戏列表文件或询问客服 |
| 87 | Invalid item parameter value | 重新确认参数规则或聯繫客服团队 |
| 88 | Only one item can be active at a time in the same game | 请玩家重新进入对应游戏使用后再发送 |
| 89 | The item has not been used yet, or the spinId does not exist | 重新确认道具已使用或是道具已过期不存在 |
错误响应范例
平台卡参数组合错误
{
"code": 11,
"message": "spinIds length must match usernames x gameCodes combinations",
"logUUID": "2b82cfaf-d6ad-48fa-9963-4d91639b9b31"
}
注意事项
- spinId 唯一性：每个 spinId 必须唯一，不可重复使用
- spinId 全对性：若带入 spinId，则必须与「玩家账号」x「游戏代码」数量可对上，否则会觸发错误
- 立即生效性：此 API 发送成功的每一个 FREE SPIN 卡为当下立即生效
- 局部发送性：不会因为部分道具发送不成功则导致此批道具全部无法发送
常見 QA
Q1: 该 API 发送 FREE SPIN 是否有过期时间?
A: 发送后，若是玩家一直未登入游戏使用，发送后的 12 小时将自动结算
Q2: 该 API 发送 FREE SPIN 是否可以取消?
A: 可以，可透过 取消平台卡 API 取消，但需要在玩家尚未进入游戏使用前或自动结算前，否则将不可取消
Q3: 自动结算后是否会告知玩家?
A: 玩家登入游戏会显示提醒奖励讯息，但不会重新展示表演动畫
Q4: 若过期时间到了平台卡会自动结算还是取消?
A: 取消，且该平台卡 spinId 将无法再復用，后台与注单纪录将无此筆资料
Q5: 若玩家于游戏动畫中离开游戏，FREE SPIN 是否会自动结算?
A: 玩家中途退出再回到游戏将会繼续完成，全数使用完畢才结算。