发票云组件服务(收票)API说明文档

一、概述

文档概述

1.1目的

本文档旨在编写一个面向开发者的完整的API调用规范,供需要调用票无忧功能的开发者使用。本文档不包括API具体的实现细节。

1.2适用范围

本文档适用阅读人员包括:发票云的设计、开发人员,合作伙伴。
适用于航天信息金税盘、百望税控盘设备。

1.3调用方式

接口均为POST方式,只支持Content-Length报文编码,不支持Chunk编码
所有接口均使用UTF-8编码请求与返回

IP直连方式
适用于局域网内的HTTP调用方式,默认端口为61624

通过接口长连接方式调用
接口地址:
https://wss.piaozone.com/bill-websocket/invoicewebsocket/push
clientsecret(发票云授权信息)3de1f420ed08409bbc3d4b9a156b4945, 盘号为3312345667,则;链接地址为https://wss.piaozone.com/bill-websocket/invoicewebsocket/push?name=如clientsecret为3de1f420ed08409bbc3d4b9a156b49453312345667

请求参数:

字段 类型 是否必须 描述
messageId string 本次请求的编号,用于后端区分(可以使用时间戳作为编号)
request_path string 请求的组件接口资源路径 (默认为/
... ... ... 其他接口参数



二、组件税控进项收票接口

接入税盘后通过税盘下载进项票

当前可支持的发票类型:

发票类型 代码
增值税专用发票 01
货运专用发票 02
机动车发票 03
通行费发票 04
增值税电子专用发票 05


2.1勾选数据查询

说明:
查询勾选数据,主要用于查询当期可进行勾选的发票数据,对于已认证的数据只保证在当前月份内的数据准确性。在查询可勾选数据成功前提下将上传接收到的单头数据至票无忧后台进行发票查验。

接口路径
/recvinv

请求参数:

参数名称 类型 是否必填 描述
data object 请求数据对象
rq_q string 请求查询开票起始时间
rq_z string 请求查询开票截止时间
rzzt string 认证状态 -1:全部 0:未认证 1:已认证
gxzt string 勾选状态 -1:全部 0:未勾选 1:已勾选
fpdm string 发票代码
fphm string 发票号码
fplx string 发票类型 -1:全部   01:增值税专用发票   02:货运专用发票   03:机动车发票   04:通行费发票   05:增值税电子专用发票   31:全电发票-增值税专用发票   
fpzt string 发票状态 -1:全部   0:正常   1:失控   2:作废   3:红冲   4:异常
page int 页码编号
pagesize int 单页数据大小

请求格式urlencode

{
    "data": {
        "rq_q": "2018-08-01",
        "rzzt": "0",
        "fpdm": "",
        "fpzt": "-1",
        "fplx": "0",
        "rq_z": "2018-11-30",
        "xfsbh": "",
        "fphm": "",
        "gxzt":"0"
    }
}

数据返回:

参数名称 类型 描述
errcode string 返回码 0000:操作成功 其他参见description描述
description string 错误描述
invoice array 结果数组
fpdm string 发票代码
fphm string 发票号码
fpzt string 发票状态 -1:全部   0:正常   1:失控   2:作废   3:红冲   4:异常
gx_rzsj string 勾选认证日期
gx_sj string 勾选日期
jshj string 金额
kprq string 开票日期
se string 税额
sf_gx string 是否已勾选
sf_gxrz string 是否已勾选认证
sf_smrz string 是否已扫描认证
sm_rzsj string 扫描认证时间
xhf_mc string 销方名称
xhf_nsrsbh string 销方纳税人识别号
fplx string 发票类型 01:增值税专用发票   02:货运专用发票   03:机动车发票   04:通行费发票  05:增值税电子专用发票   31:全电发票-增值税专用发票   

返回示例

{
    "errcode": "",
    "description": "",
    "invoice": [
        {
            "fpdm": "",
            "fphm": "",
            "fpzt": "",
            "gx_rzsj": "",
            "jshj": "",
            "kprq": "",
            "se": "",
            "sf_gx": "",
            "sf_gxrz": "",
            "sf_smrz": "",
            "sm_rzsj": "",
            "xhf_mc": "",
            "xhf_nsrsbh": "",
            "fplx": ""
        }
    ]
}


2.2抵扣统计查询

说明:查询抵扣统计数据。详情可参考 抵扣统计帮助文档。在查询抵扣数据成功前提下将上传接收到的单头数据至票无忧后台进行发票查验。

接口路径
/easydkquery

请求参数:

字段 类型 是否必须 描述
checkdate_start string 认证日期 yyyy-MM-dd
checkdate_end string 认证截止日期 yyyy-MM-dd
sellertaxcode string 销方税号
checktype string 认证方式 0:全部 1:勾选认证 2:扫描认证

请求格式:json
<示例>:

{
"invcode":"",
"invnum":"",
"checkdate_start":"2018-10-16",
"checkdate_end":"2018-10-28",
"sellertaxcode":"",
"checktype":"0"
}

数据返回:

参数名称 类型 描述
errcode string 返回码 0000:操作成功 其他参见description描述
description string 错误描述
invoice array 结果数组
invoice_code string 发票代码
invoice_num string 发票号码
invoice_state string 发票状态 -1:全部   0:正常   1:失控   2:作废   3:红冲   4:异常
checkdate string 认证日期 (认证方式相关)
taxbelong string 所属税期 yyyyMM
moneyamount string 金额
billdate string 开票日期
select_flag string 是否勾选 0:未勾选 1:已勾选
select_date string 勾选日期
tax string 税额
authentype string 认证方式 :1:勾选认证 2:扫描认证
invoice_type string 发票类型 01:增值税专票, 02:货运专票, 03:机动车发票, 08:电子专票,14:通行费发票, 31:全电发票-增值税专用发票
sellername string 销方名称

返回示例

{
    "errcode": "",
    "description": "",
    "invoice": [
        {
            "invoice_code": "",
            "invoice_num": "",
            "invoice_state": "",
            "checkdate": "",
            "taxbelong": "",
            "moneyamount": "",
            "billdate": "",
            "tax": "",
            "authentype": "",
            "invoice_type": "",
            "sellername": ""
        }
    ]
}


2.3发票勾选

说明:发票勾选。发票勾选帮助文档

接口路径
/fpcheck

请求参数:

字段 类型 是否必须 描述
fpdm string 发票代码,多个代码时用‘=’连接
fphm string 发票号码,多个号码时用‘=’连接
kprq string 开票日期 yyyy-mm-DD,多个日期时用‘=’连接
zt string 0:取消勾选 1:勾选。勾选操作,多个操作时用‘=’连接
city string 税盘所属城市名称
access_token string 票无忧授权token
caPass string 税盘CA密码
ptPass string 平台密码,若用户设置了税局登录平台密码则需要填写该字段

请求示例:

{
"fpdm":"123456=2345678",
"fphm":"34567=45678",
"kprq":"2017-12-12=2017-12-17",
"zt":"1=1",
"city":"深圳",
"access_token":"xxxxx",
"caPass":"12345678"
}

返回:

字段 类型 描述
errcode string 返回码,0000:勾选成功; 5004:部分勾选失败 其他:异常 描述见description
description string 描述
failed_list array 部分勾选失败的代码号码
invoice_code string 勾选失败的发票代码
invoice_num string 勾选失败的发票号码


2.4发票勾选确认

说明:发票认证。勾选确认帮助文档

接口路径
/fpcheckconfirm

请求参数:

若data数组不为空,则认证后增加额外校验并返回认证状态。当期已认证过的发票将返回认证成功

字段 类型 是否必填 描述
city string 税盘所属城市名称
caPass string 税盘CA密码
ptPass string 平台密码,若用户设置了税局登录平台密码则需要填写该字段

请求示例:

{
"caPass":"12345678"
}

返回:

字段 类型 描述
errcode string 返回码,0000:勾选确认成功; 其他:异常 描述见description
description string 描述


2.5税款所属期查询

说明:获取税款所属期。

接口路径
/taxqrgycx

请求参数:

字段 类型 是否必填 描述
caPass string 税盘CA密码
ptPass string 平台密码,若用户设置了税局登录平台密码则需要填写该字段

请求示例:

{
"caPass":"12345678"
}

返回:

字段 类型 描述
errcode string 返回码,0000时为获取成功
description string 描述
checkablerange string 当期可勾选发票的开票日期范围 yyyyMMdd-yyyyMMdd
taxbelong string 当期税款所属期 yyyyMM
taxbelong_next string 下一税期,一般当月月初在该值与taxbelong不同时,可通过接口2.6切换到下一税期 yyyyMM
checkdeadline string 当期可进行勾选操作的截止日期为 yyyyMMdd


2.6征期内切换至下一税期

说明:征期内将当前税款所属期切换到下一税期。该操作成功后将把当前所有已勾选未确认的发票清零

接口路径
/rollback

请求参数:

字段 类型 是否必填 描述
caPass string 税盘CA密码
ptPass string 平台密码,若用户设置了税局登录平台密码则需要填写该字段

请求示例:

{
"caPass":"12345678"
}

返回:

字段 类型 描述
errcode string 返回码,0000时为获取成功
description string 描述
taxbelong string YYYYMM 回滚操作后的当前税期


2.7单张发票查询

说明:查询单张发票信息

接口路径
/invoicequery

请求参数:

字段 类型 是否必填 描述
caPass string 税盘CA密码
ptPass string 平台密码,若用户设置了税局登录平台密码则需要填写该字段
invoice_code string 发票代码
invoice_num string 发票号码

请求示例:

{
"caPass":"12345678",
"invoice_code":"1234567890",
"invoice_num":"12345678"
}

返回:

字段 类型 描述
errcode string 返回码,0000时为获取成功
description string 描述
invoice_code string 发票代码
invoice_num string 发票号码
invoice_type string 发票类型 01:增值税专票, 02:货运专票, 03:机动车发票, 08:电子专票,14通行费发票
billdate string 开票日期 YYYY-MM-DD
sellername string 销方名称
sellertaxcode string 销方税号
amount string 金额
tax string 税额
status string 发票状态 0:正常   1:失控   2:作废   3:红冲   4:异常
auth_status int 是否认证 0:未认证 1:已认证
taxbelong string 税款所属期 YYYYMM
auth_type string 认证方式 1:勾选认证 2:扫描认证 -1:已勾选未认证
auth_date string 认证时间 YYYY-MM-DD HH: MM:SS


2.8未认证发票数据查询

说明:查询发票数据,用于收票后的发票详情查询。

接口路径
/invdatanoauth

请求参数:

字段 类型 是否必填 描述
access_token string 票无忧认证token
fphm string 发票号码
fpdm string 发票代码
fplx string 发票类型 -1:全部   01:增值税专用发票   02:货运专用发票   03:机动车发票  31:全电发票-增值税专用发票   
startdate string 查询开票起始时间 格式:yyyy-MM-dd
enddate string 查询开票截止时间 格式:yyyy-MM-dd
fpzt string 发票状态 -1:全部    0:正常    1:失控    2:作废    3:红冲    4:异常
nsrsbh string 查询发票数据的购方税号

请求示例:

{
"access_token":"7ffe2cced2a0e3615a24705ee39f53d09a243911c0e932991570ffa1d86abbf4",
"fphm":"",
"fplx":"-1",
"startdate":"2017-11-01",
"nsrsbh":"91440300358768292H",
"fpdm":"",
"fpzt":"-1",
"enddate":"2017-11-30"}
}

