跳至主要内容

發送 FeatureGame 平台卡

發送 FEATURE GAME 卡給指定玩家
補充：FEATURE GAME 卡 : 一般特色遊戲卡、強力特色遊戲卡、超強力特色遊戲卡

API 信息​

  • 端點：POST /v2/items/usesimplefeaturegame
  • 認證：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",
   "cardType": 11,
   "itemBet": 2,
   "maxWinAmount": 10,
   "expiredTime": "2026-04-12T00:00:00.000Z"
}
欄位類型必填說明
usernamestring是玩家帳號
spinIdstring是平台卡唯一識別碼
gameCodestring是遊戲代碼
cardTypenumber是卡片類型，可用參數 11, 21, 22
itemBetnumber否平台卡下注金額，可參照 BetList 填寫，若未填寫則預設使用最小 Bet
maxWinAmountnumber否最大贏得金額
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 發送 FEATURE GAME 卡為當下立即生效

常見 QA​

Q1: 該 API 發送 FEATURE GAME 是否有過期時間?​

A: 有，過期時間由 expiredTime 參數指定。未使用的卡片將於過期時間直接失效；自動結算僅在玩家於遊戲中開始使用卡片後才會發生

Q2: 該 API 發送 FEATURE GAME 是否可以取消?​

A: 可以，可透過 取消平台卡 API 取消，但需要在玩家尚未進入遊戲使用前或自動結算前，否則將不可取消

Q3: 自動結算後是否會告知玩家?​

A: 玩家登入遊戲會顯示提醒獎勵訊息，但不會重新展示表演動畫，若多筆紀錄結算則僅顯示最後一筆結算紀錄

Q4: 若過期時間到了平台卡會自動結算還是取消?​

A: 過期時間到時，未使用的卡片將直接失效，該平台卡 spinId 將無法再復用，後台與注單紀錄將無此筆資料

Q5: 若玩家於遊戲動畫中離開遊戲，FEATURE GAME 是否會自動結算?​

A: 會，玩家遊玩到一半離開遊戲時將立即結算

Q6: 卡片過期時間 "expiredTime" 與自動結算互動邏輯?​

A: expiredTime 為必填，過期與失效時間一律自發送當下起算，與玩家是否登入無關。未使用的卡片於過期時間直接失效；自動結算僅在玩家於遊戲中開始使用後才會發生，FEATURE GAME 於玩家遊玩到一半離開時立即結算

相關 API​