### 基础说明

#### 基础规则

为了方便使用和理解。我们对所有的接口做了一些整体的说明，除非特别标注。所有接口都遵从此规范：

**接口类型:** http接口（asr后续提供的长连接接口基于 websocket）

**请求方法:** post 方法

**输入输出类型：** json 结构（asr接口例外，请求参数非json类型）

**接口地址**:BASE_URL

1. xiaowei.weixin.qq.com (Deprecated) 可以继续使用，不推荐。速度慢。
2. xwcloudapi.weixin.qq.com 推荐使用，速度快，后续功能优先支持。

##### 请求接口基础参数说明

​	基础参数指的是所有业务请求中必须携带的参数，**鉴权接口与asr接口除外**。基础参数主要包括硬件产品标识pid 、用户uid、硬件身份sn、请求query_id以及接口鉴权的auth。

​	请求接口之前，需要申请凭证，获取小微云对接签发的凭证之后，才有权限访问小微云对接。获取凭证相关描述详见**接口鉴权**章节。获取凭证有两种方式，不同的获取凭证方式请求非鉴权接口、非asr接口时，需要传递的基础参数不同，下面介绍两种不同的获取凭证方式请求接口传递的基础参数。

**方式一接口鉴权：基础参数**

​	如果使用**接口鉴权**章节中的方式一获取凭证，所有业务请求需要携带base_info字段作为基础参数，鉴权接口与asr接口除外。

base_info 的字段组成如下：

| field name  | field type  | required | desc                                                  |
| ----------- | ----------- | -------- | ----------------------------------------------------- |
| device_info | json object | Yes      | 请求的硬件信息说明字段见下文                          |
| user_info   | json object | Yes      | 本次请求的用户相关信息                                |
| auth        | string      | Yes      | 本次请求的鉴权相关信息，参见下文的安全相关章节        |
| query_id    | string      | Yes      | 本次请求的id 为32字节长度的值，方便共同追查问题和定位 |

其中device_info 中字段如下

| field name | field type | required | desc                                                         |
| ---------- | ---------- | -------- | ------------------------------------------------------------ |
| pid        | int        | Yes      | [小微硬件平台](https://xiaowei.weixin.qq.com/home)注册获取的AppUin |
| channel_id | int        | No       | 渠道id 后续扩展字段，如果需要区分同产品渠道，暂不使用        |
| SN         | string     | Yes      | 硬件产品 序列号，标识一个唯一的硬件。                        |

其中user_info 中字段如下：

| field name | field type | required | desc                         |
| ---------- | ---------- | -------- | ---------------------------- |
| uid        | string     | Yes      | 用户的ID，标识一个唯一的用户 |
| uname      | string     | NO       | 用户名，可不提供             |

**一个请求示例：通过方式一获取凭证**

```json
{
      xxxxxxxxxxxxxxx // 省去业务的请求数据
    "base_info": {
        "device_info": {
            "pid": 23000246,
            "channel_id": 1,
            "SN": "KADSJFLJSDLAJFLSADJFLJFLJDSALFJLFD"
        },
        "user_info": {
            "uid": "2933999333",
            "uname": "I'm test"
        },
        "auth": "ksafd8if998@iriufadskfnkjashfkasyfiuashfksuiywqtrpnvn+",
        "query_id": "KLDASOEWUROUQWIOEUROWEQVNZVFADSFOIOUWOEQR"
    }
}

```

**方式二接口鉴权：基础参数**	

​	如果使用**接口鉴权**章节中的方式二获取凭证，所有业务请求需要携带auth、query_id字段作为基础参数，而不需要携带base_info字段，鉴权接口与asr接口除外，不需要携带基础参数。auth字段为接口鉴权章节中的方式二返回的凭证。

**注意**：小微体系其他服务方签发的token，token凭证中已经注入了相关参数。

**一个请求示例：通过方式二获取凭证**

```
{
		xxxxxxxxxxxxxxx // 省去业务的请求数据
		"auth": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJiYXNlX2luZm8iOiJ7XCJjb2RlXCI6XCIwN2E0YTZlNTRlMDUwMjRlYmQ0MTMzMzM5Y2M3OTAzMFwiLFwicGlkXCI6ODIzOTIzNDc4LFwidGltZXN0YW1wXCI6XCIxNTk4NTk5NzA1XCJ9XG4iLCJleHAiOjE1OTg2MDY5MDV9.nBuDFO7CWfg9KLognHIy10WFIorzuMBBRNh_F8gSXY",
		"query_id": "KLDASOEWUROUQWIOEUROWEQVNZVFADSFOIOUWOEQR"
}
```

#### 返回格式：

返回格式为json 结构体，结构体的基本内如如下：

```json
{
    "code":0,  // 0 代表成功 非0 失败
    "msg":"OK", // 信息简要描述
    "data":{}   // 返回的信息结构体
}
```

#### 全局错误码

| code  | desc                                           |
| ----- | ---------------------------------------------- |
| 0     | 成功                                           |
| 10001 | 系统错误，发生需要联系开发查看                 |
| 10002 | 网络寻址错误，一般不会发生，发生属于底层错误   |
| 10003 | 底层存储错误，一般也不会发生                   |
| 20001 | 请求参数为空                                   |
| 20002 | 请求参数不是合法的json，或者某些字段格式不正确 |
| 20003 | 缺少必要的请求参数                             |
| 30001 | 接口调用频次超过限制                           |
| 30002 | 安全检查错误，一般发生在安全签名不正确。       |
| 30004 | 未注册的pid                                    |
| 30005 | IP地址没有在IP白名单中                         |
| 30006 | 没有访问该接口的权限                           |

#### 补充说明:

关于请求中的 SN和uid 可能会牵扯一些业务方的核心数据问题，本质上小微这边不对SN和UID进行判别和是识别的，只是为了区分调用的一个设备和一个用户，业务方也可以在自己后台做个1对1映射，但是一定要保证一个用户可以映射到一个uid上，一个设备可以映射到一个sn上，这里主要有三个原因

1. 小微很多业务逻辑是和这两个字段强相关的。要不然很多业务流程，无法进行操作
2. 权限，每个用户的的音乐权限是和用户账号强相关的。另外小微这边会针对每个接口和每个pid 每个sn 和每个uid进行限频，防止一些错误使用。
3. 后续有些接入资源有计费需求的时候，可能针对SN或者UID进行收费，调用方有必要保证数据正确性