# 服务端接入指南

---

## 登录凭证验证接口
### 接口说明
用户登录后，4399运营SDK（以下简称SDK）客户端将返回用户信息的同时，返回用户登录凭证`state`，游戏方服务器可通过该接口验证用户登录凭证的合法性。

### 接口定义
- 接口名称：登录凭证验证接口
- 接口描述：用户登录时用于检验用户登录凭证合法性及返回用户相关的状态信息
- 接口协议：GET 
- 接口开发：4399平台
- 接口地址：http://m.4399api.com/openapiv2/oauth-check.html  

### 请求参数
| 字段    | 必填      | 数据类型           | 说明                                    |
|-------|---------|----------------|---------------------------------------|
| state | 是       | string         | 登录后SDK获取的服务端TOKEN                     |
| uid   | 是       | `unsigned int` | my或4399平台的用户id                        |
| key   | 未开启充值必填 | string         | sdk初始化的gamekey(游戏ID)，游戏未开启充值时必填，开启则选填。<br>如果游戏开启校验gamekey是否一致，传递该参数后，该参数的值会和state解析出的gamekey做对比，两者一致才校验通过，可用于防刷场景。 |

### 返回结果

成功示例：

```json
{
    "code": 200,
    "result": {
        "uid": "1924020039",
        "bindedphone": true,                // 用户是否有绑定电话号码，指定游戏按需返回，需找运营进行相关的配置
        "reg_ip":"8.8.8.8",                // 注册时的IP，指定游戏按需返回，需找运营进行相关的配置 
        "isRealName": true,                // 是否实名认证
        "isAdult": true                        // 是否成年
    },
    "message": "OK"
}
```

失败示例：

```json
{
    "code": 10205,
    "result": {
        "state": null
    },
    "message": "登录超时，重置state"
}
```


参数名| 说明
-------|-----
code        |状态码:<br/>`200`:验证成功<br/>`601`:参数错误<br/>`604`:游戏信息错误  <br/>`10204`:验证失败 <br/>`10205`:登录超时，重置state 
message     |对应`code`的返回值描述
result      |返回当前登录用户的 uid，<br>无符号整型，范围是0～2^32-1；若以整型方式使用它时，需要注意溢出风险    

## 充值回调接口
### 接口说明
用户充值成功后，SDK服务端将充值信息回调到游戏方服务端，游戏方服务端应在5秒内返回充值结果，否则将判定订单为异常订单。
只有确认订单是失败的情况下，才返回失败的返回值，当充值中心收到失败的返回值时，将退还用户的充值金额到游币账户，此后若该笔订单在游戏里又处理成充值成功，将造成充值金额的损失。

### 接口定义
- 接口名称：充值回调接口
- 接口描述：用户充值时，手机平台将请求本接口通知游戏方进行充值
- 接口协议：GET 
- 接口开发：游戏方

### 请求参数
   字段    |   必填    |   数据类型    |   说明    
:----------|:----------|:--------------|:----------
orderid | 是|string|4399 充值平台订单号，唯一，22位以内的字符串
p_type|是|int|充值渠道id
uid|是|unsigned int|充值用户ID，my平台的用户uid 
money|是|int|充值金额，单位：元 
gamemoney|是|int|获得游戏币数量，兑换标准由双方共同约定，<br>若在标准之外有优惠或者赠送策略，可忽略此字段，由游戏自行计算
serverid|否|int|充值角色服务区号。<br>只针对有分服的游戏有效。
mark|否|string|游戏方订单号，<br>游戏发起充值时生成唯一标识来标注该笔充值的相关信息时
roleid|否|int|游戏角色id，只针对pc端充值时，需要选择游戏角色的游戏。<br>roleid的值由角色接口提供（见接口2）
time|是|int|发起请求时的时间戳
coupon_mark|否|String|优惠券的唯一标识，<span color='red'>优惠券合作必接</span>
coupon_money|否|int|优惠券的金额，<span color='red'>优惠券合作必接</span>
sign|是|string|签名字段，见下文说明


#### sign 签名说明

```php
// 按顺序拼接各字段的md5值，php 示例
$sign = md5($orderid.$uid.$money.$gamemoney.
    $serverid.$secret.$mark.$roleid.$time.$coupon_mark.$coupon_money)
```

若参数`$serverid, $mark, $roleid, $coupon_mark, $coupon_money`中某个是空值时，不参与签名计算。

### 返回结果
```json
{
    "status": 2,
    "code": null,
    "money": "1",
    "game_money": "10",
    "msg": "充值成功"
}
```


参数名| 说明  
-------|-----
status |`1`：异常；<br/>`2`：成功；<br/>`3`：失败（将钱返还给用户）
code|异常状态码，成功或失败为空。<br/>`sign_error`:请求串的md5验证码错误<br/>`user_not_exist`:用户账号不存在<br/>`orderid_exist`:订单已提交（提交订单号必须唯一)<br/>`money_error`:充值金额或兑换游戏币数量错误<br/>`other_error`:其他错误
money|用户充值的人民币金额，单位：元 
gamemoney|用户实际兑换的游戏币的数量  
msg|开发商自定义的内容（返回结果的说明等）

#### 关于`$secret`
`$secret` 为 4399 自动分配的通信秘钥，仅可用于服务端，请勿将其写入客户端代码中。