1、更新日志

版本号 发布时间 更新内容
v1.1.0 2021-09-29 1、SDK API 返回 uid 保持字符串类型,最大长度将由 10 个字符扩展至 16 个字符;
2、SDK 服务端 API 返回 uid(部分 API 下称作 open_id)由 int32 型升级为 int64。
v1.1.1 2021-12-09 1、线路优化。
v1.2.0 2022-2-23 1、优化了玩家实名信息接口,将原请求参数uid调整为access_key。

2、概述

本文档是哔哩哔哩游戏SDK服务端API的统一接口规范和开发指南。主要提供给哔哩哔哩游戏中心的“SDK服务器”和哔哩哔哩游戏合作商的“游戏服务器”的交互接口规范并且配有java版和php版的相关demo,可从SDK下载文件中获取。

重要提示:严禁开发者对我方线上服务接口进行并发压力测试,如有违规将被列入黑名单。

下载文件目录结构

哔哩哔哩游戏SDK(版本号).zip\哔哩哔哩游戏SDK(版本号)\Demo_Project\sdk-server-demo

3、协议说明

3.1、通信协议

(1)概述
本接口采用HTTP 协议作为通信协议,调用方通过构造HTTP 请求(POST/GET 方式)向““哔哩哔哩游戏SDK服务器”发起接口请求。
本服务为游戏服务器调用哔哩哔哩游戏SDK服务端请求数据接口,由于南北网络连通性问题,我们提供了多域名解决方案,游戏研发需要有切线机制,主线不通切到备线,接口域名如下:
http://pnew.biligame.net (主线)
http://line3-qcloud-game-api-adapter-na.biligame.net (主线)
http://line3-game-api-adapter-na-sh.biligame.net (备用)

(2)游戏服务端请求数据示例
采用POST请求,请求body为URL参数,示例如下:

POST http://pnew.biligame.net/api/server/session.verify
sign=be61b558417cd078bfe514788999ebd8&timestamp=1418119041368&server_id=2&game_id=2&access_key=7d4c3cacccf28a7e342e4587a17139c7&merchant_id=2&uid=123&version=1

(3)哔哩哔哩游戏SDK服务端请求数据示例

POST http://game-server.test.com/recharge/callback
Content-Type: text/html
success

(4)响应数据示例 以下为正常返回数据

200 OK
Content-Type: application/json
{
    "timestamp":1418119041368,
    "code":0,
    "open_id":"123",
    "uname":"xxxxxx"
}

以下为异常返回数据

200 OK
Content-Type: application/json
{
    "code": -626,
    "message": "API sign invalid"
}

3.2、数据协议

3.2.1、数据格式

(1)游戏服务端请求
请求头部信息

参数 是否必填 头部值 描述
User-Agent Y Mozilla/5.0 GameServer 常量,所有API都是这个值
Content-Type Y application/x-www-form-urlencoded

请求消息公共字段(公共请求参数)

参数 是否必填 类型 描述
game_id Y int32 游戏id,即为CP分配的game_id
merchant_id Y int32 商户id,即为CP分配的merchant_id
server_id N int32 游戏区服ID
uid Y int64 B站用户uid
version Y String 默认为1
timestamp Y int64 当前时间戳(毫秒)
sign Y String 签名

响应消息公共字段如下表格

参数 是否必填 类型 描述
timestamp Y int64 时间戳(秒),对应request的
code Y int32 状态码
message Y String 错误信息,code不为0的时候出现

响应消息头部信息 包含Connection,Content-Type,Server,Date等标准参数

参数 是否必填 头部值 描述
Connection Y keep-alive
Content-Type Y application/json; charset=utf-8
Server Y nginx
Date Y Thu, 23 Mar 2017 08:48:42 GMT

(2)哔哩哔哩游戏SDK服务端请求
请求消息字段

参数 是否必填 类型 描述
data Y json 请求的json数据

3.2.2、字符编码

