1-3 九医云商城对外通用接口
<h1>九医云商城Sass对外通用接口</h1>
<table>
<thead>
<tr>
<th>版本号</th>
<th>变更日期 </th>
<th>变更描述 </th>
<th>变更人</th>
</tr>
</thead>
<tbody>
<tr>
<td>V1.0 </td>
<td>2023/09/18</td>
<td>创建 </td>
<td>李呈云</td>
</tr>
</tbody>
</table>
<p>[TOC]</p>
<h2>一、概述</h2>
<p>> 本文档主要是九医云平台通用接口规范。包括：通用接口中参数及返回值说明等内容。</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://test.91medicine.net/gateway/auth-server/">https://test.91medicine.net/gateway/auth-server/</a>
> - 生产接口地址:<a href="https://cloud.91medicine.cn/gateway/auth-server/">https://cloud.91medicine.cn/gateway/auth-server/</a></p>
<h3>3.1 OAuth Bearer Token获取接口</h3>
<p>> - Url路径:oauth/token</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:GET
Request:
grant_type=pwd&amp;username=jiuwei&amp;password=yf2023&amp;platform=shop&amp;Auto-Key=e33cc4e2-91a2-43d0-abeb-cbfcc42eb1e4&amp;client_id=dt&amp;client_secret=dt&amp;scope=all&amp;need=false&amp;headStoreUuid=
Response:
{
&quot;code&quot;: 0,
&quot;msg&quot;: &quot;&quot;,
&quot;data&quot;: {
&quot;access_token&quot;: &quot;baa2dc2b-2bf7-4202-bb13-f7ef3f16fcc9&quot;,
&quot;token_type&quot;: &quot;bearer&quot;,
&quot;refresh_token&quot;: &quot;dbf99cbe-3699-42ab-b423-32ac28e07e23&quot;,
&quot;expires_in&quot;: 601631,
&quot;scope&quot;: &quot;all&quot;
}
}</code></pre>