使用說明
---
目前可以使用以下幾種方式調用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``` 格式**，則**表示這是一個子屬性**