请求与响应内容须采用UTF-8字符编码。

3.2.3、签名方法

(1)游戏服务端请求
        游戏服务端请求,请求方为游戏服务端,请求数据为URL参数方式,如:用户会话验证接口。把接口所需所有URL参数,按参数名称排序,排除item_name以及item_desc字段,将其他参数值拼接,如utk=aa&time=bb,拼接后为bbaa,最后再拼接上开放平台所提供的密钥secret_key=cc, 则最后拼接出来的字符串为bbaacc,对此字符串进行md5加密

字段:拼接时需对字段名排序,排序方式是按字段名进行字符串升序排列。
字段值:取值只能为字符串、数字、true、false、null五类(注意true、false、null为小写,非True、False、Null等)。
计算MD5签名时,取签名内容的字节时,应以UTF-8编码取字符串的字节值。

(2)哔哩哔哩游戏SDK服务端请求
SDK服务端请求,请求方为哔哩哔哩游戏SDK服务端,请求数据为URL参数方,参数只有data,data的类型为,JSON格式,如:充值结果回调接口。

请求data样例:

{
    "id": "255",
    "order_no": "2014031010000614",
    "out_trade_no": "188292BFE31121A83ACC84909718EF61",
    "uid": 3521571,
    "username": "brianyao2014",
    "role": "android",
    "money": "1000",
    "pay_money": "1000",
    "game_money": "10000",
    "merchant_id": "5",
    "game_id": "9",
    "zone_id": "9",
    "product_name": "蓝钻",
    "product_desc": "Diamond",
    "pay_time": "1394434881",
    "client_ip": "221.223.236.205",
    "extension_info": "543002:android:3521571",
    "order_status": 1,
    "sign": "8f7160f8bc8a262660f2c7a42afabdb1"
}

Json decode后得到数组:

Array
(
  [id] => 255
  [order_no] => 2014031010000614
  [out_trade_no] => 188292BFE31121A83ACC84909718EF61
  [uid]=> 3521571
  [username] => brianyao2014
  [role] => android
  [money] => 1000
  [pay_money] => 1000
  [game_money] => 10000
  [merchant_id] => 5
  [game_id] => 9
  [zone_id] => 9
  [product_name] =>\u84dd\u94bb
  [product_desc] => Diamond
  [pay_time] => 1394434881
  [client_ip] => 221.223.236.205
  [extension_info] => 543002:android:3521571
  [order_status] => 1
  [sign] => 8f7160f8bc8a262660f2c7a42afabdb1
)

商户需要对参数进行签名校验,去掉sign参数,将其他参数按照数组键值顺序升序排列,再把所有数组值连接起来,形成的字符串末尾拼接上开放平台所提供的密钥secret_key即服务端appkey,之后整体做MD5,然后全部转成小写,将产生的加密串与sign进行对比,若相符,则该次请求为合法请求。

(3)订单参数加签规则
CP客户端调用哔哩哔哩游戏SDK客户端创建消费订单(接口详情参见《哔哩哔哩游戏SDK-客户端接入文档.doc》第4.7节)时,其中入参order_sign(订单参数签名)值为:按顺序拼接游戏内货币、本次交易金额、支付回调地址、商户订单号、开放平台所提供的服务端密钥后,进行md5加签的值。
哔哩哔哩游戏SDK服务端的创建消费订单接口接收到入参order_sign后,将校检订单信息是否被篡改。如发现订单被篡改,则拒绝下单。
* 加签方法:
对哔哩哔哩游戏SDK客户端创建消费订单接口参数game_money(游戏内货币) 、 money(本次交易金额) 、 notify_url(支付回调地址) 、 out_trade_no(商户订单号) 按顺序进行拼接,再拼接上开放平台所提供的服务端密钥secret_key,最后对此字符串进行md5加密。

  • 下单时必须在CP服务端对订单参数加签。

  • 注: notify_url(支付回调地址)为空或null时,值设为“”。

  • Java代码示例:

int game_money = 1; // 游戏内货币
int money = 100;  //本次交易金额(此参数即为客户端add.pay.order方法中的total_fee参数)
String notify_url = "http://www.biligame.com";  //支付回调地址,如果为null则赋值为""
Sting out_trade_no = "5117897656814864";  //商户订单号
String secret_key = "secretKey";  //服务端秘钥
String data = String.value(game_money) + String.value(money) + notify_url + out_trade_no + secret_key; //参数拼接排序请按服务端key名称序列化
String order_sign = md5(data); //加签字符串data = "1100http://www.biligame.com5117897656814864secretKey"

3.3、通用code状态码

通用code状态码如下:

状态码 说明
0 请求成功
-1 app_id不存在或已被封禁
-2 access key错误
-3 签名校验失败
-4 请求头部的user-agent不匹配,参考:2.2.1数据格式
-101 帐号未登陆
-102 帐号被封停
-400 请求参数错误
-500 服务器内部错误

4、接口列表

4.1、用户会话验证接口

  • 接口描述:验证access_key是否为有效的登录用户会话,若有效则返回其uid和昵称
  • 返回数据支持格式:JSON
  • 版本:1
  • HTTP请求方式:POST
  • 请求方:游戏服务器
  • 响应方:哔哩哔哩游戏SDK服务器
  • 请求地址:http://pnew.biligame.net/api/server/session.verify

    注意:若http://pnew.biligame.net/请求超时或者服务不可用时,请使用备用线路。如用http://line3-game-api-adapter-na-sh.biligame.net替换http://pnew.biligame.net/域名后再请求此接口,具体线路详见2.1节。

游戏服务端验证必须做切线处理

  • 请求参数(需要传递公共请求参数,详见2.2.1数据格式)

    参数 必填 类型 描述
    access_key Y String 哔哩哔哩游戏SDK登录接口返回的access_key,也就是客户端登录接口返回的access_token,禁止判断access_key字段长度(哔哩哔哩游戏保留修改的权利)
    uid Y int64 B站用户uid
  • 特殊响应状态码说明(通用响应码见2.3节)

    状态码 说明
    -503 调用速度过快
    500001 游戏封测,用户未激活
  • 响应数据说明(仅描述非通用字段的数据格式)

    参数 必填 类型 描述
    open_id Y String 哔哩哔哩游戏用户的用户id,也就是客户端登录接口返回的uid
    uname Y String 哔哩哔哩游戏用户的昵称
  • 请求参数示例

uid=12345&access_key=4ac2cceb5bb64906535398c58a981a02&game_id=57&merchant_id=1&server_id=116&version=1&timestamp=1445270401897&sign=fe222a9dc8392932404485c0ce5707bd
  • 响应结果示例
{
  "code":0,
  "timestamp":141645290000,
  "open_id":"141642321",
  "uname": "用户昵称"
}

4.2、查询支付订单接口

  • 接口描述:根据哔哩哔哩订单号,查询支付订单结果信息

    PS:建议CP多用同步通知机制,然后主动来查询订单结果

  • 返回数据支持格式:JSON

  • 版本:1
  • HTTP请求方式:POST
  • 请求方:游戏服务器
  • 响应方:哔哩哔哩游戏SDK服务器
  • 请求地址:http://pnew.biligame.net/api/server/query.pay.order
  • 注意:若http://pnew.biligame.net/请求超时或者服务不可用时,请使用备用线路。如用http://line3-game-api-adapter-na-sh.biligame.net替换http://pnew.biligame.net/域名后再请求此接口,具体线路详见2.1节。

