4399 运营 SDK Harmony Next 服务端接入

登录状态校验

接口说明

请求协议

接口地址

请求参数

参数名 类型 方法 必须 说明
state string post 是 用户信息标示
uid int post 是 用户id
key string post 是 游戏key

返回结果

示例：

{
    "code": 200,
    "result": {
        "uid": "3458272310",
        "isRealName": true, // 是否实名
        "isAdult": true,    // 是否成年
        "age": 18       // 年龄
    },
    "message": "OK"
}
{
    "code": 10204,
    "result": [],
    "message": "验证失败"
}

返回字段中code说明：

参数值 说明
200 OK
601 参数错误
604 游戏信息错误
10204 验证失败

获取用户关联绑定鸿蒙用户信息接口

接口说明

请求协议

接口地址

请求参数

参数名 类型 方法 必须 说明
uid int post 是 用户uid

返回结果

示例：

{
    "code": 200,
    "result": {
        "uid": "943046627",             // 4399用户UID
        "open_id": "AAAovRyYDAWxRdzE1YawZIe8-k35",      // 鸿蒙授权openid
        "union_id": "MDECbNBEFrF580knfSPzgWXBo6HiaegD6rCEY06mIoH9tcA",          // 鸿蒙授权unionid
        "player_id": "CB0D7CEA18E9969B3FE8EA4D2168EE498A9127902678A296BC71A4453D43C29D" // 鸿蒙授权player_id,可能是 gamePlayerId 也可能是 teamPlayerId
    },
    "message": "OK"
}

返回字段中code说明：：

参数值 含义
200 成功 OK
601 参数错误

充值回调接口协议（由游戏厂商提供）

接口说明

  1. 厂商根据协议开发“充值回调接口”，并提供给平台。
  2. 厂商需提供“正式”跟“沙盒”两个环境的地址及对应的秘钥。
  3. 充值成功后，充值SDK会通过服务端回调厂商的“充值回调接口”，厂商完成物品发放逻辑，并依照规定返回处理结果。
  4. 若厂商未返回成功结果，平台将启动重发机制。
  5. 平台可能成功的订单重复回调，厂商需根据订单号（唯一标识）正确处理，避免重复发放。若对成功订单进行重复请求，也需返回成功的结果。

请求协议

POST

请求参数

表单，即头部参数为Content-Type: application/form-data

参数名 类型 是否必须 说明
orderId string 是 充值订单号，订单的唯一标识
payType int 是 用户使用的充值渠道ID
默认传：164，表示华为充值。
uid int 是 用户UID，用户的唯一标识
mark string 是 cp下单时生产的订单号，长度不可超过48个字符
productId string 是 产品ID
bundleId string 是 应用ID
money float 是 订单金额，保留2位小数
payMoney float 是 订单金额，保留2位小数（同money、兼容其它版本冗余字段）
payPrice float 是 玩家实际支付金额，保留2位小数
payCurrency string 是 玩家实际支付货币类型，货币类型简称，如：人民币：CNY；
payCurrencySymbol string 是 玩家实际支付货币符号，如：人民币：￥；
sign string 是 签名字段，算法详见 “签名算法说明”

返回结果

示例：

{
   'code' => 100,
   'msg' => '充值成功'
}

返回字段说明：

参数名 类型 是否必须 说明
code int 是 充值结果：
100： 充值成功；
其他情况 ：充值异常，平台将启动重试机制。
msg sring 否 返回结果的文字说明

退款通知接口协议（由游戏厂商提供）

接口说明

  1. 厂商根据协议开发“退款通知接口”，并提供给平台。
  2. 厂商需提供“正式”跟“沙盒”两个环境的地址及对应的秘钥。
  3. 用户成功申请退款时，平台会通过服务端回调厂商的“退款通知接口”，厂商完成相关逻辑，并依照规定返回处理结果。
  4. 若厂商未返回成功结果，平台将启动重发机制。

请求协议

POST

请求参数

表单，即头部参数为Content-Type: application/form-data

参数名 类型 是否必须 说明
uid int 是 用户UID，用户的唯一标识
orderId string 是 充值订单号，订单的唯一标识
bundleId string 是 应用ID
productId string 是 商品ID
mark string 是 cp下单时生产的订单号
sign string 是 签名字段，算法详见 “签名算法说明”

返回结果

示例：

{
   'code' => 100,
   'msg' => '成功'
}

返回字段说明：

参数名 类型 是否必须 说明
code int 是 充值结果：
100：成功；
其他情况 ：异常，平台将启动重试机制。
msg sring 否 返回结果的文字说明

签名算法说明

算法说明

  1. 将接收到的所有参数，去掉 sign字段；
  2. 将剩余的参数，按照参数名的字符串升序排序；
  3. 将所有参数以"key=val"的格式，直接连接起来，得到字符串str1
  4. 在字符串 str1 后，附加双方约定的密钥 secret，得到字符串str2
  5. 计算str2的md5值，并转换成小写字符串，作为签名sign的值

代码示例

// 示例，充值回调请求url为： 
// http://www.xxx.com/path/callback?uid=10000&mark=1234567890abcdefg&bundleId=cn.4399.gamebox
&productId=cn.4399.gamebox_001&money=100.00&payMoney=88.00
&orderId=2024020108080891642387&payType=164&sign=3f5efd681f4a14310dc721a38e6eb478
// 双方约定的密钥 secret 为： 12345abcde
$secret = "12345abcde";
$params = [
    'uid' => 10000,
    'mark' => '1234567890abcdefg',
    'bundleId' => 'cn.4399.gamebox',
    'productId' => 'cn.4399.gamebox_001',
    'orderId' => '2024020108080891642387',
    'money' => 100.00,
    'payMoney' => 88.00,
    'payType' => 164,
];
ksort($params);
$str1 = "";
foreach($params as $k=>$v){
    $str1 .= "{$k}={$v}";
}
$str2 = $str1 . $secret;
$sign = strtolower(md5($str2));

注意事项

  1. 密钥是签名校验的重要凭证，不可泄露。
  2. 密钥长度限制在50个字符以内（包括50）。
  3. 由于平台在通知业务方，可能会遇到网络等原因，不能保证一给订单只同步一次（但一个订单的订单号是唯一不变的），游戏方在发放游戏虚拟币时应该做好校验，避免同一订单多次发放的情况。
  4. 充值回调，除校验签名外，还需要校验回调参数中的其他信息，如用户信息、金额等
  5. 签名计算以传递的参数原始值进行计算校验，请勿在校验前调整参数格式，以免签名校验不通过