# Mild White 宠物物联网开放平台 API 文档
## 文档说明
- 版本：v1.0.0
- 接口基础地址：`https://nbsg.aidbai.com`
- 编码格式：UTF-8
- 数据格式：JSON
- 鉴权方式：OAuth2.0 Client Credentials 客户端模式

---

## 一、接入流程
1. 联系平台管理员创建第三方应用，获取 `SDKAppID` 和 `AppSecret`
2. 调用获取token接口，得到 `access_token`（有效期2小时）
3. 所有业务接口请求头携带 `Authorization: Bearer {access_token}`
4. 调用分配用户码接口，为终端用户分配唯一识别码
5. 调用设备绑定接口，完成设备与用户、宠物的绑定
6. 连接MQTT服务，订阅专属Topic，实时接收设备上报的体征数据

---

## 二、鉴权接口
### 2.1 获取access_token
**接口地址**：`POST /oauth/token`

**请求头**：`Content-Type: application/x-www-form-urlencoded`

**请求参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| grant_type | string | 是 | 固定值：`client_credentials` |
| sdk_app_id | string | 是 | 平台分配的SDKAppID |
| app_secret | string | 是 | 平台分配的AppSecret |

**请求示例**：
```http
POST /oauth/token HTTP/1.1
Host: nbsg.aidbai.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&sdk_app_id=test123&app_secret=abcdefg
```

**成功返回**：
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "accessToken": "a1b2c3d4e5f6g7h8i9j0",
        "expiresIn": 7200
    }
}
```
| 返回字段 | 类型 | 说明 |
|----------|------|------|
| accessToken | string | 访问令牌，后续接口需要携带 |
| expiresIn | number | 令牌有效期，单位：秒（默认7200秒=2小时） |

---

## 三、业务接口
> 所有业务接口必须在请求头携带：`Authorization: Bearer {access_token}`

### 3.1 分配第三方用户识别码
为第三方终端用户分配平台唯一识别码ThirdUserCode，用于设备绑定和数据关联。

**接口地址**：`POST /open/api/allocateThirdUserCode`

**请求头**：
```http
Authorization: Bearer {access_token}
```

**请求参数**：无

**成功返回**：
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "third_user_code": "x1y2z3w4v5u6t7s8"
    }
}
```
| 返回字段 | 类型 | 说明 |
|----------|------|------|
| third_user_code | string | 平台分配的用户唯一识别码，长度16位 |

---

### 3.2 绑定设备
将设备SN与第三方用户、宠物进行绑定，绑定后设备上报的数据会推送到对应机构的MQTT Topic。

**接口地址**：`POST /open/api/bindDevice`

**请求头**：
```http
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
```

**请求参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| device_sn | string | 是 | 设备唯一序列号 |
| third_user_code | string | 是 | 平台分配的用户识别码 |
| pet_id | number | 否 | 第三方系统的宠物ID，用于数据关联 |

**请求示例**：
```http
POST /open/api/bindDevice HTTP/1.1
Host: nbsg.aidbai.com
Authorization: Bearer a1b2c3d4e5f6g7h8i9j0
Content-Type: application/x-www-form-urlencoded

device_sn=SN202607220001&third_user_code=x1y2z3w4v5u6t7s8&pet_id=10086
```

**成功返回**：
```json
{
    "code": 0,
    "msg": "success",
    "data": null
}
```

---

## 四、MQTT 实时数据对接
### 4.1 连接信息
| 项 | 值 |
|----|----|
| MQTT地址 | `mqtt://nbsg.aidbai.com:1883` |
| WebSocket地址 | `ws://nbsg.aidbai.com:8083/mqtt` |
| Username | 平台分配的 `SDKAppID` |
| Password | 通过 `/oauth/token` 获取的 `access_token` |
| ClientId | 自定义唯一标识，建议使用UUID |

### 4.2 订阅Topic
每个机构只能订阅属于自己的专属Topic，格式：
```
open/app/{SDKAppID}/realtime
```
> ⚠️ 禁止订阅通配符Topic（如`open/app/#`），系统会拒绝非法订阅请求。