返回:

字段 类型 描述
errcode string 返回码,0000时为获取成功
description string 返回描述
invoice array 发票票面数据
fpqqlsh string 发票流水号
ddh string 发票订单号
kplx string 类型 0:蓝票 1:红票
fpdm string 发票代码
fphm string 发票号码
kprq string 开票日期 yyyy-MM-dd HH:mm:ss
hjbhsje string 不含税金额
kphjse string 税额
jshjje string 价税合计
kpy string 开票员
sky string 收款人
fhr string 复核人
yfpdm string 原发票代码
yfphm string 原发票号码
bz string 备注
rzzt string 认证状态 0:未认证 1:已认证
xhf_nsrsbh string 销货方识别号
xhf_mc string 销货方名称
xhf_dzdh string 销货方地址、固定电话
xhf_yhzh string 销货方银行账号
ghf_nsrsbh string 购货方方识别号
ghf_mc string 购货方名称
ghf_dzdh string 购货方地址、固定电话
ghf_yhzh string 购货方银行账号
ghf_sj string 购货方手机
checkcode string 检验码
zfbz string 作废标志
fwm string 防伪码
kabao_url string 微信卡包链接
dkbz string 待开标志 1:待开
pdf_url string 发票pdf下载地址
items null 发票明细数据
xmdw string 项目单位
ggxh string 规格型号
se string 税额
xmmc string 项目名称
xmdj string 项目单价
xmsl string 项目数量
xmje string 项目金额
sl string 税率
hsbz string 含税标志,0:不含税 1:含税