游戏服务端验证必须做切线处理

  • 请求参数(需要传递公共请求参数,详见2.2.1数据格式)

    参数 必填 类型 描述
    order_no Y String 哔哩哔哩提供的订单号
    uid Y int64 B站用户uid
  • 特殊响应状态码说明(通用响应码见2.3.节)

    参数 信息
    -500 订单不存在
  • 响应数据说明(仅描述非通用字段的数据格式)

    参数 必填 类型 描述
    uid Y int64 用户ID
    username Y String 付款游戏用户的交易账号
    pay_time Y int64 支付订单时间,格式为时间戳
    pay_money Y int32 支付金额,单位为分,如1分钱
    order_no Y String 哔哩哔哩游戏SDK服务器的订单号
    out_trade_no Y String 游戏CP厂商支付订单号
    server_id Y int32 游戏区服iD
    subject Y String 订单名称
    remark N String 订单备注信息
    order_status Y int32 订单状态:1为已完成; 2为失败;3为处理中
    notify_status Y int32 异步通知状态:0:未完成;1:已经完成;2:异步通知失败
    extension_info N String 额外信息,原样通知回来,联运商返回的拓展信息
  • 请求参数示例

  order_no=5121979484629435&uid=85547212&sign=bb638778c69a196b491b63b8e0acebcf&merchant_id=1&server_id=543&version=1&game_id=314&timestamp=1512197961
  • 响应结果示例
  {
    "timestamp":1445270440,
    "code":0,
    "uid":15868578,
    "username":"AnubisZ",
    "pay_time":1445261585,
    "pay_money":3000,
    "order_no":"4456431357954"
    …….
  }

4.3、充值结果回调接口

  • 接口描述:即充值结果通知地址,当支付成功后,哔哩哔哩游戏SDK服务器会将支付结果在notify告诉游戏服务器,由游戏CP在开放平台中填写。
  • 返回数据支持格式:JSON
  • 版本:1
  • HTTP请求方式:POST
  • 请求方:哔哩哔哩游戏SDK服务器
  • 响应方:游戏服务器
  • 请求地址:游戏CP提供的回调地址 (CP可在开放平台中填写)
  • 请求参数

    参数 必填 类型 描述
    data Y json 请求的数据data信息,json格式,详细请看下面的data信息
  • data信息

    参数 必填 类型 描述
    id Y int32 订单ID
    order_no Y String 哔哩哔哩游戏SDK服务器方订单号
    out_trade_no Y String 游戏CP厂商支付订单号
    uid Y String 用户ID
    username Y String 用户名
    role Y String 角色名
    money Y int32 支付金额(单位:分)
    pay_money Y int32 实际支付金额,单位:分
    game_money Y int32 应用内货币
    merchant_id Y int32 商户ID
    game_id Y int32 游戏ID
    zone_id Y int32 区服ID
    product_name Y String 商品名称
    product_desc Y String 商品描述
    pay_time Y int32 订单支付时间
    client_ip Y String 客户端IP
    extension_info Y String 额外信息,原样通知回来
    order_status Y int32 订单状态:1为已完成
    sign Y String md5加密后的签名
  • 特殊响应状态码说明(通用响应码见2.3.节)

    状态码 说明
  • 响应数据说明(该接口只有响应内容)

    响应内容 描述
    success或者failure success表示处理订单成功,哔哩哔哩游戏SDK服务端方收到响应success后不会再通知给cp方.failure失败(也可返回其他错误信息,bili方收到success以外的字符串后都会多次重复通知)
  • 接口备注
    在用户支付订单完成后,哔哩哔哩游戏SDK服务器会向商户方服务器发起通知,并异步不断尝试直到获取结果。以下为异步通知接口说明:

  • 必须保证服务器异步通知页面(notify_url)上无任何字符,如空格、HTML 标签、开发系统自带抛出的异常提示信息等;
  • 哔哩哔哩游戏SDK服务器使用 POST 方式发送通知信息,只有一个参数名称为data,里面的数据是一个json字符串,json decode以后得到订单数组,因此该页面中获取参数的方式,如: request.Form("data")、$_POST['data'];
  • 程序执行完后必须打印输出“success”(不包含引号,不能加入换行符,缩进符等不可见字符)。如果商户反馈给哔哩哔哩游戏SDK服务器的字符不是 success 这 7 个字符,哔哩哔哩游戏SDK服务器会不断重发通知,直到 超过24小时22分钟。一般情况下,25 小时以内完成 8 次通知(通知的间隔频率一般是: 2m,10m,10m,1h,2h,6h,15h);
  • 程序执行完成后,该页面不能执行页面跳转。如果执行页面跳转,哔哩哔哩游戏SDK服务器会收不到 success 字符,会被哔哩哔哩游戏SDK服务器判定为该页面程序运行出现异常, 而重发处理结果通知;
  • cookies、session 等在此页面会失效,即无法获取这些数据;
  • 该方式的调试与运行必须在服务器上,即互联网上能访问;
  • CP方不仅要对回调的签名进行验证,还需要对回调的金额进行比对,两方一致方可发货,避免用户造假篡改订单内容

