发票通开放注册平台

一、概述

1.1 业务介绍

商家使用税控盘开票软件给消费者开具发票时，存在手工录入抬头信息耗时长、易出错的问题，开票精灵是辅助税控盘开票软件快速填充抬头的软件，为商家提高了开具发票的效率。

开票精灵原本使用场景:用户使用微信扫一扫扫描商家在开票精灵软件内下载的二维码，在手机打开开票精灵的抬头填写页面。用户填写抬头信息后，点击“保存并发送”，将信息发送至开票精灵内。商户收到用户的抬头信息，将信息填充至开票软件内即可极速完成开票。

现第三方服务商接入开票精灵，使用第三方服务商提供的抬头填写页面发送抬头信息，具体流程如下。第三方服务商提供抬头填写页面 URL 地址给开票精灵，开票精灵生成二维码给商户，用户扫描商户的二维码，打开抬头填写页面填写并提交抬头，第三方服务商收到抬头信息后，将信息发送至开票精灵内。

1.2 目的

此文档为第三方服务商接入发票通开票精灵发票抬头的接入技术规范(企业业务)，第三方按此文档就接口内容、接口格式、交互模式等技术达成一致，并以此进行对接程序的开发。对第三方开发、实现技术和实现方式等均无要求，由第三方自行决定，但需要满足此文档的技术接入规范。

应业务要求，业务过程中涉及到的两个系统之间的数据交互方式及交互内容进行规范，制定统一的协议，形成技术文档。

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 信息进行保密，不要随意泄漏。

二、业务接口说明

2.1 请求报文

接口说明:用于企业端 APP html5 页面发送抬头到开票精灵服务器接口服务

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

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

正式环境 URL: https://IP:PORT/Entoauth/thirdApi?sign=FPTT1002&client_id=应用 ID&access_token =访问 Token&openID=&sqm=&busiType=SQM_KPJL&data=报文数据(Base64 过后的数据)&dataType=data 报文数据类型(0:json/1:xml)

参数说明:

序号	参数	含义
参数 1	client_id	应用 ID
参数 2	access_token	二.1 接口获取到
参数 3	openID	二.2 接口获取到
参数 4	sqm	开票精灵授权码
参数 5	busiType	固定值 SQM_KPJL
参数 6	data	报文数据(Base64 过，然后再 URLEncoder 的数据)
参数 7	dataType	data 报文数据类型(0:json/1:xml)

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

XML 格式数据:

<REQUEST>
  <HEAD></HEAD> 
  <BODY>
    <ORDER_NO>订单号</ORDER_NO>
    <TTQQLSH>抬头请求流水号</TTQQLSH>
    <ATTACH>附件字段用户提交发票时会发送给商户，一般用盘号作为attach</ATTACH>
  </BODY>
</REQUEST>

JSON 格式数据:

{
  "REQUEST": { 
    "HEAD": "", 
    "BODY": {
      "ORDER_NO":"订单号",
      "TTQQLSH": "抬头请求流水号",
      "ATTACH": "附件字段用户提交发票时会发送给商户，一般用盘号作为 attach"
    } 
  }
}

请求参数:

序号	字段	名称	长度	必须	说明
1	client_id	应用 ID		是	应用 ID
2	access_token	访问 Token		是	二.1 接口获取
3	openID			是	二.2 接口获取到的
4	sqm	开票精灵授权码		是	在开发者平台进行申请
5	dataType	报文数据类型		是	0:json, 1:xml
6	busiType	业务类型		是	SQM_KPJL: 表示开票精灵业务
7	data	Json/xml 格式业务报文		是	需要进行 Base64 编码然后进行 URLEncoder.encode("","UTF-8" )
8	ORDER_NO	订单号		是	订单号
9	TTQQLSH	抬头请求流水号	20	是	流水号，每个请求流水号只能开一次,流水号前面以公司名称前缀例如百望电子: BWDZ201604201454001
10	ATTACH	税控盘编号	20	是	附件字段用户提交发票时会发送给商户，一般用盘号作为 attach

2.2 返回报文

XML 格式返回报文

<ROOT>
  <HEAD> 
    <SERVICE>
      <REPLYCODE>0000</REPLYCODE>
      <REPLYMSG>success</REPLYMSG> 
    </SERVICE>
  </HEAD> 
  <BODY>
    <TTQQLSH>抬头请求流水号</TTQQLSH> 
  </BODY>
</ROOT>

JSON 格式返回报文

{
  "head": { 
    "service": {
      "replyCode": "0000",
      "replyMsg": "success" 
    }
  }, 
  "body": {
  }
}

返回参数说明

序号	字段	名称	必须	说明
1	REPLYCODE	返回代码	是	0000 为成功,其它为失败
2	REPLYMSG	返回信息	否	详细信息描述
3	TTQQLSH	抬头请求流水号

删除订单信息，开票精灵同步抬头信息删除