返回示例

{
    "errcode": "",
    "description": "",
    "invoice": [
        {
            "fpqqlsh": "",
            "ddh": "",
            "kplx": "",
            "fpdm": "",
            "fphm": "",
            "kprq": "",
            "hjbhsje": "",
            "kphjse": "",
            "jshjje": "",
            "kpy": "",
            "sky": "",
            "fhr": "",
            "yfpdm": "",
            "yfphm": "",
            "bz": "",
            "rzzt": "",
            "xhf_nsrsbh": "",
            "xhf_mc": "",
            "xhf_dzdh": "",
            "xhf_yhzh": "",
            "ghf_nsrsbh": "",
            "ghf_mc": "",
            "ghf_dzdh": "",
            "ghf_yhzh": "",
            "ghf_sj": "",
            "checkcode": "",
            "zfbz": "",
            "fwm": "",
            "kabao_url": "",
            "dkbz": "",
            "pdf_url": "",
            "items": [
                {
                    "xmdw": "",
                    "ggxh": "",
                    "se": "",
                    "xmmc": "",
                    "xmdj": "",
                    "xmsl": "",
                    "xmje": "",
                    "sl": "",
                    "hsbz": ""
                }
            ]
        }
    ]
}


2.9已认证发票数据查询

说明:查询发票数据,用于收票后的发票详情查询。

