批次發送 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"
}
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
usernames | string Array | 是 | 玩家帳號 |
gameCodes | string Array | 是 | 遊戲代碼 |
spinIds | string Array | 否 | 平台卡唯一識別碼，未填則由系統自動生成 |
round | number | 是 | 回合數，上限為 100 |
maxWinAmount | number | 否 | 最大贏得金額 |
itemBet | number | 否 | 平台卡下注金額，可參照 BetList 填寫，若未填寫則預設使用最小 Bet |
multiple | number | 否 | 免費旋轉倍數，可填 1/2/3/5 倍，若未填寫則預設使用1倍 |
expiredTime | string | 否 | 卡片過期時間 |
響應
成功響應
{
"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"
}
| 欄位 | 類型 | 說明 |
|---|---|---|
code | number | 響應代碼，0 表示成功 |
message | string | 響應訊息 |
data.successList | Object Array | 道具發送成功清單 |
data.failedList | Object Array | 道具發送失敗清單 |
logUUID | string | 請求追蹤 ID，用於問題排查和日誌查詢 |
- 道具發送清單參數說明
| 欄位 | 類型 | 說明 |
|---|---|---|
username | number | 玩家帳號 |
gameCode | string | 遊戲代碼 |
spinId | string | 平台卡唯一識別碼 |
code | number | 道具發送結果響應代碼 |
message | string | 道具發送結果響應訊息 |
itemId | string | 系統內平台卡 ID，僅在道具成功發送清單產生 |
錯誤響應
錯誤代碼
| 狀態碼 | 說明 | 處理建議 |
|---|---|---|
| 5 | Game is not found | 遊戲不存在、已下線或不支援該幣別，請確認 gameCode 是否正確 |
| 8 | The User is not exist | 會員不存在，請先創建會員 |
| 78 | Operator card spinId was used | 請更換 spinId，若有疑問則聯絡客服處理 |
| 86 | Game is restricted | 請參考遊戲列表文件或詢問客服 |
| 87 | Invalid item parameter value | 重新確認參數規則或聯繫客服團隊 |
| 88 | Only one item can be active at a time in the same game | 請玩家重新進入對應遊戲使用後再發送 |
| 89 | The 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"
}
注意事項
- spinId 唯一性：每個 spinId 必須唯一，不可重複使用
- spinId 全對性：若帶入 spinId，則必須與「玩家帳號」x「遊戲代碼」數量可對上，否則會觸發錯誤
- 立即生效性：此 API 發送成功的每一個 FREE SPIN 卡為當下立即生效
- 局部發送性：不會因為部分道具發送不成功則導致此批道具全部無法發送
常見 QA
Q1: 該 API 發送 FREE SPIN 是否有過期時間?
A: 發送後，若是玩家一直未登入遊戲使用，發送後的 12 小時將自動結算
Q2: 該 API 發送 FREE SPIN 是否可以取消?
A: 可以，可透過 取消平台卡 API 取消，但需要在玩家尚未進入遊戲使用前或自動結算前，否則將不可取消
Q3: 自動結算後是否會告知玩家?
A: 玩家登入遊戲會顯示提醒獎勵訊息，但不會重新展示表演動畫
Q4: 若過期時間到了平台卡會自動結算還是取消?
A: 取消，且該平台卡 spinId 將無法再復用，後台與注單紀錄將無此筆資料
Q5: 若玩家於遊戲動畫中離開遊戲，FREE SPIN 是否會自動結算?
A: 玩家中途退出再回到遊戲將會繼續完成，全數使用完畢才結算。