### 4.3 消息格式
设备上报的心率、呼吸等体征数据会实时推送到订阅的Topic，消息格式：
```json
{
    "device_sn": "SN202607220001",
    "third_user_code": "x1y2z3w4v5u6t7s8",
    "pet_id": 10086,
    "heart_rate": 78,
    "breath_rate": 22,
    "battery": 86,
    "collect_time": "2026-07-22 10:30:00"
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| device_sn | string | 设备序列号 |
| third_user_code | string | 第三方用户识别码 |
| pet_id | number | 第三方宠物ID |
| heart_rate | number | 心率，单位：次/分钟 |
| breath_rate | number | 呼吸率，单位：次/分钟 |
| battery | number | 设备电量，百分比 |
| collect_time | string | 数据采集时间 |

---

## 五、错误码说明
| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 0 | 请求成功 | - |
| 401 | 未授权，缺少token或token无效/过期 | 重新调用 `/oauth/token` 获取新的access_token |
| 40001 | SDKAppID或AppSecret错误 | 检查凭证是否正确，注意不要有空格 |
| 40002 | 应用已被禁用 | 联系平台管理员开通应用权限 |
| 40003 | 请求参数缺失 | 检查必填参数是否完整 |
| 40010 | 设备已被绑定 | 该设备已经绑定到其他用户，无法重复绑定 |
| 42901 | 请求过于频繁 | 降低请求频率，默认限制60秒最多120次请求 |

---

## 六、限流规则
为保证服务稳定，平台对接口调用做了频率限制：
1. 获取token接口：单SDKAppID 60秒最多30次请求
2. 业务接口：单SDKAppID 60秒最多120次请求，特殊需求可联系管理员调整配额
3. MQTT连接：单SDKAppID最多同时建立10个长连接
4. MQTT消息推送：单SDKAppID 60秒最多推送300条消息

---

## 七、调用示例（Java）
```java
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.json.JSONObject;
import cn.hutool.json.JSONUtil;

public class OpenApiDemo {
    private static final String BASE_URL = "https://nbsg.aidbai.com";
    private static final String SDK_APP_ID = "你的SDKAppID";
    private static final String APP_SECRET = "你的AppSecret";

    public static void main(String[] args) {
        // 1. 获取access_token
        String tokenUrl = BASE_URL + "/oauth/token";
        HttpResponse tokenResp = HttpRequest.post(tokenUrl)
                .form("grant_type", "client_credentials")
                .form("sdk_app_id", SDK_APP_ID)
                .form("app_secret", APP_SECRET)
                .execute();
        JSONObject tokenJson = JSONUtil.parseObj(tokenResp.body());
        String accessToken = tokenJson.getJSONObject("data").getStr("accessToken");
        System.out.println("获取到token：" + accessToken);

        // 2. 分配用户码
        String userUrl = BASE_URL + "/open/api/allocateThirdUserCode";
        HttpResponse userResp = HttpRequest.post(userUrl)
                .header("Authorization", "Bearer " + accessToken)
                .execute();
        System.out.println("分配用户码返回：" + userResp.body());

        // 3. 绑定设备
        String bindUrl = BASE_URL + "/open/api/bindDevice";
        HttpResponse bindResp = HttpRequest.post(bindUrl)
                .header("Authorization", "Bearer " + accessToken)
                .form("device_sn", "SN202607220001")
                .form("third_user_code", "x1y2z3w4v5u6t7s8")
                .form("pet_id", 10086)
                .execute();
        System.out.println("绑定设备返回：" + bindResp.body());
    }
}
```

---

## 八、开发者门户接口
> 门户接口用于开发者自服务平台，前缀 `/portal`，登录态通过 `X-Token` 请求头传递

### 8.1 发送注册验证码
**接口**：`POST /portal/sendCode`

**参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 邮箱地址 |

### 8.2 用户注册
**接口**：`POST /portal/register`

**参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 邮箱 |
| code | string | 是 | 邮箱验证码 |
| password | string | 是 | 密码（至少6位） |

### 8.3 用户登录
**接口**：`POST /portal/login`

**参数**：
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| email | string | 是 | 邮箱 |
| password | string | 是 | 密码 |

**返回**：
```json
{
    "code": 0,
    "data": {
        "token": "登录凭证",
        "email": "用户邮箱"
    }
}
```

### 8.4 退出登录
**接口**：`POST /portal/logout`
**请求头**：`X-Token: {登录token}`

### 8.5 获取用户信息
**接口**：`GET /portal/userInfo`
**请求头**：`X-Token: {登录token}`

### 8.6 提交资质申请
**接口**：`POST /portal/apply`
**请求头**：`X-Token: {登录token}`
**Content-Type**: `application/json`

**请求体**：
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| companyName | string | 是 | 公司名称 |
| creditCode | string | 是 | 统一社会信用代码 |
| contactName | string | 是 | 联系人 |
| contactMobile | string | 是 | 联系电话 |
| contactEmail | string | 是 | 联系邮箱 |
| website | string | 否 | 公司官网 |
| businessDesc | string | 是 | 业务场景描述 |
| licenseUrl | string | 否 | 营业执照图片地址 |

### 8.7 查询申请状态
**接口**：`GET /portal/applyStatus`
**请求头**：`X-Token: {登录token}`

**返回状态说明**：
- 0：待审核
- 1：审核通过
- 2：审核拒绝

### 8.8 获取应用凭证
**接口**：`GET /portal/appInfo`
**请求头**：`X-Token: {登录token}`
**说明**：审核通过后才会返回应用信息，否则返回null

---

## 九、技术支持
如有对接问题，请联系平台技术支持。