跳至主要内容

批次發送 FeatureGame 平台卡

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

API 信息​

  • 端點：POST /v2/items/usesimplefeaturegame/batch
  • 認證：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==..."
}

加密前的參數​

{
  "usernames": ["alice01", "bob02"],
  "gameCodes": ["VP_240001_1", "VP_240002_1"],
  "spinIds": [
    "fg_alice_g1_0001",
    "fg_alice_g2_0002",
    "fg_bob_g1_0003",
    "fg_bob_g2_0004"
  ],
  "cardType": 11,
  "itemBet": 50,
  "maxWinAmount": 3000,
  "expiredTime": "2026-04-30T12:00:00.000Z"
}
欄位類型必填說明
usernamesstring Array是玩家帳號
gameCodesstring Array是遊戲代碼
spinIdsstring Array否平台卡唯一識別碼，未填則由系統自動生成
cardTypenumber是卡片類型
itemBetnumber否平台卡下注金額，可參照 BetList 填寫，若未填寫則預設使用最小 Bet
maxWinAmountnumber否最大贏得金額
expiredTimestring否卡片過期時間

響應​

成功響應​

{
  "code": 0,
  "message": "No error.",
  "data": {
    "successList": [
      {
        "username": "alice01",
        "gameCode": "VP_230001_1",
        "spinId": "spin_alice_g1_0001",
        "code": 0,
        "message": "No error.",
        "itemId": "generated-item-id1"
      },
      {
        "username": "alice01",
        "gameCode": "VP_230003_1",
        "spinId": "spin_alice_g1_0001",
        "code": 0,
        "message": "No error.",
        "itemId": "generated-item-id2"
      }
    ],
    "failedList": [
      {
        "username": "bob02",
        "gameCode": "VP_230001_1",
        "spinId": "spin_bob_g2_0004",
        "code": 8,
        "message": "The User is not exist"
      },
      {
        "username": "bob02",
        "gameCode": "VP_230003_1",
        "spinId": "spin_bob_g2_0004",
        "code": 8,
        "message": "The User is not exist"
      }
    ]
  },
  "logUUID": "c6a85c7b-6108-4c88-95fb-fd79a1bda0a1"
}
欄位類型說明
codenumber響應代碼，0 表示成功
messagestring響應訊息
data.successListObject Array道具發送成功清單
data.failedListObject Array道具發送失敗清單
logUUIDstring請求追蹤 ID，用於問題排查和日誌查詢
  • 道具發送清單參數說明
欄位類型說明
usernamenumber玩家帳號
gameCodestring遊戲代碼
spinIdstring平台卡唯一識別碼
codenumber道具發送結果響應代碼
messagestring道具發送結果響應訊息
itemIdstring系統內平台卡 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重新確認道具已使用或是道具已過期不存在

錯誤響應範例​

spinId 數與道具組合不匹配​

{
    "code": 11,
    "message": "spinIds length must match usernames x gameCodes combinations",
    "logUUID": "2b82cfaf-d6ad-48fa-9963-4d91639b9b31"
}

注意事項​

  1. spinId 唯一性：每個 spinId 必須唯一，不可重複使用
  2. spinId 全對性：若帶入 spinId，則必須與「玩家帳號」x「遊戲代碼」數量可對上，否則會觸發錯誤
  3. 立即生效性：此 API 發送成功的每一個 FEATURE GAME 卡為當下立即生效
  4. 局部發送性：不會因為部分道具發送不成功則導致此批道具全部無法發送

常見 QA​

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

A: 發送後，若是玩家一直未登入遊戲使用，發送後的 12 小時將自動結算

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

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

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

A: 玩家登入遊戲會顯示提醒獎勵訊息，但不會重新展示表演動畫

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

A: 取消，且該平台卡 spinId 將無法再復用，後台與注單紀錄將無此筆資料

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

A: 自動結算

相關 API​