使用说明
---
目前可以使用以下几种方式调用API：
1. 在插件在向服务端传递事件数据时，服务端在响应数据中加入需要的调用的API信息，但这样无法获取API的调用结果，另外，该方式会主动屏蔽调用GET类中声明的相关API。
2. 通过HTTP协议调用插件接口，该方式支持所有API，可以获取到调用结果，但需要配置插件的动态交互设置后使用 ( 配置参见「 配置文件说明 - httpSocket 」)，并且服务端要能够**以主动连接方式**成功连到插件端口 ( 即插件所在的主机要有所谓的公网IP ) 。
3. 在插件使用「 定时任务 」功能轮询服务端时调用，此方式与传递事件数据时的使用方法与使用限制一致。
所有API均支持异步调用，调用方法请见「异步调用」。
本篇大部分内容针对第二种使用方式进行说明。
请求说明
---
请求地址：`schema://ip:port/`
| 参数 | 说明 |
| --- | --- |
| schema | 使用协议，目前仅支持`http`，不支持`https`，如需使用，需要自行加装中间件(如`nginx`)进行反向代理。 |
| ip | 插件所使用的主机IP，主要是相对于服务端来说所使用的IP地址，需要服务端能够主动连接成功访问。 |
| port | 插件使用的监听端口 |
例如：
插件使用的监听端口是`9999`，因为服务端程序 ~~(PHP)~~ 运行在同一主机上，所以使用的IP地址即`127.0.0.1`或`localhost`，因此请求地址为：`http://127.0.0.1:9999/`
### **请求方式**
为了减少处理步骤，强制 **使用`POST`方式** 调用API接口
### **数据格式**
仅支持`JSON`
### **编码方式**
`UTF-8`
### **数据说明**
所有API均需要**提交参数`fun`**，值为该API的英文描述名
提交的参数**区分大小写**，**没有给出参数默认值时，表示该参数不可空**
如果开启了 数据校验 功能，请注意额外提交`authTime`和`authToken`这两个检验参数，具体说明请参考「提交说明 - 校验参数说明」
接口响应说明
---
对于任意请求：
### **HTTP状态码**
* `200`：表示成功调用了API，**但不能保证调用结果是正确的**。
* `400`：表示处理时出现错误。
* `403`：表示缺少API所需信息。
* `404`：表示调用了不存在的API。
* `405`：表示使用了接口不支持的协议，如`GET`、`HEAD`。
* `406`：表示无法解析请求，或为非支持的数据格式，如`XML`。
* `500`：表示处理时出现错误
> 如果开启 **数据校验** 功能，在出错的情况下会响应以下状态码
* `401`：表示缺少校验参数，或传递的校验参数有误
* `408`：表示该请求超过有效时间
因设计问题，部分情况下状态码可能与本规则设定不符，**请以`errMsg`参数为准**
### **响应数据格式**
响应数据为JSON格式：
~~~
{
"status":0,
"errMsg":"",
"result":"",
"request":{
"handle":12345,
"text":{
"fun":"xxx"
}
}
}
~~~
字段说明：
| 字段名 | 数据类型 | 说明 |
| --- | --- | --- |
| status | int | 状态码，`0`表示成功，`非0` 表示失败 |
| errMsg | string | 错误原因，成功调用接口时为`null` |
| result | ```string```/```array```/```object``` | 执行结果，部分API的返回值不存在此字段 |
| request | ```object``` | 本次请求的相关信息 |
| request.handle | ```int``` | 请求绑定的句柄 |
| request.text | ```object```/```string``` | 请求内容 |
* ```status```只有```-400```~```-600```之间的值为接口错误码，并请会在```errMsg```中返回错误原因；不在此范围内的错误码为酷Q错误码，请参考「[官方文档](https://docs.cqp.im/dev/v9/errorcode/)」
* **API说明中将不再描述```status```，```errMsg```与```request```字段信息**
* 若**字段名为 ```a.xx``` 格式**，则**表示这是一个子属性**
