请求鉴权及公共参数说明
<h3>测试服务主机地址</h3>
<p><code>https://mxboss.xinghansoft.com</code></p>
<p><b style="color: red;">若无特殊说明, 所有接口均使用POST方法通信, 使用JSON作为通信数据格式</b></p>
<h3>验证信息</h3>
<ul>
<li>
<p>测试环境:</p>
<p>AK: <code>zsgo</code></p>
<p>SK: <code>FPgIVc1hyKUG8xej2KyuywOoE4Ab0LUO</code></p>
</li>
<li>
<p>正式环境:</p>
<p>待定</p>
</li>
</ul>
<h3>请求头</h3>
<table>
<thead>
<tr>
<th style="text-align: left;">名称<div style="width: 100pt"></th>
<th style="text-align: left;">必填</th>
<th style="text-align: left;">类型</th>
<th>字段描述<div style="width: 200pt"></th>
<th>备注<div style="width: 180pt"></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">MX-Ak</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>对应验证信息中的<code>AK</code>字段</td>
<td>例如： zsgo</td>
</tr>
<tr>
<td style="text-align: left;">MX-Timestamp</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>POSIX时间戳,1970-01-01 UTC至今的秒数</td>
<td>例如： 1718889455</td>
</tr>
<tr>
<td style="text-align: left;">MX-Noise</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>随机字符串，防重放攻击（5分钟内不可重复）</td>
<td>例如： 1ca430cdcbdd4b8b87e280161608fdde</td>
</tr>
<tr>
<td style="text-align: left;">MX-Signature</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>签名信息</td>
<td>例如： da2a90815cd6248caa4b62a389c27917e4b4f15c4303ed6b6bf42a62932289a3</td>
</tr>
</tbody>
</table>
<h3>公共参数</h3>
<p><b>通过URL-QueryString附加在请求URI尾部, 不是所有接口均需要验证全部公共参数, 接口所需的公共参数会在接口文档中注明</b></p>
<table>
<thead>
<tr>
<th style="text-align: left;">名称<div style="width: 100pt"></th>
<th style="text-align: left;">类型</th>
<th>字段描述<div style="width: 200pt"></th>
<th>备注<div style="width: 180pt"></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">openid</td>
<td style="text-align: left;">string</td>
<td>微信小程序用户的用户标识信息, 系统需通过此值关联对应用户</td>
<td>例如： 202203031550069761096753606</td>
</tr>
<tr>
<td style="text-align: left;">pageabled</td>
<td style="text-align: left;">boolean</td>
<td>启用分页</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">pageNo</td>
<td style="text-align: left;">int</td>
<td>分页参数, 当前页页码</td>
<td>起始: 1</td>
</tr>
<tr>
<td style="text-align: left;">pageSize</td>
<td style="text-align: left;">int</td>
<td>分页参数, 一页数据数量</td>
<td>默认: 20</td>
</tr>
</tbody>
</table>
<h4>签名步骤</h4>
<ol>
<li>准备当前接口名称(<code>endpoint</code>)字符串, 不包括主机地址域名和端口号.</li>
<li>将请求参数(包括URL-QueryString和form-data)按照参数名称字典序升序排列,
并将排列后的参数按照key=value的形式拼接成字符串, 不同参数之间使用&分隔.
此字符串记为<code>paramStr</code>, 可为空.</li>
<li>计算请求体(Body)的MD5值（注意, form-data不算作请求体）,
将md5值使用小写16进制写成字符串, 此字符串记为<code>bodyMd5</code>. 注意：空值也具有md5.</li>
<li>准备POSIX时间戳字符串（即1970-01-01 UTC至今的秒数）, 此字符串记为<code>timestamp</code>.</li>
<li>生成一个随机字符串, 记为<code>noise</code>.</li>
<li>将上述五个字符串拼接为<code>$endpoint|$paramStr|$bodyMd5|$timestamp|$noise</code>, 记为signStr.</li>
<li>以验证信息的SK字段作为密钥,使用<code>HMAC-SHA256</code>对<code>signStr</code>进行签名，将其转为16进制小写即为签名结果.</li>
<li>将AK, 时间戳, 随机串写入请求头对应位置,并将签名结果写入请求头<code>MX-Signature</code>字段中.</li>
</ol>
<h4>请求成功响应结构</h4>
<p>响应信息有统一封包结构, 若无特殊说明, 接口文档中的响应示例, 均为封包结构中的data信息.</p>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名<div style="width: 100pt"></th>
<th style="text-align: left;">必填</th>
<th style="text-align: left;">类型</th>
<th>字段描述<div style="width: 200pt"></th>
<th>备注<div style="width: 180pt"></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">code</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>业务结果</td>
<td>若接口无特殊约定, 0-成功, 1-失败</td>
</tr>
<tr>
<td style="text-align: left;">message</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">string</td>
<td>结果信息描述</td>
<td>若code不为0时, 将携带失败信息</td>
</tr>
<tr>
<td style="text-align: left;">data</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">object/array</td>
<td>响应数据载荷</td>
<td>通常为object或array, 无响应数据接口则为空</td>
</tr>
<tr>
<td style="text-align: left;">extra</td>
<td style="text-align: left;">否</td>
<td style="text-align: left;">object</td>
<td>额外信息</td>
<td>固定为key-value Mapping, 内容由文档具体约定</td>
</tr>
</tbody>
</table>
<h4>通用成功响应示例</h4>
<pre><code>{
&quot;code&quot;: 0,
&quot;message&quot;: &quot;操作成功&quot;,
&quot;data&quot;: { ... }, // object or array
&quot;extra&quot;: { ... }
}</code></pre>
<h4>分页请求响应结构</h4>
<p>注意: 响应载荷同样置于统一封包中的data数据中.<br>
若标注为分页接口, 公共参数可选携带<code>pageNo</code>,<code>pageSize</code>信息.<br>
若未携带分页信息, 则默认视作查询前20条数据.<br>
分页接口的响应体说明默认为list载荷数据. 外围结构不再赘述.<br></p>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名<div style="width: 100pt"></th>
<th style="text-align: left;">必填</th>
<th style="text-align: left;">类型</th>
<th>字段描述<div style="width: 200pt"></th>
<th>备注<div style="width: 180pt"></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">pageNo</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>当前页码</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">pageSize</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>一页条目上限数量</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">currentSize</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>本页实际条目数量</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">allRow</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>总条目数量</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">allPage</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">int</td>
<td>总页数</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">list</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">array</td>
<td>页列表数据</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">empty</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">boolean</td>
<td>是否为空列表</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">usable</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">boolean</td>
<td>页码是否有效(即小于等于总页数)</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">first</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">boolean</td>
<td>是否为首页</td>
<td></td>
</tr>
<tr>
<td style="text-align: left;">last</td>
<td style="text-align: left;">是</td>
<td style="text-align: left;">boolean</td>
<td>是否为末页</td>
<td></td>
</tr>
</tbody>
</table>
<h4>签名示例</h4>
<p>使用测试环境的主机地址及验证信息<br>
接口名称 <code>/bos/scooter/goapi/ping</code><br>
公共参数 <code>openid=202203031550069761096753606</code><br>
请求载荷 <code>{&quot;message&quot;:&quot;Hello World!&quot;,&quot;timestamp&quot;:&quot;2025-08-04 12:58:15&quot;}</code><br>
签名信息: </p>
<pre><code>endpoint /bos/scooter/goapi/ping
paramStr openid=202203031550069761096753606
bodyMd5 1c09030ef2a5a68bff352e907d22a764
timestamp 1754283494
noise e47191dbcdfa4407b23112dd38507010</code></pre>
<p>签名原串: </p>
<pre><code>/bos/scooter/goapi/ping|openid=202203031550069761096753606|1c09030ef2a5a68bff352e907d22a764|1754283494|e47191dbcdfa4407b23112dd38507010</code></pre>
<p>签名结果:</p>
<pre><code>bfcfd1ccaec76da98b6a8988bd26f74f3ea10e4683e3225953118678eb72aeec</code></pre>
<p>完整请求报文示例:</p>
<pre><code>POST https://mxboss.xinghansoft.com/bos/scooter/goapi/ping?openid=202203031550069761096753606
Host mxboss.xinghansoft.com
Endpoint /bos/scooter/goapi/ping
QueryString openid=202203031550069761096753606
Headers:
Content-Type [application/json]
MX-Ak [zsgo]
MX-Noise [e47191dbcdfa4407b23112dd38507010]
MX-Signature [bfcfd1ccaec76da98b6a8988bd26f74f3ea10e4683e3225953118678eb72aeec]
MX-Timestamp [1754283494]
Body:
{&quot;message&quot;:&quot;Hello World!&quot;,&quot;timestamp&quot;:&quot;2025-08-04 12:58:15&quot;}</code></pre>
<p>完整响应报文示例:</p>
<pre><code>Response Status-Code 200
POST https://mxboss.xinghansoft.com/bos/scooter/goapi/ping?openid=202203031550069761096753606
Headers:
connection [keep-alive]
content-type [application/json;charset=UTF-8]
date [Mon, 04 Aug 2025 04:58:14 GMT]
server [nginx/1.22.1]
transfer-encoding [chunked]
vary [Origin, Access-Control-Request-Method, Access-Control-Request-Headers]
Body:
{&quot;extra&quot;:{},&quot;code&quot;:0,&quot;message&quot;:&quot;操作成功&quot;,&quot;data&quot;:&quot;from [zsgo] request with [{\&quot;message\&quot;:\&quot;Hello World!\&quot;,\&quot;timestamp\&quot;:\&quot;2025-08-04 12:58:15\&quot;}]&quot;} </code></pre>
<h4>通用请求失败响应信息</h4>
<hr />
<h5>HTTP Status Code: 400</h5>
<p>传入参数有误, 响应体为文本, 内容为参数错误原因描述</p>
<hr />