文档概述
本文档旨在编写一个面向开发者的完整的API调用规范,供需要调用票无忧功能的开发者使用。本文档不包括API具体的实现细节。
本文档适用阅读人员包括:发票云的设计、开发人员,合作伙伴。
适用于航天信息金税盘、百望税控盘设备。
接口均为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 |
说明:
查询勾选数据,主要用于查询当期可进行勾选的发票数据,对于已认证的数据只保证在当前月份内的数据准确性。在查询可勾选数据成功前提下将上传接收到的单头数据至票无忧后台进行发票查验。
接口路径
/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": ""
}
]
}
说明:查询抵扣统计数据。详情可参考 抵扣统计帮助文档。在查询抵扣数据成功前提下将上传接收到的单头数据至票无忧后台进行发票查验。
接口路径
/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": ""
}
]
}
说明:发票勾选。发票勾选帮助文档。
接口路径
/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 | 勾选失败的发票号码 |
说明:发票认证。勾选确认帮助文档。
接口路径
/fpcheckconfirm
请求参数:
若data数组不为空,则认证后增加额外校验并返回认证状态。当期已认证过的发票将返回认证成功
字段 | 类型 | 是否必填 | 描述 |
---|---|---|---|
city | string | 否 | 税盘所属城市名称 |
caPass | string | 是 | 税盘CA密码 |
ptPass | string | 否 | 平台密码,若用户设置了税局登录平台密码则需要填写该字段 |
请求示例:
{
"caPass":"12345678"
}
返回:
字段 | 类型 | 描述 |
---|---|---|
errcode | string | 返回码,0000:勾选确认成功; 其他:异常 描述见description |
description | string | 描述 |
说明:获取税款所属期。
接口路径
/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 |
说明:征期内将当前税款所属期切换到下一税期。该操作成功后将把当前所有已勾选未确认的发票清零
接口路径
/rollback
请求参数:
字段 | 类型 | 是否必填 | 描述 |
---|---|---|---|
caPass | string | 是 | 税盘CA密码 |
ptPass | string | 否 | 平台密码,若用户设置了税局登录平台密码则需要填写该字段 |
请求示例:
{
"caPass":"12345678"
}
返回:
字段 | 类型 | 描述 |
---|---|---|
errcode | string | 返回码,0000时为获取成功 |
description | string | 描述 |
taxbelong | string | YYYYMM 回滚操作后的当前税期 |
说明:查询单张发票信息
接口路径
/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 |
说明:查询发票数据,用于收票后的发票详情查询。
接口路径
/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 HHss |
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": ""
}
]
}
]
}
说明:查询发票数据,用于收票后的发票详情查询。
接口路径
/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返回格式
说明:执行发票勾选以及勾选确认,已认证的数据作认证成功处理
接口路径
/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 |