跳到主要内容

批次发送 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是卡片类型，可用参数 11, 21, 22
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重新确认参数规则或联系客服团队
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: 有，过期时间由 expiredTime 参数指定。未使用的卡片将于过期时间直接失效；自动结算仅在玩家于游戏中开始使用卡片后才会发生

Q2: 该 API 发送 FEATURE GAME 是否可以取消?​

A: 可以，可透过 取消平台卡 API 取消，但需要在玩家尚未进入游戏使用前或自动结算前，否则将不可取消

Q3: 自动结算后是否会告知玩家?​

A: 玩家登入游戏会显示提醒奖励讯息，但不会重新展示表演动画，若多笔纪录结算则仅显示最后一笔结算纪录

Q4: 若过期时间到了平台卡会自动结算还是取消?​

A: 过期时间到时，未使用的卡片将直接失效，该平台卡 spinId 将无法再复用，后台与注单纪录将无此笔资料

Q5: 若玩家于游戏动画中离开游戏，FEATURE GAME 是否会自动结算?​

A: 会，玩家游玩到一半离开游戏时将立即结算

Q6: 卡片过期时间 "expiredTime" 与自动结算互动逻辑?​

A: expiredTime 为必填，过期与失效时间一律自发送当下起算，与玩家是否登入无关。未使用的卡片于过期时间直接失效；自动结算仅在玩家于游戏中开始使用后才会发生，FEATURE GAME 于玩家游玩到一半离开时立即结算

相关 API​