发票开具-全电
<p>[TOC]</p>
<p><a name="使用流程"></a></p>
<h2>使用流程</h2>
<p>第一步：用户提供【企业税号、所属省份、复核人、收款人、开票人、地址&电话、银行&帐号】，由聚美智数通过这个信息生成唯一spid [税票id]
第二步：聚美智数提供全电发票开具接口配套系统，用户安装
第三步：通过生成的 spid [税票id] ，拼装发票报文json ，调用发票开票接口即可</p>
<p><a name="接口调用方式"></a></p>
<h2>接口调用说明</h2>
<h3>请求方式</h3>
<p>如接口没有单独说明，均为：<strong>POST</strong></p>
<h3>请求格式</h3>
<p>如接口没有单独说明，均为：<strong>application/x-www-form-urlencoded</strong></p>
<h3>请求参数</h3>
<p>请求参数包括公共参数和业务参数（业务参数见具体接口说明）
调用接口时，需要把<strong>公共参数</strong>和<strong>业务参数</strong>一并放在<strong>请求参数</strong>中提交</p>
<h4>公共请求参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>appId</td>
<td>String</td>
<td>是</td>
<td>服务商分配的唯一标识</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>是</td>
<td>当前时间戳（毫秒）</td>
</tr>
<tr>
<td>sign</td>
<td>String</td>
<td>是</td>
<td>签名，详见<a href="#签名算法">签名算法说明</a></td>
</tr>
</tbody>
</table>
<p><a name="签名算法"></a></p>
<h4>签名算法说明</h4>
<pre><code>sign = sha256(appId + appSecret + timestamp)</code></pre>
<p>用服务商分配的 <strong>appId</strong>、服务商分配的 <strong>appSecret</strong>，当前时间戳（毫秒） <strong>timestamp</strong>，按上述顺序拼接成字符串，再进行 <strong>sha256</strong> 哈希得到。如下：</p>
<pre><code class="language-java">String appId = &quot;xyzxy2121zxyz&quot;；
String timestamp = &quot;1555378976238&quot;；
String appSecret = &quot;efcefcef1121cefcefc1212121&quot;；
String str = appId + appSecret + timestamp；
String sign = sha256(str)；</code></pre>
<h3>返回说明</h3>
<h4>公共返回字段说明</h4>
<p>所有接口均返回以下公共字段：</p>
<table>
<thead>
<tr>
<th>字段名</th>
<th><div style="width:420px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>返回码，详见：公共code返回码说明</td>
</tr>
<tr>
<td>msg</td>
<td>code对应的描述</td>
</tr>
<tr>
<td>charge</td>
<td>计费标志</td>
</tr>
<tr>
<td>taskNo</td>
<td>本次请求号</td>
</tr>
<tr>
<td>data</td>
<td>返回具体结果，object类型，详见data返回字段描述</td>
</tr>
</tbody>
</table>
<h4>公共code返回码说明</h4>
<p>所有接口公共返回码如下：</p>
<table>
<thead>
<tr>
<th>code</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>成功，注：开票接口指接口调用成功，不表示发票开具成功</td>
</tr>
<tr>
<td>400</td>
<td>参数错误</td>
</tr>
<tr>
<td>404</td>
<td>接口地址不正确</td>
</tr>
<tr>
<td>500</td>
<td>系统维护，请稍候再试</td>
</tr>
<tr>
<td>601</td>
<td>接口未开通</td>
</tr>
<tr>
<td>602</td>
<td>账号停用</td>
</tr>
<tr>
<td>604</td>
<td>接口停用</td>
</tr>
<tr>
<td>606</td>
<td>调用超限，请稍候再试</td>
</tr>
<tr>
<td>607</td>
<td>ip不在白名单</td>
</tr>
<tr>
<td>609</td>
<td>请求过于频繁，请稍候再试</td>
</tr>
<tr>
<td>610</td>
<td>请求超时</td>
</tr>
<tr>
<td>999</td>
<td>其他，以实际返回为准</td>
</tr>
</tbody>
</table>
<p><a name="全电发票开具"></a></p>
<h2>全电发票开具</h2>
<h3>接口描述</h3>
<ul>
<li>全电发票开具（含蓝字和红字发票）</li>
</ul>
<h3>请求地址</h3>
<p><code>https://api.jumdata.com/invoice/makeout</code></p>
<h3>业务参数</h3>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>spid</td>
<td>String</td>
<td>是</td>
<td>税票id，联系服务商获取</td>
</tr>
<tr>
<td>data</td>
<td>String</td>
<td>是</td>
<td>发票报文json，详见发票报文data说明</td>
</tr>
</tbody>
</table>
<h3>发票报文data说明</h3>
<h4>报文结构</h4>
<p>> 注：报文节点全大写</p>
<pre><code>[{
&quot;XTLSH&quot;: &quot;单据号&quot;,
&quot;KHMC&quot;: &quot;客户名称&quot;,
&quot;KHSH&quot;: &quot;税号&quot;,
&quot;KHDZ&quot;: &quot;地址&quot;,
&quot;KHKHYHZH&quot;: &quot;客户银行账号&quot;,
&quot;FPZL&quot;: &quot;发票种类&quot;,
&quot;BZ&quot;: &quot;备注&quot;,
&quot;KPR&quot;: &quot;开票人&quot;,
&quot;SKR&quot;: &quot;收款人&quot;,
&quot;FHR&quot;: &quot;复核人&quot;,
&quot;QYKHYHZH&quot;: &quot;企业开户银行账号&quot;,
&quot;QYDZDH&quot;: &quot;企业地址电话&quot;,
&quot;YFPHM&quot;: &quot;红冲原发票号&quot;,
&quot;XXBBH&quot;: &quot;信息表编号&quot;,
&quot;QDBZ&quot;: &quot;清单标志&quot;,
&quot;KHYJ&quot;: &quot;客户邮件&quot;,
&quot;KHSJ&quot;: &quot;客户手机号&quot;,
&quot;JDC&quot;: &quot;机动车标识&quot;,
&quot;DBTS&quot;: &quot;代办退税标识&quot;,
&quot;ITEM&quot;: [{
&quot;CPMC&quot;: &quot;产品名称1&quot;,
&quot;CPXH&quot;: &quot;产品型号&quot;,
&quot;CPDW&quot;: &quot;产品单位&quot;,
&quot;SL&quot;: &quot;税率&quot;,
&quot;CPSL&quot;: &quot;数量&quot;,
&quot;BHSJE&quot;: &quot;不含税金额&quot;,
&quot;SE&quot;: &quot;税额&quot;,
&quot;FLBM&quot;: &quot;分类编码&quot;,
&quot;XSYH&quot;: &quot;税率优惠&quot;,
&quot;KCJE&quot;:&quot;0&quot;
}, {
&quot;CPMC&quot;: &quot;产品名称2&quot;,
&quot;CPXH&quot;: &quot;产品型号&quot;,
&quot;CPDW&quot;: &quot;产品单位&quot;,
&quot;SL&quot;: &quot;税率&quot;,
&quot;CPSL&quot;: &quot;数量&quot;,
&quot;BHSJE&quot;: &quot;不含税金额&quot;,
&quot;SE&quot;: &quot;税额&quot;,
&quot;FLBM&quot;: &quot;分类编码&quot;,
&quot;XSYH&quot;: &quot;税率优惠&quot;,
&quot;KCJE&quot;:&quot;0&quot;
},... ]
},...
]
</code></pre>
<h4>字段说明</h4>
<table>
<thead>
<tr>
<th>字段</th>
<th>是否必需</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>XTLSH</td>
<td>是</td>
<td>单据号，由调用方自行生成，唯一。返回时会同样返回，便于匹配结果</td>
</tr>
<tr>
<td>KHMC</td>
<td>是</td>
<td>客户名称</td>
</tr>
<tr>
<td>KHSH</td>
<td>否</td>
<td>客户税号</td>
</tr>
<tr>
<td>KHDZ</td>
<td>否</td>
<td>客户地址</td>
</tr>
<tr>
<td>KHKHYHZH</td>
<td>否</td>
<td>开户银行账号</td>
</tr>
<tr>
<td>FPZL</td>
<td>是</td>
<td>发票种类 <br/>- 020 全电专票 <br>- 021 全电普票</td>
</tr>
<tr>
<td>BZ</td>
<td>否</td>
<td>备注</td>
</tr>
<tr>
<td>KPR</td>
<td>否</td>
<td>开票人</td>
</tr>
<tr>
<td>SKR</td>
<td>否</td>
<td>收款人</td>
</tr>
<tr>
<td>FHR</td>
<td>否</td>
<td>复核人</td>
</tr>
<tr>
<td>QYKHYHZH</td>
<td>否</td>
<td>销方银行账号</td>
</tr>
<tr>
<td>QYDZDH</td>
<td>否</td>
<td>销方地址电话</td>
</tr>
<tr>
<td>YFPHM</td>
<td>条件是</td>
<td>原发票号(原发票代码+原发票号码) <br>红字发票必传，普票和电票必有<br>注：含（代码）总共18位或20位。</td>
</tr>
<tr>
<td>XXBBH</td>
<td>条件是</td>
<td>信息表编号 红字专票必传，普票电票不需要传</td>
</tr>
<tr>
<td>QDBZ</td>
<td>否</td>
<td>清单标志 默认为0</td>
</tr>
<tr>
<td>KHYJ</td>
<td>否</td>
<td>客户邮件 自动发邮件</td>
</tr>
<tr>
<td>KHSJ</td>
<td>否</td>
<td>客户手机</td>
</tr>
<tr>
<td>JDC</td>
<td>否</td>
<td>机动车标识 1为开具机动车专票</td>
</tr>
<tr>
<td>DBTS</td>
<td>否</td>
<td>代办退税标识 1为开具代办退税发票</td>
</tr>
<tr>
<td>ITEM</td>
<td>是</td>
<td>详见ITEM字段说明</td>
</tr>
</tbody>
</table>
<p>> 注：非必须节点，可以不带此节点</p>
<h4>ITEM字段说明</h4>
<table>
<thead>
<tr>
<th>字段</th>
<th>是否必需</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>CPMC</td>
<td>是</td>
<td>产品名称 如果是折扣行，必需与正数行一致的名称</td>
</tr>
<tr>
<td>CPXH</td>
<td>否</td>
<td>产品型号 如果是折扣行，此值为空</td>
</tr>
<tr>
<td>CPDW</td>
<td>否</td>
<td>产品单位 如果是折扣行，此值为空</td>
</tr>
<tr>
<td>SL</td>
<td>是</td>
<td>税率</td>
</tr>
<tr>
<td>CPSL</td>
<td>否</td>
<td>产品数量 红冲时为负，红冲时，不能有正数金额。</td>
</tr>
<tr>
<td>BHSJE</td>
<td>是</td>
<td>不含税金额 红冲时为负</td>
</tr>
<tr>
<td>SE</td>
<td>是</td>
<td>税额 红冲时为负</td>
</tr>
<tr>
<td>FLBM</td>
<td>是</td>
<td>分类编码 必需到未级编码</td>
</tr>
<tr>
<td>XSYH</td>
<td>否</td>
<td>税收优惠 有优惠1, 无优惠0 默认 0</td>
</tr>
<tr>
<td>KCJE</td>
<td>否</td>
<td>扣除金额 差额开票时有用</td>
</tr>
</tbody>
</table>
<p>> 注：非必须节点，可以不带此节点</p>
<h3>返回说明</h3>
<pre><code class="language-json">{
&quot;code&quot;: 200, // 200指接口调用成功，不表示发票开具成功，详见code返回码说明
&quot;msg&quot;: &quot;成功&quot;, // code对应的描述
&quot;taskNo&quot;: &quot;69564903663951243279&quot;, // 本次唯一请求号
&quot;data&quot;: {
&quot;successList&quot;: [{ // 成功列表
&quot;XTLSH&quot;: &quot;001&quot;, // 单据号
&quot;JQBH&quot;: &quot;&quot;, // 机器编号
&quot;FPDM&quot;: &quot;1233456789012&quot;, // 发票代码
&quot;FPHM&quot;: &quot;12345678&quot;, // 发票号码
&quot;KPRQ&quot;: &quot;2019-01-12t11:20:33&quot;, // 开票日期
&quot;SKM&quot;: &quot;密文&quot;, // 密文
&quot;JYM&quot;: &quot;校验码&quot;, // 校验码
&quot;EWM&quot;: &quot;二维码&quot;, // 二维码
&quot;URL&quot;: &quot;&quot;,// 电子发票下载网址【永久有效】
&quot;KPJG&quot;: &quot;&quot;,// 开票结果 1开票成功 0开票失败
&quot;KPFK&quot;: &quot;&quot;// 开票反馈信息
},...
],
&quot;errorList&quot;: [ // 失败列表
{
&quot;XTLSH&quot;: &quot;&quot;, // 单据号
&quot;ERRMSG&quot;: &quot;&quot; // 错误信息
},...
]}
}</code></pre>
<ul>
<li>当离线开票或税盘不在线时可能只是接口调用成功，此时需要关注下errorList这个值，此时有可能是部份成功，部份不成功。</li>
<li>唯一能确定开票成功开票的情况：successList列表中的发票号码不是为空</li>
</ul>
<h4>开具成功示例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200, // 200指接口调用成功，不表示发票开具成功，详见code返回码说明
&quot;msg&quot;: &quot;成功&quot;, // code对应的描述
&quot;taskNo&quot;: &quot;69564903663951243279&quot;, // 本次唯一请求号
&quot;data&quot;: {
&quot;successList&quot;: [{ // 成功列表
&quot;XTLSH&quot;: &quot;001&quot;, // 单据号
&quot;FPZL&quot;: &quot;&quot;, // 发票种类
&quot;FPDM&quot;: &quot;1233456789012&quot;, // 发票代码
&quot;FPHM&quot;: &quot;12345678&quot;, // 发票号码
&quot;KPRQ&quot;: &quot;2019-01-12t11:20:33&quot;, // 开票日期
&quot;JQBH&quot;: &quot;&quot;, // 机器编号
&quot;SKM&quot;: &quot;密文&quot;, // 密文
&quot;JYM&quot;: &quot;校验码&quot;, // 校验码
&quot;EWM&quot;: &quot;二维码&quot;, // 二维码
&quot;URL&quot;: &quot;&quot;,// 电子发票下载网址
&quot;KPJG&quot;: &quot;&quot;,// 开票结果 1开票成功 0开票失败
&quot;KPFK&quot;: &quot;&quot;// 开票反馈信息
},...
]
}</code></pre>
<h4>开具失败示例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 999, //
&quot;msg&quot;: &quot;&quot;, // code对应的描述
&quot;taskNo&quot;: &quot;69564903663951243279&quot;, // 本次唯一请求号
&quot;data&quot;: {
&quot;errorList&quot;: [{
&quot;XTLSH&quot;: &quot;001&quot;, // 单据号
&quot;ERRMSG&quot;: &quot;&quot; // 错误信息
},...
]
}</code></pre>
<h4>接口调用失败示例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 400,
&quot;msg&quot;: &quot;税盘id不能为空&quot;
}</code></pre>
<hr />
<p><a name="发票开具结果查询"></a></p>
<h2>发票开具结果查询</h2>
<h3>接口描述</h3>
<ul>
<li>查询发票开具结果</li>
</ul>
<h3>请求地址</h3>
<p><code>https://api.jumdata.com/invoice/makeout-result</code></p>
<h3>业务参数</h3>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>spid</td>
<td>String</td>
<td>是</td>
<td>税票id，联系服务商获取</td>
</tr>
<tr>
<td>fpzl</td>
<td>String</td>
<td>是</td>
<td>发票种类 <br>- 020 全电专票 <br>- 021 全电普票</td>
</tr>
<tr>
<td>xtlsh</td>
<td>String</td>
<td>是</td>
<td>单据号，即开具发票的传入的单据号</td>
</tr>
</tbody>
</table>
<h3>返回说明</h3>
<pre><code class="language-json">{
&quot;code&quot;: 200, // 详见code返回码说明
&quot;msg&quot;: &quot;成功&quot;, // code对应的描述
&quot;taskNo&quot;: &quot;69564903663951243279&quot;, // 本次唯一请求号
&quot;data&quot;: {
&quot;XTLSH&quot;: &quot;001&quot;, // 单据号
&quot;FPHM&quot;: &quot;12345678&quot;, // 发票号码（18位或20位）包含发票代码 。18位：发票代码前10位，发票号码后8位；20位：发票代码前12，发票号码后8位
&quot;KPRQ&quot;: &quot;2021-11-12 00:00:00.000&quot;, // 开票日期
&quot;MW&quot;: &quot;[ODA0NDw2KjYwMD]&quot;, // 发票密文, 前后都有中括号
&quot;XYM&quot;: &quot;57408721592&quot;,//校验码
&quot;JQBH&quot;: &quot;66180&quot;, //机器编号
&quot;URL&quot;: &quot;574087215921.PDF&quot;//发票下载地址
}
}
</code></pre>
<hr />
<p><a name="发票重新下载"></a></p>
<h2>发票重新下载</h2>
<h3>接口描述</h3>
<ul>
<li>因网络抖动原因，个别发票PDF无法下载，该接口可重新下载</li>
</ul>
<h3>请求地址</h3>
<p><code>https://api.jumdata.com/invoice/makeout/pdf/reload</code></p>
<h3>业务参数</h3>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>taskNo</td>
<td>String</td>
<td>是</td>
<td>发票开具接口返回的请求号</td>
</tr>
</tbody>
</table>
<h3>返回说明</h3>
<pre><code class="language-json">{
&quot;charge&quot;: false,//该接口不收费
&quot;code&quot;: 200,//详见code返回码说明
&quot;msg&quot;: &quot;成功&quot;,//code对应的描述
&quot;taskNo&quot;: &quot;332844491207624722580105&quot;,//本次唯一请求号
&quot;data&quot;: {
&quot;result&quot;: true,//是否成功，true：成功，false：失败
&quot;message&quot;: &quot;成功&quot;,
&quot;url&quot;: &quot;https://xxxxxx.pdf&quot; //发票开具接口返回的链接
}
}
</code></pre>
<h3>失败示例</h3>
<pre><code class="language-json">{
&quot;code&quot;: 400,
&quot;msg&quot;: &quot;taskNo不能为空！&quot;
}</code></pre>
<h2>获取刷脸认证二维码</h2>
<h3>接口描述</h3>
<ul>
<li>用于电子税务局刷脸认证时使用，延长税局在线时间和身份验证</li>
</ul>
<h3>请求地址</h3>
<p><code>https://api.jumdata.com/tax-plate/face-qrcode</code></p>
<h3>业务参数</h3>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>spid</td>
<td>String</td>
<td>是</td>
<td>税票id，联系服务商获取</td>
</tr>
</tbody>
</table>
<h3>返回说明</h3>
<pre><code class="language-json">{
&quot;code&quot;: 200, // 详见code返回码说明
&quot;msg&quot;: &quot;成功&quot;, // code对应的描述
&quot;taskNo&quot;: &quot;69564903663951243279&quot;, // 本次唯一请求号
&quot;data&quot;: {
&quot;Qrcode&quot;:&quot;&quot;
}
}
</code></pre>