# 基础说明
# 基础规则
为了方便使用和理解。我们对所有的接口做了一些整体的说明，除非特别标注。所有接口都遵从此规范：
接口类型: http接口（asr后续提供的长连接接口基于 websocket）
请求方法: post 方法
输入输出类型： json 结构（asr接口例外，请求参数非json类型）
接口地址:BASE_URL
- xiaowei.weixin.qq.com (Deprecated) 可以继续使用，不推荐。速度慢。
- 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 | 小微硬件平台注册获取的AppUin |
| channel_id | int | No | 渠道id 后续扩展字段，如果需要区分同产品渠道，暂不使用 |
| SN | string | Yes | 硬件产品 序列号，标识一个唯一的硬件。 |
其中user_info 中字段如下：
| field name | field type | required | desc |
|---|---|---|---|
| uid | string | Yes | 用户的ID，标识一个唯一的用户 |
| uname | string | NO | 用户名，可不提供 |
一个请求示例：通过方式一获取凭证
{
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 结构体，结构体的基本内如如下：
{
"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上，这里主要有三个原因
- 小微很多业务逻辑是和这两个字段强相关的。要不然很多业务流程，无法进行操作
- 权限，每个用户的的音乐权限是和用户账号强相关的。另外小微这边会针对每个接口和每个pid 每个sn 和每个uid进行限频，防止一些错误使用。
- 后续有些接入资源有计费需求的时候，可能针对SN或者UID进行收费，调用方有必要保证数据正确性