# 4399 运营 SDK Harmony Next 服务端接入

## 登录状态校验
### 接口说明
- 验证uid及state是否合法、用户是否实名、是否成年

### 请求协议
- POST

### 接口地址
- http://m.4399api.com/openapiv2/hmOauth-check.html

### 请求参数

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

### 返回结果
 示例：
```json
{
    "code": 200,
    "result": {
        "uid": "3458272310",
        "isRealName": true,	// 是否实名
        "isAdult": true,	// 是否成年
        "age": 18		// 年龄
    },
    "message": "OK"
}
```

```json
{
    "code": 10204,
    "result": [],
    "message": "验证失败"
}
```
**返回字段中code说明：**

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

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

### 接口说明
- 供游戏厂商服务端获取用户关联的鸿蒙用户信息接口

### 请求协议
- POST

### 接口地址
- http://m.4399api.com/openapiv2/api-hmBindInfo.html

### 请求参数

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

### 返回结果
 示例：
```json
{
    "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 <br/> 默认传：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|是|充值结果：<br> **100**： 充值成功；<br/>  **其他情况** ：充值异常，平台将启动重试机制。
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|是|充值结果：<br> **100**：成功；<br/>  **其他情况** ：异常，平台将启动重试机制。
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. 签名计算以传递的参数原始值进行计算校验，请勿在校验前调整参数格式，以免签名校验不通过