跳到主要内容

发送 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"
}
栏位类型必填说明
usernamestring是玩家账号
spinIdstring是平台卡唯一识别码
gameCodestring是游戏代码
roundnumber是回合数，必须为整数，下限 1，上限为 100
maxWinAmountnumber否最大赢得金额
itemBetnumber否平台卡下注金额，可参照 BetList 填写，若未填写则预设使用最小 Bet
multiplenumber否免费旋转倍数，可填 1/2/3/5 倍，若未填写则预设使用1倍
expiredTimestring否卡片过期时间

响应​

成功响应​

{
   "code": 0,
   "message": "No error.",
   "data": {
       "itemId": "f2cb520579c8014452d6f521693a4aa8_VPItemTestTrans1042_ghjklhtombg"
   },
   "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
栏位类型说明
codenumber响应代码，0 表示成功
messagestring响应讯息
data.itemIdstring系统内平台卡 ID
logUUIDstring请求追踪 ID，用于问题排查和日志查询

错误响应​

错误代码​

状态码说明处理建议
5Game is not found游戏不存在、已下线或不支援该币别，请确认 gameCode 是否正确
8The User is not exist会员不存在，请先创建会员
78Operator card spinId was used请更换 spinId，若有疑问则联络客服处理
86Game is restricted请参考游戏列表文件或询问客服
87Invalid item parameter value重新确认参数规则或联系客服团队
88Only one item can be active at a time in the same game请玩家重新进入对应游戏使用后再发送
89The 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"
}

注意事项​

  1. spinId 唯一性：每个 spinId 必须唯一，不可重复使用
  2. 立即生效性：此 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: 玩家中途退出再回到游戏将会继续完成，全数使用完毕才结算。

Q6: 卡片过期时间 "expiredTime" 与自动结算互动逻辑?​

A: 过期与失效时间一律自发送当下起算，与玩家是否登入、是否使用卡片无关。过期时间预设为 12 小时，即使 expiredTime 设定超过发送当下 12 小时，也会回缩为 12 小时；若 expiredTime 设定在 12 小时以内，则以该设定时间为失效时间，时间到期自动失效

相关 API​