该方式的作用主要防止订单丢失,即页面跳转同步通知没有处理订单更新,它则去处理;

  • 请求参数示例(哔哩哔哩游戏SDK服务器)
  http://www.notifyUrl.com?data={
    "client_ip": "182.48.102.6",
    "extension_info": "20015312|2|ag0002",
    "game_id": "93",
    "game_money": "30",
    "id": "4114535",
    "merchant_id": "30",
    "money": "3000",
    "order_no": "4452682411635123",
    "order_status": 1,
    "out_trade_no": "01200153121445268238110020101",
    "pay_money": "3000",
    "pay_time": "1445268273",
    "product_desc": "机动战姬钻石",
    "product_name": "300钻石",
    "role": "折木奉太郎",
    "sign": "974c948dde515d39d7d1e5b52a891778",
    "uid": "389339",
    "username": "浓眉毛の喵",
    "zone_id": "184"
  }
  • 响应结果示例(CP方)
    success

4.4、玩家实名信息接口

  • 接口描述:可根据game_id和access_key查出该玩家实名相关信息,含是否实名,年龄段。请求方根据需求接入。
  • 返回数据支持格式:JSON
  • 版本:1
  • HTTP请求方式:POST
  • 请求方:游戏服务器
  • 响应方:哔哩哔哩游戏SDK服务器
  • 请求地址:http://pnew.biligame.net/api/server/user/age/range

    注意:若http://pnew.biligame.net/请求超时或者服务不可用时,请使用备用线路。如用http://line3-game-api-adapter-na-sh.biligame.net替换http://pnew.biligame.net/域名后再请求此接口,具体线路详见2.1节。

  • 请求参数(需要传递公共请求参数,详见2.2.1数据格式)

    参数 必填 类型 描述
    access_key Y String 哔哩哔哩游戏SDK登录接口返回的access_key,也就是客户端登录接口返回的access_token,禁止判断access_key字段长度(哔哩哔哩游戏保留修改的权利)
  • 特殊响应状态码说明(通用响应码见2.3.节)

    状态码 说明
  • 响应数据说明(仅描述非通用字段的数据格式)

    参数 必填 类型 描述
    code Y int32 响应状态码
    message Y String 提示信息
    data Y json 响应数据
  • data信息

    参数 必填 类型 描述
    uid Y int64 B站用户ID
    auth_status Y int32 实名状态:0=已实名,1=未实名
    age_range N string 年龄范围(岁):1-8,8-16,16-18,18-80。固定值,小于8岁,大于等于8岁小于16岁,大于等于16岁小于18岁,和大于等于18岁 四个阶段
  • 请求参数示例

access_key=d6d8a610c24964ca6147cddb4d8a5711&sign=0e7d4df0e3053b9ae3a1d303708ec4fb&merchant_id=2&server_id=2&version=1&game_id=2&timestamp=1569299127934
  • 响应结果示例
{
    "code":0,
    "message":"success",
    "data":{
        "uid": 123456,
        "auth_status": 0,
        "age_range": "18-80"
    }
}