1-3、海王星辰ipaas对外通用接口
<p>[TOC]</p>
<table>
<thead>
<tr>
<th>版本号</th>
<th>变更日期 </th>
<th>变更描述 </th>
<th>变更人</th>
</tr>
</thead>
<tbody>
<tr>
<td>V1.0 </td>
<td>2021/11/24</td>
<td>创建 </td>
<td>黄伟健</td>
</tr>
<tr>
<td>V1.1.0</td>
<td>2021/12/08</td>
<td>更改3.1 OAuth出入参示例 </td>
<td>黄伟健</td>
</tr>
<tr>
<td>V1.1.1</td>
<td>2021/12/10</td>
<td>补充接口请求示例 </td>
<td>叶卓 </td>
</tr>
<tr>
<td>V1.2 </td>
<td>2021/12/13</td>
<td>新增回调4.5同步经营门店库存 </td>
<td>黄伟健</td>
</tr>
<tr>
<td>V1.3 </td>
<td>2022/03/07</td>
<td>4.4新增若干字段,4.5新增库存所属门店标识 </td>
<td>黄伟健</td>
</tr>
<tr>
<td>V1.4 </td>
<td>2022/03/11</td>
<td>4.3新增字段isHealthIsr(国家医保商品标识),healthIsrCode(医保国家码)</td>
<td>黄伟健</td>
</tr>
<tr>
<td>V1.5 </td>
<td>2022/06/20</td>
<td>[5.1新增字段](<a href="https://www.showdoc.com.cn/nephealth/10201027046249193">https://www.showdoc.com.cn/nephealth/10201027046249193</a> "5.1新增字段")platformFreightDiscount(海王方运费优惠金额)、appFreightDiscount(商家方运费优惠金额)、platformDiscountAmt(单品(海王方)折让金额) 、appDiscountAmt(单品(接入方)折让金额) 删除字段unitPrice(商品支付价)</td>
<td>黄伟健</td>
</tr>
<tr>
<td>V1.6 </td>
<td>2023/07/21</td>
<td>4.3和5.5新增字段category1(一级分类)、category1Name(一级分类名称)、category2(二级分类)、category2Name(二级分类名称)、category3(三级分类)、category3Name(三级分类名称)、brandName(品牌名称)</td>
<td>黄伟健</td>
</tr>
<tr>
<td>V1.7 </td>
<td>2023/10/08</td>
<td>5.3新增字段peiSongStatusId(配送状态ID)、peiSongStatus(配送状态)、courierName(骑手名称)、courierPhone(骑手电话)、shippingReceivingTime(配送回调时间)</td>
<td>黄伟健</td>
</tr>
</tbody>
</table>
<h2>一、概述</h2>
<p>> 本文档主要是海王星辰ipaas平台通用接口规范。包括：ipaas通用接口中参数及返回值说明等内容。</p>
<h3>1.1接口方向的说明</h3>
<p>4.X的接口是海王调用第三方的
5.X的接口是第三方调用海王的</p>
<h2>二、接口规范</h2>
<h3>2.1安全验证</h3>
<p>> - 本套接口遵循Bearer Token (<a href="http://www.rfcreader.com/#rfc6750">RFC 6750</a>) 用于OAuth 2.0授权访问资源
> - 业务接口中以sign系统级参数进行请求校验，除Token请求接口外均需携带签名进行交互
> - 业务接口中以timestamp(时间戳10位)系统级参数有效时间为100秒
> - 业务接口中以nonce系统级参数校验重放攻击，唯一随机数,可以是uuid,每次请求都随机生成</p>
<h3>2.2协议格式</h3>
<h4>2.2.1 通信协议</h4>
<p>> - 请求参数与返回参数都以JSON 格式作为数据格式
> - 字符集默认使用 UTF-8,请勿使用其它字符集
> - 所有业务接口默认为post</p>
<h4>2.2.2 数据约束</h4>
<p>> - 与日期，时间有关的信息以yyyy-MM-dd HH:mm:ss格式传输
> - 与金额有关的信息以元为单位，保留两位小数（可按具体需求）
> - 业务接口非必填参数可不传，若传，则参数值不能为空</p>
<h3>2.3 系统级参数约束</h3>
<h4>2.3.1 请求说明</h4>
<p>> - 请求参数采用 JSON 格式
> - 包含sign，appKey，timestamp，nonce，input字段</p>
<table>
<thead>
<tr>
<th>参数名称 </th>
<th>参数类型</th>
<th>必填</th>
<th>说明 </th>
</tr>
</thead>
<tbody>
<tr>
<td>appKey </td>
<td>string </td>
<td>Y </td>
<td>商户Key(海王提供) </td>
</tr>
<tr>
<td>timestamp</td>
<td>long </td>
<td>Y </td>
<td>取当前时间戳(10位) </td>
</tr>
<tr>
<td>nonce </td>
<td>string </td>
<td>Y </td>
<td>唯一随机数,可以是uuid,每次请求都随机生成</td>
</tr>
<tr>
<td>sign </td>
<td>string </td>
<td>N </td>
<td>签名值 </td>
</tr>
<tr>
<td>input </td>
<td>object </td>
<td>N </td>
<td>业务模型 </td>
</tr>
</tbody>
</table>
<h4>2.3.2 返回说明</h4>
<p>> - 返回结果采用 JSON 格式
> - 包含code、msg、output字段</p>
<table>
<thead>
<tr>
<th>参数名称</th>
<th>参数类型</th>
<th>必填</th>
<th>说明 </th>
</tr>
</thead>
<tbody>
<tr>
<td>code </td>
<td>Integer </td>
<td>Y </td>
<td>200 标识成功，非200 失败</td>
</tr>
<tr>
<td>msg </td>
<td>string </td>
<td>Y </td>
<td>返回信息 </td>
</tr>
<tr>
<td>nonce </td>
<td>string </td>
<td>Y </td>
<td>请求时携带的随机数 </td>
</tr>
<tr>
<td>output </td>
<td>object </td>
<td>N </td>
<td>返回数据，json 格式 </td>
</tr>
</tbody>
</table>
<h3>2.4 签名方法</h3>
<p>客户端和服务端之间约定一个相同的秘钥secret(海王提供)，作为加密字符串的一部分</p>
<p>生成规则由字符串secret + timestamp + nonce拼接后进行MD5加密得出小写字符串后进行SHA1加密后得出小写字符串作为数据签名</p>
<p>demo:</p>
<pre><code>secret=Hwdiicysdgrffc012342de_dsr$221
timestamp=1637725871
nonce=BE6DD046-CAFB-B26F-7C9006BE48EA48D4
tempStr = Hwdiicysdgrffc012342de_dsr$2211637725871BE6DD046-CAFB-B26F-7C9006BE48EA48D4
md5Str = MD5(tempStr); 得出 1d121b5435f3281112c5a0c8ff66b77c
sign = SHA1(md5Str); 得出 39d8b31606bc3cf349540c9f52d586ea60aeb924</code></pre>
<h2>三、校验获取Token接口详细说明</h2>
<p>> - 测试接口地址:<a href="https://zttest.star365.com/orderBusiness">https://zttest.star365.com/orderBusiness</a>
> - 生产接口地址:<a href="https://zt.star365.com/orderBusiness">https://zt.star365.com/orderBusiness</a></p>
<h3>3.1 OAuth Bearer Token获取接口</h3>
<p>> - Url路径:authtoken</p>
<h4>3.1.1 接口请求模型</h4>
<table>
<thead>
<tr>
<th>参数名称 </th>
<th>参数类型</th>
<th>必填</th>
<th>说明 </th>
</tr>
</thead>
<tbody>
<tr>
<td>grant_type</td>
<td>string </td>
<td>Y </td>
<td>传入固定值:password </td>
</tr>
<tr>
<td>username </td>
<td>string </td>
<td>Y </td>
<td>用户名(海王技术提供)</td>
</tr>
<tr>
<td>password </td>
<td>string </td>
<td>Y </td>
<td>密码(海王技术提供) </td>
</tr>
</tbody>
</table>
<h4>3.1.2 接口返回模型</h4>
<table>
<thead>
<tr>
<th>参数名称 </th>
<th>参数类型</th>
<th>必填</th>
<th>说明 </th>
</tr>
</thead>
<tbody>
<tr>
<td>access_token</td>
<td>string </td>
<td>Y </td>
<td>返回的token </td>
</tr>
<tr>
<td>expires_in </td>
<td>int </td>
<td>Y </td>
<td>剩余有效期(秒) 一般是86399</td>
</tr>
<tr>
<td>token_type </td>
<td>string </td>
<td>Y </td>
<td>请求业务接口头部类型bearer</td>
</tr>
</tbody>
</table>
<p>Demo:</p>
<pre><code>Method:POST
Content-Type: application/x-www-form-urlencoded</code></pre>
<p>Request:</p>
<pre><code>grant_type=password&amp;password=5XuwtoUQgWVME2vwt9fsAOOYF5noaVXKl2z3o9jrITTqVE3VzNHnnhSPDvhCosANtRj92bO8Rplh4B6h1DIw5zzmqLhFjcRbZiQrjC0iZPo5M0VAqZZGrpuRcb0LwFWS&amp;username=test</code></pre>
<p>Response:</p>
<pre><code>{
&quot;access_token&quot;: &quot;HwoNTKEcoCeB4vrxsBiop5yQfMA4bQiXBftrifVZndea85hyxtIoce-2XJzuZyRjM46Szw7Sv2Pq3RIAbi7dL5-dwoZEol9AEILeQ34DrCXAdxnGV4X_s6XCrjU3FKusyddcubkU-Ix3Ti5XvcxdUCxnXohUDajivHxItlmEvHuGq5qd3ovRJtvOxvAhuzKhyqvd686R7f5-sedQOF83Ej7WZRG9A7um7RYEM1V&quot;,
&quot;expires_in&quot;: 85370,
&quot;token_type&quot;: &quot;bearer&quot;
}</code></pre>