OFD版式文件生成
一、概述
1.1 业务介绍
随着总局税控改革的推进，OFD格式将全面取PDF 格式，成为主流的电子发票版式文件。
OFD 版式文件作为一种全新的国标，尚处于普及推广的前奏阶段，客户对 OFD 版式文件服务的需求广泛而迫切。
现第三方服务商接入OFD，客户可以调用平台API接口实现文件生成、解析等功能。
1.2 目的
此文档为第三方服务商接入发票通OFD版式文件生成发票的接入技术规范(企业业务)，第三方按此文档就接口内容、接口格式、交互模式等技术达成一致，并以此进行对接程 序的开发。对第三方开发、实现技术和实现方式等均无要求，由第三方自行决定，但需要满 足此文档的技术接入规范。
应业务要求，业务过程中涉及到的两个系统之间的数据交互方式及交互内容进行规范， 制定统一的协议，形成技术文档。
1.3 接入方式
接入主要采取 Oauth2.0 接入技术规范，认证成功后发票通平台提供相关服务业务功能， 业务参数和报文基于 XML/JSON 报文格式，采用 http 或 https 方式。
1、XML 格式规范
请求规范(HEAD 节点中的子节点根据实际业务自定义):
<?xml version="1.0" encoding="utf-8"?> <REQUEST> <HEAD></HEAD> <BODY></BODY> </REQUEST>
响应规范:
<?xml version="1.0" encoding="utf-8"?>
<ROOT>
<HEAD>
<SERVICE>
<REPLYCODE>0</REPLYCODE>
<REPLYMSG>success</REPLYMSG>
</SERVICE>
</HEAD>
<BODY></BODY>
</ROOT>
2、JSON 格式规范
请求规范(HEAD 节点中的子节点根据实际业务自定义):
{
"REQUEST": {
"HEAD": {
},
"BODY": {
}
}
}
响应规范:
{
"ROOT": {
"HEAD": {
"SERVICE": {
"REPLYCODE": "0",
"REPLYMSG": "success"
}
},
"BODY": {
}
}
}
1.4 接入流程图
术语
注意:对 client_id 和 client_secret 信息进行保密，不要随意泄漏。
二、业务接口说明
1、OFD版式文件生成
1.1、请求报文
接口说明:用于OFD版式文件生成
调用方式:HTTPS请求方式 POST请求
测试环境 URL: https://IP:PORT/Entoauth/thirdApi?sign=DQWJSC&client_id=应用ID&access_token=访问Token&openID=openID的值&sqm=授权码&busiType=SQM_DQWJSC&data=报文数据(Base64过后的数据)&dataType=data报文数据类型(0:json/1:xml)
正式环境 URL: https://IP:PORT/Entoauth/thirdApi?sign=DQWJSC&client_id=应用ID&access_token=访问Token&openID=openID的值&sqm=授权码&busiType=SQM_DQWJSC&data=报文数据(Base64过后的数据)&dataType=data报文数据类型(0:json/1:xml)
参数说明:
| 序号 | 参数 | 含义 |
|---|---|---|
| 参数 1 | client_id | 应用 ID |
| 参数 2 | access_token | 二.1 接口获取到 |
| 参数 3 | openID | 二.2 接口获取到 |
| 参数 4 | sqm | OFD版式文件生成授权码 |
| 参数 5 | busiType | 固定值 SQM_DQWJSC |
| 参数 6 | data | 报文数据(Base64 过，然后再 URLEncoder 的数据) |
| 参数 7 | dataType | data 报文数据类型(0:json/1:xml) |
data 不同格式报文数据样例:
XML 格式数据:
<REQUEST> <REQUEST_PARAM> <REQUEST_COMMON_FPKJ> <XSF_MC>销方名称</XSF_MC> <XSF_NSRSBH>销方税号</XSF_NSRSBH> <XSF_DZDH>销方地址电话</XSF_DZDH> <XSF_YHZH>销方银行账号</XSF_YHZH> <GMF_MC>购买方名称</GMF_MC> <GMF_NSRSBH>购方税号</GMF_NSRSBH> <GMF_DZDH>购方地址电话</GMF_DZDH> <GMF_YHZH>购方银行账号</GMF_YHZH> <JYM>校验码</JYM> <QMZ>签名值</QMZ> <ZSFS>征税方式</ZSFS> <JSHJ>价税合计</JSHJ> <COMMON_FPKJ_XMXXS class="COMMON_FPKJ_XMXX" size=""> <COMMON_FPKJ_XMXX> <SE>税额</SE> <HSBZ>含税标志</HSBZ> <GGXH>规格型号</GGXH> <SL>税率</SL> <ZZSTSGL>增值税特殊管理</ZZSTSGL> <XMSL>项目数量</XMSL> <LSLBS>零税率标识</LSLBS> <DW>单位</DW> <SPSM>商品税目</SPSM> <FPHXZ>发票行性质</FPHXZ> <SPBM>商品编码</SPBM> <XMDJ>项目单价</XMDJ> <XMMC>项目名称</XMMC> <XMJE>项目金额</XMJE> <YHZCBS>优惠政策标识</YHZCBS> <ZXBM>纳税人自行编码</ZXBM> </COMMON_FPKJ_XMXX> </COMMON_FPKJ_XMXXS> <EWM>二维码</EWM> <BZ>备注</BZ> <JQBH>机器编号</JQBH> <KPRQ>开票日期</KPRQ> <FP_MW>发票密文</FP_MW> <BMB_BBH>编码表版本号</BMB_BBH> <KPLX>开票类型</KPLX> <KPR>开票人</KPR> <SKR>收款人</SKR> <FHR>复核人</FHR> <FP_HM>发票号码</FP_HM> <FP_DM>发票代码</FP_DM> <HJJE>合计金额</HJJE> <TSPZ>特殊票种</TSPZ> <YFP_DM>原发票代码</YFP_DM> <HJSE>合计税额</HJSE> <YFP_HM>原发票号码</YFP_HM> </REQUEST_COMMON_FPKJ> </REQUEST_PARAM> </REQUEST>
JSON 格式数据:
{
"REQUEST": {
"REQUEST_PARAM": {
"REQUEST_COMMON_FPKJ": {
"XSF_MC": "销方名称",
"XSF_NSRSBH": "销方税号",
"XSF_DZDH": "销方地址电话",
"XSF_YHZH": "销方银行账号",
"GMF_MC": "购买方名称",
"GMF_NSRSBH": "购方税号",
"GMF_DZDH": "购方地址电话",
"GMF_YHZH": "购方银行账号",
"JYM": "校验码",
"QMZ": "签名值",
"ZSFS": "征税方式",
"JSHJ": "价税合计",
"COMMON_FPKJ_XMXXS": {
"COMMON_FPKJ_XMXX": {
"SE": "税额",
"HSBZ": "含税标志",
"GGXH": "规格型号",
"SL": "税率",
"ZZSTSGL": "增值税特殊管理",
"XMSL": "项目数量",
"LSLBS": "零税率标识",
"DW": "单位",
"SPSM": "商品税目",
"FPHXZ": "发票行性质",
"SPBM": "商品编码",
"XMDJ": "项目单价",
"XMMC": "项目名称",
"XMJE": "项目金额",
"YHZCBS": "优惠政策标识",
"ZXBM": "纳税人自行编码"
}
},
"EWM": "二维码",
"BZ": "备注",
"JQBH": "机器编号",
"KPRQ": "开票日期",
"FP_MW": "发票密文",
"BMB_BBH": "编码表版本号",
"KPLX": "开票类型",
"KPR": "开票人",
"SKR": "收款人",
"FHR": "复核人",
"FP_HM": "发票号码",
"FP_DM": "发票代码",
"HJJE": "合计金额",
"TSPZ": "特殊票种",
"YFP_DM": "原发票代码",
"HJSE": "合计税额",
"YFP_HM": "原发票号码"
}
}
}
}
请求参数:
| 序号 | 字段 | 名称 | 必须 | 说明 |
|---|---|---|---|---|
| 1 | client_id | 应用ID | 是 | 应用ID |
| 2 | access_token | 访问Token | 是 | 2.1接口获取 |
| 3 | openID | OpenID | 是 | 2.2接口获取到的 |
| 4 | sqm | 授权码 | 是 | 在开发者平台进行申请 |
| 5 | dataType | 报文数据类型 | 是 | 0:json,1:xml |
| 6 | busiType | 业务类型 | 是 | SQM_DQWJSC：OFD板式文件生成（未签章） |
| 7 | data | Json/xml 业务报文 | 是 | 需要进行Base64 编码 |
| 7.1 | XSF_MC | 销方名称 | 是 | 销方名称 |
| 7.2 | XSF_NSRSBH | 销方税号 | 是 | 销方税号 |
| 7.3 | XSF_DZDH | 销方地址电话 | 是 | 销方地址电话 |
| 7.4 | XSF_YHZH | 销方银行账号 | 是 | 销方银行账号 |
| 7.5 | GMF_MC | 购买方名称 | 是 | 如为非收购发票，为购买方名称；如为收购发票，此项必填，即开票纳税人名称，例如XX烟草公司 |
| 7.6 | GMF_NSRSBH | 购方税号 | 是 | 购方税号 |
| 7.7 | GMF_DZDH | 购方地址电话 | 是 | 购方地址电话 |
| 7.8 | GMF_YHZH | 购方银行账号 | 是 | 购方银行账号 |
| 7.9 | JYM | 校验码 | 否 | 成功必填 |
| 7.10 | QMZ | 签名值 | 是 | 签名值 |
| 7.11 | ZSFS | 征税方式 | 是 | 0：普通征税,1：减按计征,2：差额征税 |
| 7.12 | JSHJ | 价税合计 | 是 | 小数点后2位 校验:价税合计=合计金额+合计税额 正票：13位；负票：14位 |
| 7.13 | EWM | 二维码 | 是 | 二维码 |
| 7.14 | BZ | 备注 | 否 | 备注 |
| 7.15 | JQBH | 机器编号 | 是 | 机器编号 |
| 7.16 | KPRQ | 开票日期 | 否 | 格式： “YYYYMM” |
| 7.17 | FP_MW | 发票密文 | 是 | 发票密文 |
| 7.18 | BMB_BBH | 编码表版本号 | 是 | 编码表版本号 |
| 7.19 | KPLX | 开票类型 | 是 | 0：正数票开具 1：负数票开具 |
| 7.20 | KPR | 开票人 | 是 | 开票人 |
| 7.21 | SKR | 收款人 | 否 | 收款人 |
| 7.22 | FHR | 复核人 | 否 | 复核人 |
| 7.23 | FP_HM | 发票号码 | 是 | 发票号码 |
| 7.24 | FP_DM | 发票代码 | 是 | 发票代码 |
| 7.25 | HJJE | 合计金额 | 是 | 小数点后2位，不含税 正票：12位；负票：13位 |
| 7.26 | TSPZ | 特殊票种 | 是 | “00”不是、“01”农产品销售、“02”农产品收购、“06”抵扣通行费、“07”其它通行费、“08”成品油销售。 |
| 7.27 | YFP_DM | 原发票代码 | 否 | 原发票代码 |
| 7.28 | HJSE | 合计税额 | 是 | 小数点后2位 |
| 7.29 | YFP_HM | 原发票号码 | 否 | 原发票号码 |
| 7.30 | SE | 税额 | 是 | 精度两位小数 |
| 7.31 | HSBZ | 含税标志 | 是 | N不含税，Y含税，建议均传不含税明细 |
| 7.32 | GGXH | 规格型号 | 否 | 规格型号 |
| 7.33 | SL | 税率 | 是 | 税率 |
| 7.34 | ZZSTSGL | 增值税特殊管理 | 否 | 增值税特殊管理 |
| 7.35 | XMSL | 项目数量 | 否 | 总长度包含小数点不能超过20位。若TSPZ为08，此项必填，不能为0。 |
| 7.36 | LSLBS | 零税率标识 | 否 | 空代表正常税率。1 出口免税和其他免税优惠政策（免税）、2 不征增值税（不征税）、3 普通零税率（0%） |
| 7.37 | DW | 单位 | 否 | 单位 |
| 7.38 | SPSM | 商品税目 | 否 | 保留字段，目前为空 |
| 7.39 | FPHXZ | 发票行性质 | 是 | 0 正常行、1 折扣行、2 被折扣行 |
| 7.40 | SPBM | 商品编码 | 否 | 总局固定编码，不能修改 |
| 7.41 | XMDJ | 项目单价 | 否 | 不含税，总长度包含小数点不能超过20位(只有当ZSFS为1时，此处填含税单价)若TSPZ为08，此项必填，不能为0。 |
| 7.42 | XMMC | 项目名称 | 是 | 如果为折扣行，商品名称须与被折扣行的商品名称相同，不能多行折扣。 |
| 7.43 | XMJE | 项目金额 | 是 | 不含税，单位：元（最多保留2位小数）(只有当ZSFS为1时，此处填含税金额)(只有当ZSFS为1时，此处填含税金额) |
| 7.44 | YHZCBS | 优惠政策标识 | 否 | 0未使用，1使用 |
| 7.45 | ZXBM | 纳税人自行编码 | 否 | 自定义编码以2位为一级，共10级，每级可用编码值为00-99 或AA-ZZ |
1.2、返回报文
XML 格式返回报文
<RESPONSE> <CODE>返回代码</CODE> <MESSAGE>返回消息</MESSAGE> <DATA>返回数据 base64加密的OFD byte数组</DATA> </RESPONSE>
JSON 格式返回报文
{
"RESPONSE": {
"CODE": "返回代码",
"MESSAGE": "返回消息",
"DATA": "返回数据 base64加密的OFD byte数组"
}
返回参数说明
| 序号 | 字段 | 名称 | 长度 | 必须 | 说明 |
|---|---|---|---|---|---|
| 1 | CODE | 返回代码 | 是 | 0000 为成功,其它为失败 | |
| 2 | MESSAGE | 返回信息 | 否 | 详细信息描述 | |
| 3 | DATA | 返回数据 | 是 | 返回数据 |