跳至主要内容

批次發送 FreeSpin 平台卡

發送 FREE SPIN 卡給指定玩家，支援多玩家多遊戲一次發送
補充：FREE SPIN 卡 : 免費旋轉卡、乘倍免費旋轉卡（cardType 1, 2）

API 信息​

  • 端點：POST /v2/items/usesimplefreespin/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_230001_1", "VP_230002_1"],
  "spinIds": [
    "spin_alice_g1_0001",
    "spin_alice_g2_0002",
    "spin_bob_g1_0003",
    "spin_bob_g2_0004"
  ],
  "round": 10,
  "itemBet": 100,
  "multiple": 2,
  "maxWinAmount": 5000,
  "expiredTime": "2026-04-30T12:00:00.000Z"
}
欄位類型必填說明
usernamesstring Array是玩家帳號
gameCodesstring Array是遊戲代碼
spinIdsstring Array否平台卡唯一識別碼，未填則由系統自動生成
roundnumber是回合數，必須為整數，下限 1，上限為 100
maxWinAmountnumber否最大贏得金額
itemBetnumber否平台卡下注金額，可參照 BetList 填寫，若未填寫則預設使用最小 Bet
multiplenumber否免費旋轉倍數，可填 1/2/3/5 倍，若未填寫則預設使用1倍
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重新確認參數規則或聯繫客服團隊
89The item has not been used yet, or the spinId does not exist重新確認道具已使用或是道具已過期不存在

錯誤響應範例​

平台卡參數組合錯誤​

{
    "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 發送成功的每一個 FREE SPIN 卡為當下立即生效
  4. 局部發送性：不會因為部分道具發送不成功則導致此批道具全部無法發送

常見 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​