跳到主要内容

批次发送 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​