跳到主要内容

发送簡易 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
}
欄位类型必填说明
usernamestring是玩家账号
spinIdstring是平台卡唯一識别码
gameCodestring是游戏代码
roundnumber是回合数
maxWinAmountnumber否最大贏得金额
itemBetnumber否平台卡下注金额，可参照 BetList 填写，若未填写则预设使用最小 Bet
multiplenumber否免费旋转倍数，可填 1/2/3/5 倍，若未填写则预设使用1倍

响应​

成功响应​

{
   "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请参考游戏列表文件或询问客服

错误响应范例​

平台卡参数组合错误​

{
   "code": 7,
   "message": "Internal server error",
   "error": "{\"retStatus\":{\"StatusCode\":80013,\"StatusMsg\":\"RiskInfoError\",\"CheckCode\":0,\"SystemTime\":1760348424576}}",
   "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}

平台卡 ID 重复使用​

{
   "code": 78,
   "message": "The spinID was used",
   "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}

注意事项​

  1. spinId 唯一性：每个 spinId 必须唯一，不可重复使用
  2. 立即生效性：此 API 发送 FREE SPIN 卡为当下立即生效

常見 QA​

Q1: 发送参数中的的 itemBet 列表要如何取得?​

A: 透过 查询平台卡资讯 可查询完整支援清单，也可以隨意带入，我方会自动选择该游戏 betList 中最接近该值且较低 bet 发送

Q2: 该 API 发送 Free Spin 是否有过期时间?​

A: 发送后，若是玩家一直未登入游戏使用，发送后的 12 小时将自动结算

Q3: 该 API 发送 Free Spin 是否可以取消?​

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

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

A: 玩家登入游戏会显示提醒奖励讯息，但不会重新展示表演动畫

相关 API​