跳至主要内容

發送簡易 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​