接口路径
/invdataauth

请求参数:

字段 类型 是否必填 描述
access_token string 票无忧认证token
fphm string 发票号码
fpdm string 发票代码
fplx string 发票类型 -1:全部   01:增值税专用发票   02:货运专用发票   03:机动车发票  31:全电发票-增值税专用发票   
startdate string 查询认证起始时间 格式:yyyy-MM-dd
enddate string 查询认证截止时间 格式:yyyy-MM-dd
fpzt string 发票状态 -1:全部    0:正常    1:失控    2:作废    3:红冲    4:异常
nsrsbh string 查询发票数据的购方税号

返回:
通接口2.8返回格式

2.10发票认证

说明:执行发票勾选以及勾选确认,已认证的数据作认证成功处理

接口路径
/easyconfirm

请求参数:

字段 类型 是否必须 描述
fpdm string 发票代码,多个代码时用‘=’连接
fphm string 发票号码,多个号码时用‘=’连接
kprq string 开票日期 yyyy-mm-DD,多个日期时用‘=’连接
city string 税盘所属城市名称
access_token string 票无忧授权token
caPass string 税盘CA密码
ptPass string 平台密码,若用户设置了税局登录平台密码则需要填写该字段

请求示例:

{
"fpdm":"123456=2345678",
"fphm":"34567=45678",
"kprq":"2017-12-12=2017-12-17",
"city":"深圳",
"access_token":"xxxxx",
"caPass":"12345678"
}

返回:

字段 类型 描述
errcode string 返回码,0000:认证成功; 5004:认证勾选失败, 其他异常 描述见description
description string 描述
failed_list array 部分认证失败的代码号码
invoice_code string 认证失败的发票代码
invoice_num string 认证失败的发票号码



二、组件税控销项收票接口

接入税盘后通过税盘下载进项票
当前可支持 增值税专用发票货运专用发票机动车发票通行费发票增值税电子专用发票

当前可支持的发票类型:

发票类型 代码
增值税专用发票 01
货运专用发票 02
机动车发票 03
通行费发票 04
增值税电子专用发票 05