发票通开放注册平台

一、概述

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 版式文件转图片，返回base64图片数据和清单。

调用方式:HTTPS请求方式 POST请求

测试环境 URL: https://IP:PORT/Entoauth/thirdApi?sign=ZTP&client_id=应用ID&access_token=访问Token&openID=openID的值&sqm=授权码&busiType=SQM_ZTP&data=报文数据(Base64过后的数据)&dataType=data报文数据类型(0:json/1:xml)

正式环境 URL: https://IP:PORT/Entoauth/thirdApi?sign=ZTP&client_id=应用ID&access_token=访问Token&openID=openID的值&sqm=授权码&busiType=SQM_ZTP&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_ZTP
参数 6	data	报文数据(Base64 过，然后再 URLEncoder 的数据)
参数 7	dataType	data 报文数据类型(0:json/1:xml)

data 不同格式报文数据样例:

XML 格式数据:

<REQUEST>
<REQUEST_PARAM>
<OFD_BYTES> base64加密的OFD byte数组</OFD_BYTES>
<IMG_TYPE> 图片类型（0：svg/1:png）</IMG_TYPE>
<HEIGHT> 图片高度（默认4960）</HEIGHT>
<WIDTH> 图片宽度（默认 6968）</WIDTH>
<MERGE> 是否合并图片和清单（0：不合并/1：合并,默认不合并）</MERGE>
</REQUEST_PARAM>
</REQUEST>

JSON 格式数据:

{
  "REQUEST": {
    "REQUEST_PARAM": {
"OFD_BYTES": " base64加密的OFD byte数组",
"IMG_TYPE": "图片类型（0：svg/1:png）",
"HEIGHT": "图片高度（默认6968）",
"WIDTH": "图片宽度（默认4960 ）",
"MERGE": "是否合并图片和清单（0：不合并/1：合并,默认不合并）"
  }
}

请求参数:

序号	字段	名称	必须	说明
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_YQYZ： OFD验签验章
7	data	Json/xml 业务报文	是	需要进行Base64 编码
8	IMG_TYPE	图片类型	是	0:svg,1:png
9	HEIGHT	图片高度	否	默认6968(如果转图片时间过慢，此值需调小一些。)
10	WIDTH	图片宽度	否	默认4960(如果转图片时间过慢，此值需调小一些。)
11	MERGE	是否合并	是	0：不合并/1：合并,默认不合并

1.2、返回报文

XML 格式返回报文

<RESPONSE>
<CODE>返回代码</CODE>
<MESSAGE>返回消息</MESSAGE>
<DATA>
<IMAGELIST>
<IMAGE>base64加密的OFD 数据（OFD xml 图片数据）</IMAGE>
<IMAGE>base64加密的OFD 数据（OFD xml 清单图片数据）</IMAGE>
</IMAGELIST>
</DATA>
</RESPONSE>

JSON 格式返回报文

{
  "RESPONSE": {
    "CODE": "返回代码",
    "MESSAGE": "返回消息",
    "DATA":{
"IMAGELIST":[
{"IMAGE":"base64加密的OFD 数据（OFD xml 图片数据）"},
    	 {"IMAGE":"base64加密的OFD 数据（OFD xml 清单图片数据）"}
]
}
}

返回参数说明

序号	字段	名称	必须	说明
1	CODE	返回代码	是	0000 为成功,其它为失败
2	MESSAGE	返回信息	否	详细信息描述
3	DATA	返回数据	是	返回数据