跳到主要内容

发送 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重新确认参数规则或联系客服团队
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: 有，过期时间由 expiredTime 参数指定。未使用的卡片将于过期时间直接失效；自动结算仅在玩家于游戏中开始使用卡片后才会发生

Q2: 该 API 发送 FREE SPIN 是否可以取消?​

A: 可以，可透过 取消平台卡 API 取消，但需要在玩家尚未进入游戏使用前或自动结算前，否则将不可取消

Q3: 自动结算后是否会告知玩家?​

A: 玩家登入游戏会显示提醒奖励讯息，但不会重新展示表演动画，若多笔纪录结算则仅显示最后一笔结算纪录

Q4: 若过期时间到了平台卡会自动结算还是取消?​

A: 过期时间到时，未使用的卡片将直接失效，该平台卡 spinId 将无法再复用，后台与注单纪录将无此笔资料

Q5: 若玩家于游戏动画中离开游戏，FREE SPIN 是否会自动结算?​

A: 玩家中途退出再回到游戏将会继续完成，全数使用完毕才结算；若玩家已使用到一半、卡在剩余场次未完成，则满 12 小时后才会自动结算

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

A: expiredTime 为必填，过期与失效时间一律自发送当下起算，与玩家是否登入无关。未使用的卡片于过期时间直接失效；自动结算仅在玩家于游戏中开始使用后才会发生，FREE SPIN 若卡在剩余场次未完成，将于满 12 小时后自动结算

相关 API​