开放平台对接说明文档
<table>
<thead>
<tr>
<th>请提供如下信息，提前找开放平台管理人员开户</th>
</tr>
</thead>
<tbody>
<tr>
<td>企业名称</td>
</tr>
<tr>
<td>税号</td>
</tr>
<tr>
<td>管理员名称</td>
</tr>
<tr>
<td>管理员手机号</td>
</tr>
<tr>
<td>回调地址（测试环境）</td>
</tr>
<tr>
<td>回调地址（生产环境）</td>
</tr>
<tr>
<td>IP地址（测试环境）</td>
</tr>
<tr>
<td>IP地址（生产环境）</td>
</tr>
</tbody>
</table>
<h1>1.环境说明</h1>
<h2>1.1 概述</h2>
<p>本文档旨在指导开发者在沙箱环境和生产环境中对接运之盟开放平台。请按照以下步骤进行操作。 </p>
<h2>1.2 环境切换</h2>
<p>运之盟开放平台提供了沙箱环境和生产环境，分别用于开发和测试以及正式上线运行。请确保在开发阶 段使用沙箱环境，而在上线前切换到生产环境。 </p>
<h3>1.2.1 沙箱环境</h3>
<p>沙箱环境用于开发和测试，具有模拟真实环境的功能，但不产生真实交易。在沙箱环境中，您可以使用 测试数据和模拟工具进行对接测试。 </p>
<pre><code>API地址： https://open-beta.56yzm.com:8443 </code></pre>
<ul>
<li>
<p>访问凭证： 请向开放平台申请沙箱环境的访问凭证（ client_id , client_secret ）或联系工作 人员协助处理。 </p>
</li>
<li>账号注册： 请向开放平台申请沙箱环境的注册用户或联系工作人员协助处理。 </li>
</ul>
<h3>1.2.2 生产环境</h3>
<p>生产环境用于正式上线运行，产生真实交易数据。在切换到生产环境之前，请确保您的系统已通过沙箱 环境的测试。</p>
<pre><code>API地址： https://open-prod.56yzm.com</code></pre>
<ul>
<li>
<p>访问凭证： 请向开放平台申请生产环境的访问凭证（ client_id , client_secret ）或联系工作 人员协助处理。</p>
</li>
<li>账号注册： 请向开放平台申请生产环境的注册用户或联系工作人员协助处理。 </li>
</ul>
<h3>1.2.3 token 规则</h3>
<ul>
<li>
<p>生产环境的 access_token 有效期为 7199秒 （2 小时）。 请提前换 token</p>
</li>
<li>
<p>我方返回的token，具有唯一性（只会保留最新返回的那次token，其他的token会立即失效）</p>
</li>
<li>如果请求并发大，重复申请token，会导致token使用错乱，我方建议使用 redis 存储token，保证token的唯一性</li>
</ul>
<table>
<thead>
<tr>
<th>频繁出现token失效 ？？？？</th>
</tr>
</thead>
<tbody>
<tr>
<td>1.是不是没有缓存 token值（如果遇到并发，就会互踢token）</td>
</tr>
<tr>
<td>2.是不是用的服务器缓存（如果token存在服务器，多节点，多服务， 会导致token存在多个）</td>
</tr>
<tr>
<td>3.token，是不是存在了多个平台，没有做到共享同一个token</td>
</tr>
<tr>
<td>4.token是不是 缓存了 两小时 以内</td>
</tr>
<tr>
<td>5.token存在reids中，是不是存了多份（比如：多平台或者多服务调用，一个平台、一个服务存一个token）</td>
</tr>
</tbody>
</table>
<h2>1.3 认证与授权</h2>
<p>在使用运之盟开放平台的API之前，您需要进行认证并获取注册用户和访问凭证。不同环境的认证方式相 同，但用户和凭证不通用，沙箱环境和生产环境分别需要申请。 </p>
<h4><strong>PS：如果您是运之盟开放平台用户下的某个供应商用户， 请联系工作人员申请供应商用户代码（user-code）。</strong></h4>
<h1>2.获取AccessToken</h1>
<h2>2.1 凭证模式</h2>
<p>OAuth 2.0 中的凭证模式（Client Credentials Grant）用于客户端以自身身份请求访问令牌，而无需用 户的授权或用户的用户名和密码。这通常用于服务器对服务器的通信，而不涉及用户。</p>
<h3>步骤1：构建认证请求</h3>
<p>客户端构建一个 HTTP 请求，将用户的用户名和密码以及其他必要参数包含在请求中。请求应包含以下 参数：</p>
<ul>
<li>
<p>请求方法：POST </p>
</li>
<li>请求 URL：</li>
</ul>
<pre><code>https://open-beta.56yzm.com:8443/open-oauth/oauth/token（更换对应环境的域名） </code></pre>
<ul>
<li>请求头：包含客户端的身份验证信息，这里是Basic 认证的客户端ID和客户端密钥。</li>
</ul>
<p><code>Content-Type：application/x-www-form-urlencoded</code></p>
<ul>
<li>请求体：包含以下参数：</li>
</ul>
<p><code>grant_type ：授权类型，为 &quot;client_credentials&quot; 。</code></p>
<p><code>client_id ：颁发用户凭证的客户端Id。</code></p>
<p><code>client_secret ：颁发用户凭证的客户端秘钥。</code> </p>
<ul>
<li>示例请求：</li>
</ul>
<pre><code>POST /open-oauth/oauth/token HTTP/1.1
Host: https://open-beta.56yzm.com:8443
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&amp;client_id={client_id}&amp;client_secret= {client_secret}</code></pre>
<h3>步骤2：发送认证请求</h3>
<p>将构建的认证请求发送到授权服务器的 Token 端点。</p>
<h3>步骤3：处理响应</h3>
<p>客户端可以使用令牌来继续访问受保护资源。</p>
<ul>
<li>示例响应：
<pre><code>{
&quot;access_token&quot;: &quot;eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJvcGVuVXNlcklkIjoxLCJncmFudFR5cGUiOiJjbG llbnRfY3JlZGVudGlhbHMiLCJ0aW1lc3RhbXAiOjE3MDQ2ODE0OTk4OTV9.h3NfgKCZdWW7VzhLdaBFIltXSPdOKYBrdk9dWuwCHU&quot;,
&quot;token_type&quot;: &quot;bearer&quot;,
&quot;expires_in&quot;: 6102,
&quot;scope&quot;: &quot;read&quot;
}</code></pre></li>
</ul>
<h1>3. 使用 Access Token 请求 API</h1>
<h2>3.1 公共接口</h2>
<h3>步骤1：构建 API 请求</h3>
<p>构建一个 HTTP 请求，将 Access Token 包含在请求头的 Authorization 字段中。</p>
<ul>
<li>请求方法：根据 API 的要求。</li>
<li>请求 URL：API 的终端点 URL。（更换对应环境的域名）</li>
<li>请求头：包含 Authorization 字段，值为 Bearer 后跟你的 Access Token。</li>
</ul>
<p>这里我们使用 文件上传接口 callback/file/upload 作为 请求示例:</p>
<pre><code>POST {callback/file/upload} HTTP/1.1
Host: https://open-beta.56yzm.com:8443
Content-Type : multipart/form-data
Authorization: Bearer {your_access_token}
fileType={fileType}&amp;file={file}</code></pre>
<h3>步骤2：发送 API 请求</h3>
<p>将构建的 API 请求发送到相应的 API 终端点。</p>
<h3>步骤3：处理 API 响应</h3>
<p>API 将验证请求中的 Access Token 的有效性，如果有效，将返回资源的响应。</p>
<ul>
<li>示例 API 响应</li>
</ul>
<pre><code>{
&quot;biz_code&quot;: null,
&quot;biz_msg&quot;: null,
&quot;code&quot;: 200,
&quot;msg&quot;: &quot;业务处理成功&quot;,
&quot;data&quot;: {
&quot;sourceFileName&quot;: &quot;1.jpg&quot;,
&quot;fileUrl&quot;: &quot;https://img.56yzm.com/dev/image/2024/1/51f4f0fad608a8399f463bbd7cd76f0b.jpg&quot;
},
&quot;data_total&quot;: null
}</code></pre>
<h2>3.2 业务接口</h2>
<h3>步骤1：构建 API 请求</h3>
<p>构建一个 HTTP 请求，将 Access Token 包含在请求头的 Authorization 字段中。</p>
<ul>
<li>
<p>请求方法：根据 API 的要求。</p>
</li>
<li>
<p>请求 URL：API 的终端点 URL。（更换对应环境的域名）</p>
</li>
<li>请求头：</li>
</ul>
<p><code>包含 Authorization 字段，值为 Bearer 后跟你的 Access_Token。</code></p>
<p><code>包含 user-code 字段，值为 供应商用户的用户代码 （用于识别该用户下具体的供应商用户）。</code></p>
<ul>
<li>这里我们使用 发票分页接口 /api-server/invoice/pageInvoice 作为 请求示例</li>
</ul>
<pre><code>POST {/api-server/invoice/pageInvoice} HTTP/1.1
Host: https://open-beta.56yzm.com:8443
Content-Type : application/json;charset=UTF-8
user-code : {your_user_code}
Authorization: Bearer {your_access_token}
{
&quot;pageQuery&quot;: {
&quot;page&quot;: 1,
&quot;size&quot;: 10,
&quot;total&quot;: 0
}
}</code></pre>
<h3>步骤2：发送 API 请求</h3>
<p>将构建的 API 请求发送到相应的 API 终端点</p>
<h3>步骤3：处理 API 响应</h3>
<p>API 将验证请求中的 Access Token 的有效性，如果有效，将返回资源的响应。</p>
<ul>
<li>示例 API 响应</li>
</ul>
<pre><code>{
&quot;code&quot;: 200,
&quot;data&quot;: {
&quot;code&quot;: 200,
&quot;msg&quot;: &quot;查询成功&quot;,
&quot;page&quot;: 1,
&quot;rows&quot;: [
{
&quot;applyCode&quot;: &quot;20231116202109t5hvr&quot;,
&quot;applyName&quot;: &quot;江苏恒力新材料科技有限公司&quot;,
&quot;invoiceStatusText&quot;: &quot;申请中&quot;,
&quot;openInvoiceTypeText&quot;: &quot;纸质发票&quot;
}
],
&quot;size&quot;: 10,
&quot;total&quot;: 16
},
&quot;msg&quot;: &quot;操作成功&quot;
}</code></pre>