发送 FreeSpin 平台卡
发送 FREE SPIN 卡给指定玩家
補充：FREE SPIN 卡 : 免费旋转卡、乘倍免费旋转卡（cardType 1, 2）
API 信息
- 端点：
POST /v2/items/usesimplefreespin - 认证：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==..."
}
加密前的参数
{
"username": "VPSysDevTest001",
"spinId": "SystemItemTestTrans150",
"gameCode": "VP_230001_1",
"round": 3,
"maxWinAmount": 10,
"itemBet": 2,
"multiple": 1,
"expiredTime": "2026-04-12T00:00:00.000Z"
}
| 欄位 | 类型 | 必填 | 说明 |
|---|---|---|---|
username | string | 是 | 玩家账号 |
spinId | string | 是 | 平台卡唯一識别码 |
gameCode | string | 是 | 游戏代码 |
round | number | 是 | 回合数，上限为 100 |
maxWinAmount | number | 否 | 最大贏得金额 |
itemBet | number | 否 | 平台卡下注金额，可参照 BetList 填写，若未填写则预设使用最小 Bet |
multiple | number | 否 | 免费旋转倍数，可填 1/2/3/5 倍，若未填写则预设使用1倍 |
expiredTime | string | 否 | 卡片过期时间 |
响应
成功响应
{
"code": 0,
"message": "No error.",
"data": {
"itemId": "f2cb520579c8014452d6f521693a4aa8_VPItemTestTrans1042_ghjklhtombg"
},
"logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
| 欄位 | 类型 | 说明 |
|---|---|---|
code | number | 响应代码，0 表示成功 |
message | string | 响应讯息 |
data.itemId | string | 系统內平台卡 ID |
logUUID | 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": 87,
"message": "Invalid item parameter value",
"logUUID": "c6a85c7b-6108-4c88-95fb-fd79a1bda0a1"
}
平台卡 ID 重复使用
{
"code": 78,
"message": "The spinID was used",
"logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
注意事项
- spinId 唯一性：每个 spinId 必须唯一，不可重复使用
- 立即生效性：此 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: 玩家中途退出再回到游戏将会繼续完成，全数使用完畢才结算。