# SYIOS 渠道 API 文档

## 渠道信息
- **渠道ID**: 12
- **平台**: sy_ios
- **处理器**: SYIOSChannelHandler

---

## 1. 登录鉴权接口

### 接口地址
- **GET/POST** `/thirdLogin` (通过渠道ID=12调用)

### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| userToken | string | 是 | 鉴权凭证，从 URL 上获取 |
| gameid | number | 是 | 游戏的ID，商户后台游戏添加完成后可获取 |

### 请求示例
```bash
# POST 请求
POST /thirdLogin
Content-Type: application/json

{
  "channelId": 12,
  "userToken": "your_token_here",
  "gameid": 1540
}
```

### 响应参数
```json
{
  "code": 1,           // 1成功，-1失败
  "msg": "登录成功",    // 提示信息
  "data": {
    "uid": "",         // 用户UID
    "nickname": "",    // 用户昵称
    "headimgurl": "",  // 用户头像地址
    "sex": "",         // 用户性别 0未知 1男 2女
    "focus": "",       // 是否关注公众号 0否 1是
    "usertype": ""     // 用户类型 1为微信用户 -1为非微信用户
  }
}
```

### 错误响应
```json
{
  "code": -1,
  "msg": "参数有误，请检查接口所需参数是否都已经填写正确",
  "data": null
}
```

---

## 2. 支付回调接口

### 接口地址
- **GET** `/callback` (通过渠道ID=12调用)

### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| openid | string | 是 | 用户UID |
| rmb | number | 是 | 付费金额，单位人民币 |
| reqid | string | 是 | 不重复的请求ID |
| trans_id | number | 是 | 平台支付订单号 |
| product_id | number | 是 | 商品ID |
| notify_id | string | 是 | 平台通知ID |
| userdata | string | 否 | 支付的透传参数，商户自定义参数，最多128个字节 |
| txid | string | 否 | 支付的透传参数，商户订单号，最多64个字节 |
| product_count | number | 否 | 购买的商品数量，默认为1 |
| sign | string | 是 | 签名，签名算法3 |

### 请求示例
```bash
GET /callback?openid=12345678&rmb=1&reqid=20152392834940&trans_id=123456&product_id=6000&notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c&userdata=test_data&txid=merchant_order_123&product_count=1&sign=7761AF5E944ABC6060B3192861FA0281
```

### 响应
- **成功**: 返回字符串 `"SUCCESS"` (不包含引号，全大写)
- **失败**: 返回错误信息

### 支付处理流程
1. **接收支付回调**: 接收第三方支付平台的回调通知
2. **验证支付签名**: 使用签名算法3验证支付回调的签名
3. **提取notify_id**: 从支付回调中提取 `notify_id` 参数
4. **订单校验**: 调用第三方订单校验API验证订单是否真实有效
5. **发货处理**: 只有订单校验成功后才进行实际的发货处理
6. **返回响应**: 返回 `"SUCCESS"` 给第三方支付平台

### 订单校验集成
支付回调处理中会自动进行订单校验，确保：
- 防止恶意第三方通知
- 验证订单的真实性
- 只有校验成功的订单才会发货
- 提高支付安全性

---

## 3. 订单校验接口

### 接口地址
- **GET/POST** `/miniapp/verifyOrder`

### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| gameid | number | 是 | 游戏ID，商户后台游戏添加完成后可获取 |
| notify_id | string | 是 | 平台通知ID，商户通过notify_id查询订单是否付费成功 |
| sign | string | 是 | 签名，签名算法3 |

### 请求示例
```bash
# GET 请求
GET /miniapp/verifyOrder?gameid=1540&notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c&sign=A3EA3EF39B43BA762DFBFB78229DB33B

# POST 请求
POST /miniapp/verifyOrder
Content-Type: application/json

{
  "gameid": 1540,
  "notify_id": "f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c",
  "sign": "A3EA3EF39B43BA762DFBFB78229DB33B"
}
```

### 响应参数
```json
{
  "success": true,        // 校验是否成功
  "message": "订单校验成功" // 提示信息
}
```

### 错误响应
```json
{
  "success": false,
  "message": "缺少必要参数: gameid"
}
```

### 第三方API
- **请求方式**: GET
- **URL**: `https://login.11h5.com/pay/paygate/verify.php`
- **成功响应**: `"SUCCESS"` (不包含引号，全大写)
- **失败响应**: 其他任何信息

---

## 4. 签名算法3

### 算法步骤

1. **除去为空的参数**: 过滤掉值为空、null、undefined的参数，以及sign参数
2. **参数排序**: 对参数名按字母顺序排序 (a-z)
3. **构建字符串**: 用 `&` 连接所有参数，格式为 `key=value`
4. **拼接私钥**: 在字符串末尾添加 `&key=私钥`
5. **MD5签名**: 对最终字符串进行MD5哈希，并转换为大写

### 示例

**原始参数**:
```
openid=12345678
rmb=1
reqid=20152392834940
trans_id=123456
product_id=6000
notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c
nick=                    // 空参数，会被过滤
userdata=test_data
txid=merchant_order_123
product_count=1
```

**排序后的待签名字符串**:
```
notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c&openid=12345678&product_count=1&product_id=6000&reqid=20152392834940&rmb=1&trans_id=123456&txid=merchant_order_123&userdata=test_data
```

**最终签名字符串**:
```
notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c&openid=12345678&product_count=1&product_id=6000&reqid=20152392834940&rmb=1&trans_id=123456&txid=merchant_order_123&userdata=test_data&key=yduLY3ovg4NwTHMMemGg1vO6VHuYBcYD
```

**生成的签名**:
```
7761AF5E944ABC6060B3192861FA0281
```

### 订单校验签名示例

**原始参数**:
```
gameid=1540
notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c
```

**排序后的待签名字符串**:
```
gameid=1540&notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c
```

**最终签名字符串**:
```
gameid=1540&notify_id=f2c90bc120cdef27c8cc4d1bdf8341a74625588c6edcd9c&key=yduLY3ovg4NwTHMMemGg1vO6VHuYBcYD
```

**生成的签名**:
```
A3EA3EF39B43BA762DFBFB78229DB33B
```

---

## 4. 错误码说明

| 错误码 | 说明 |
|--------|------|
| 0 | 参数有误，请检查接口所需参数是否都已经填写正确 |
| 403 | token验证失败，同一个userToken只能验证一次，可通过刷新游戏重新获取 |
| -1 | 系统错误，鉴权失败，请稍后重试 |

---

## 5. 重要说明

⚠️ **同一个token只能验证一次，不能多次重复请求**

## 6. 第三方API

- **登录鉴权**: `https://api.11h5.com/login?cmd=checkUserToken`
- **私钥**: `yduLY3ovg4NwTHMMemGg1vO6VHuYBcYD`
- **游戏ID**: `1540`