跳到主要内容
版本：v4

厂商接入直发礼包指南

请先阅读接口公共说明了解接口的基本信息。

厂商接口可前往 开发者中心 > 你的游戏 > 游戏服务 > 应用配置 > 直达礼包 > 直达礼包发送的接口地址 进行配置。

直发礼包获取游戏区服列表​

该接口用于获取指定区服（如果有区服概念）的游戏角色数据。如果游戏支持多个区服，则需要传入 server_id 来指定查询的区服；如果游戏没有区服概念，则无需传入 server_id 参数。

注意
  • URL：/direct-gift/v1/get-server-list (path 仅供参考，后台配置时须配置完整带 path 的请求地址)
  • Method：GET
  • 需要鉴权：是

请求参数​

注意

公共参数见 接口公共说明 文档

参数名类型必须描述
fromint是用于指定查询开始的起点。例如 from=0 表示从第 1 条记录开始返回。
limitint是翻页参数，每页的数量
openidstring是TapTap OpenID
unionidstring是TapTap UnionID

成功响应​

注意

条件：请求参数合法，并且验签通过。 状态码：200 OK 响应示例：返回游戏列表信息

{
  "code": 0,
  "msg": "OK",
  "data": {
    "servers": [
      {
        "server_id": "string", // 游戏服 ID
        "server_name": "string" // 游戏服名称
      }
    ],
    "total": 0
  }
}

错误响应​

{
  "code": 510008,
  "msg": "some errors"
}

直发礼包获取游戏该区服下角色列表​

该接口用于获取指定区服（如果有区服概念）的游戏角色数据。如果游戏支持多个区服，则需要传入 server_id 来指定查询的区服；如果游戏没有区服概念，则无需传入 server_id 参数。

注意
  • URL：/direct-gift/v1/get-role-list(path 仅供参考，后台配置时须配置完整带 path 的请求地址)
  • Method：GET
  • 需要鉴权：是

请求参数​

注意

公共参数见 接口公共说明 文档

参数名类型必须描述
server_idstring否用户选择的区服 ID
openidstring是TapTap OpenID
unionidstring是TapTap UnionId

请求示例​

/direct-gift/v1/get-role-list?server_id=1&openid=aaaaaaaaa&unionid=aaaaaaaaaa

成功响应​

注意
  • 条件：请求参数合法，并且验签通过。
  • 状态码：200 OK
  • 响应示例：返回用户在该服务下的角色列表
{
  "code": 0,
  "msg": "OK",
  "data": {
    "roles": [
      {
        "id": "string", // 角色 ID
        "name": "string" // 角色名称
      }
    ]
  }
}

错误响应​

{
  "code": 510008,
  "msg": "some errors"
}

直发礼包发送接口​

TapTap 侧已登录的用户通过此接口获得直发礼包。

注意
  • URL：/direct-gift/v1/send-gift-package (path 仅供参考，后台配置时须配置完整带 path 的请求地址)
  • Method：POST
  • 需要鉴权：是

请求参数​

注意

无额外 query parameters，公共参数见接口公共说明 文档

需要保证幂等

请求示例​

{
  "openid": "aaaaaaaaaaaaaaa",
  "unionid": "aaaaaaaaaaaaaaa",
  "server": "1",
  "role_id": "aaaaaaaaa",
  "gift_code": "123456"
}

成功响应​

注意
  • 条件：请求参数合法，并且验签通过。
  • 状态码：200 OK
  • 响应示例：发送直发礼包结果
{
  "code": 0,
  "msg": "OK"
}

错误响应​

{
  "code": 510008,
  "msg": "server error"
}

直发礼包错误码​

自定义状态码含义复现场景
510001参数错误发起请求的参数错误或者缺失部分必要参数
510002发送道具失败发送道具游戏方返回了失败结果
510003该礼包码无效异常兑换码的提交
510004礼包码次数已达上限通相同用户使用礼包中超过礼包设置的兑换数量
510005找不到服务器列表该用户在服务器下没有任何角色
510006找不到角色列表没有对应的角色
510007点击过快，请稍候再试用户连续点击获取角色或兑换礼包
510008服务器故障礼包系统出现通用性错误