API接口说明
<p>[TOC]</p>
<h2>使用前提</h2>
<p>我司提供对外MQTT服务器租用及API接口调用服务，二开设备连接到我司对外MQTT服务器，提供设备API接口调用方式，适用于不想自己架设MQTT服务，同时需要对硬件设备进行远程操控的客户。
收费标准：<code>500元/年/200台设备</code>。</p>
<h2>约定</h2>
<ul>
<li>所有请求参数，以json形式发送。</li>
<li>返回参数中包含<code>code</code>和<code>msg</code>，<code>code</code>非0则为失败，<code>msg</code>记录失败信息。</li>
</ul>
<h2>Headers 的 Content-Type</h2>
<p>{"Content-Type": "application/json"}</p>
<h2>认证</h2>
<ul>
<li>在 headers 中增加 Basic auth 的认证，填入(username, password)。</li>
<li>username，password 在和我司签订合同并付费后提供。</li>
<li>快速体验可参考[快速测试体验](<a href="https://www.showdoc.com.cn/asopen/11558677539469292">https://www.showdoc.com.cn/asopen/11558677539469292</a> "快速测试体验")。</li>
<li>认证方式为 HTTP Basic Authorization，认证信息为 username:password，详细调用请参考[各语言的Basic Auth例程](<a href="https://www.showdoc.com.cn/asopen/11558693425837147">https://www.showdoc.com.cn/asopen/11558693425837147</a> "各语言的Basic Auth例程")。</li>
</ul>
<h2>Host</h2>
<p><a href="https://api.mqtt.asinfo.online">https://api.mqtt.asinfo.online</a></p>
<h2>通讯说明</h2>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=6536822592a3beec15125e8b74404d48&amp;file=file.png" alt="" /></p>
<h2>接口详情</h2>
<h3>发送设备命令</h3>
<p><strong>简要描述</strong>
向指定imei的设备发送命令。
!!! 此接口调用成功只代表命令成功传到MQTT服务器，并不代表设备能接收到命令。比如设备离线，设备MQTT参数没有按照我司提供的配置参数进行配置。</p>
<p><strong>请求URL</strong>
/device/cmd</p>
<p><strong>请求方式</strong>
POST</p>
<p><strong>请求参数</strong></p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>必须</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>imei</td>
<td>是</td>
<td>string</td>
<td>设备imei</td>
</tr>
<tr>
<td>data</td>
<td>是</td>
<td>object</td>
<td>要发送给设备的命令，命令协议参考[设备通讯协议命令](<a href="https://www.showdoc.com.cn/asopen/11558675454686779">https://www.showdoc.com.cn/asopen/11558675454686779</a> "设备通讯协议命令")</td>
</tr>
</tbody>
</table>
<p><strong>请求示例</strong></p>
<pre><code>body
{
&quot;imei&quot;: &quot;51546468468797&quot;,
&quot;data&quot;: {
&quot;method&quot;: &quot;getDevInfo&quot;,
&quot;frameId&quot;: &quot;1745396239780&quot;
}
}</code></pre>
<p><strong>返回参数</strong></p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>int</td>
<td>执行结果code，非 0 表示失败，详情参见<code>msg</code>说明</td>
</tr>
<tr>
<td>msg</td>
<td>string</td>
<td>执行结果消息</td>
</tr>
</tbody>
</table>
<p><strong>应答示例</strong></p>
<pre><code>body
{
&quot;code&quot;: 0,
&quot;msg&quot;: &quot;success&quot;
}
</code></pre>
<p><strong>备注</strong>
无</p>
<h3>设备应答回调地址配置</h3>
<p><strong>简要描述</strong>
配置回调地址，用来接收设备的应答。
设备接收到命令后，会执行命令，然后返回应答，应答会以 HTTP POST 方式请求到 url， body 内容是应答数据，用 json 格式。
回调返回内容参考 [设备通讯协议命令](<a href="https://www.showdoc.com.cn/asopen/11558675454686779">https://www.showdoc.com.cn/asopen/11558675454686779</a> "设备通讯协议命令")。</p>
<p><strong>请求URL</strong>
/callback/config</p>
<p><strong>请求方式</strong>
POST</p>
<p><strong>请求参数</strong></p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>必须</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>url</td>
<td>是</td>
<td>string</td>
<td>回调地址 url，必须是公网可以访问到</td>
</tr>
<tr>
<td>username</td>
<td>否</td>
<td>string</td>
<td>回调地址 Basic Authorization 中的 username</td>
</tr>
<tr>
<td>password</td>
<td>否</td>
<td>string</td>
<td>回调地址 Basic Authorization 中的 password</td>
</tr>
</tbody>
</table>
<p><strong>请求示例</strong></p>
<pre><code>body
{
&quot;url&quot;: &quot;https://xxx.com/callback/test&quot;,
&quot;username&quot;: &quot;xxxxx&quot;,
&quot;password&quot;: &quot;xxxxx&quot;
}</code></pre>
<p><strong>返回参数</strong></p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>int</td>
<td>执行结果 code，非 0 表示失败，详情参见<code>msg</code>说明</td>
</tr>
<tr>
<td>msg</td>
<td>string</td>
<td>执行结果消息</td>
</tr>
</tbody>
</table>
<p><strong>应答示例</strong></p>
<pre><code>body
{
&quot;code&quot;: 0,
&quot;msg&quot;: &quot;success&quot;
}
</code></pre>
<p><strong>备注</strong>
例如获取设备基本信息的应答数据如下：</p>
<pre><code>{
&quot;method&quot;: &quot;getDevInfo&quot;,
&quot;result&quot;: &quot;ok&quot;,
&quot;version&quot;: &quot;SWITCH-EC618X-R24-O-V4.0.8&quot;,
&quot;slotAmount&quot;: 1,
&quot;phaseAmount&quot;: 1,
&quot;imei&quot;: &quot;1745396239780&quot;,
&quot;frameId&quot;: &quot;1745396239780&quot;,
&quot;timestamp&quot;: 1745396759
}</code></pre>
<p>应答数据参数说明</p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>method</td>
<td>string</td>
<td>getDevInfo</td>
</tr>
<tr>
<td>result</td>
<td>string</td>
<td>返回结果。<code>ok</code>-成功；其他-具体失败原因</td>
</tr>
<tr>
<td>version</td>
<td>string</td>
<td>版本号</td>
</tr>
<tr>
<td>slotAmount</td>
<td>int</td>
<td>插槽数量，开关类设备支持</td>
</tr>
<tr>
<td>phaseAmount</td>
<td>int</td>
<td>相位数量，开关类设备支持</td>
</tr>
<tr>
<td>imei</td>
<td>string</td>
<td>设备imei</td>
</tr>
<tr>
<td>frameId</td>
<td>string</td>
<td>同命令frameId</td>
</tr>
<tr>
<td>timestamp</td>
<td>int</td>
<td>秒级时间戳，WiFi款不支持</td>
</tr>
</tbody>
</table>
<h3>发送设备命令并等待设备应答（测试中）</h3>
<p><strong>简要描述</strong>
向指定imei的设备发送命令，并等待设备应答。
！！！注意：如果timeout设置过短，或设备移动网络延时等问题，会导致设备接收到命令且有返回，但此接口返回超时错误。</p>
<p><strong>请求URL</strong>
/device/cmd_wait/{frameId}</p>
<p><strong>请求方式</strong>
POST</p>
<p><strong>请求参数</strong></p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>必须</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>imei</td>
<td>是</td>
<td>string</td>
<td>设备imei</td>
</tr>
<tr>
<td>frameId</td>
<td>是</td>
<td>string</td>
<td>作为帧ID发送给设备，设备应答会返回相同的帧ID。！！！注意：url的frameId，和data里面的frameId都必须填，且为一样的值，如/device/cmd_wait/1745396239780</td>
</tr>
<tr>
<td>timeout</td>
<td>是</td>
<td>int</td>
<td>超时秒数，超时会返回<code>code</code>为<code>204</code></td>
</tr>
<tr>
<td>data</td>
<td>是</td>
<td>object</td>
<td>要发送给设备的命令，命令协议参考[设备通讯协议命令](<a href="https://www.showdoc.com.cn/asopen/11558675454686779">https://www.showdoc.com.cn/asopen/11558675454686779</a> "设备通讯协议命令")</td>
</tr>
</tbody>
</table>
<p><strong>请求示例</strong></p>
<pre><code>body
{
&quot;imei&quot;: &quot;1745396239780&quot;,
&quot;timeout&quot;: 5,
&quot;data&quot;: {
&quot;method&quot;: &quot;getDevInfo&quot;,
&quot;frameId&quot;: &quot;1745396239780&quot;
}
}</code></pre>
<p><strong>返回参数</strong></p>
<table>
<thead>
<tr>
<th>参数名</th>
<th>类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>int</td>
<td>执行结果code，非 0 表示失败，详情参见<code>msg</code>说明</td>
</tr>
<tr>
<td>msg</td>
<td>string</td>
<td>执行结果消息</td>
</tr>
<tr>
<td>data</td>
<td>string</td>
<td>设备应答json字符串，应答数据说明参考参考[设备通讯协议命令](<a href="https://www.showdoc.com.cn/asopen/11558675454686779">https://www.showdoc.com.cn/asopen/11558675454686779</a> "设备通讯协议命令")</td>
</tr>
</tbody>
</table>
<p><strong>应答示例</strong></p>
<pre><code>body
{
&quot;code&quot;: 0,
&quot;msg&quot;: &quot;success&quot;,
&quot;data&quot;: &quot;{\&quot;method\&quot;:\&quot;getDevInfo\&quot;,\&quot;result\&quot;:\&quot;ok\&quot;,\&quot;version\&quot;:\&quot;SWITCH-EC618X-R24-O-V4.0.8\&quot;,\&quot;slotAmount\&quot;:1,\&quot;phaseAmount\&quot;:1,\&quot;imei\&quot;:\&quot;1745396239780\&quot;,\&quot;frameId\&quot;:\&quot;1745396239780\&quot;,\&quot;timestamp\&quot;:1745396759}&quot;
}
</code></pre>
<p><strong>备注</strong>
无</p>