# 个人票夹后台对接
TIP
此文档适用于第3方系统自己开发票选择页面,对接税务云,获取税务云个人账号中的发票数据。
# 流程设计
# 对接主体流程
如上图所示,第3方系统从税务云票夹获取发票,必须个人进行授权。
目前采用第3方系统与税务云账号绑定的方案实现该需求。
对于未进行绑定的第3方系统账号,登陆验证身份是会进行绑定操作,如果绑定成功,后续可以不再需要用户输入用户名及密码。
另外,同时提供解绑接口,满足解除绑定的需求。
第3方系统中,用户存在2中状态,未绑定和以绑定,处理流程
# 未绑定账号
# 已绑定账号
# 接口列表
# 账号绑定验证
# URL
GET http://{HOST}:{PORT}/piaoeda-web/api/partner/v1/auth-check?appid=xxxxx&usercode=001
# URL参数
参数 | 类型 | 长度 | 是否必填 | 默认值 | 描述 | 说明 |
---|---|---|---|---|---|---|
appid | String | 是 | ||||
usercode | String | 是 | 用户编码 |
# 返回值
{
"code": "0000",
"msg":"操作成功",
"datas":"YWZjYzMzMzgtYjM4Mi00OGJmLWJhZjMtOGYzYzhiNTQ2NDI5"
}
# 返回值说明
参数 | 类型 | 描述 | 说明 |
---|---|---|---|
code | String | 状态码 | 0000-操作成功;详见状态码说明 |
msg | String | 信息说明 | |
datas | String | token值,如果未绑定,token为空 |
# 获取加密公钥
个人票夹请求公钥
# URL
GET
http://{HOST}:{PORT}/cas/v1/pubkey
# 返回值
{
"code" : "0000",
"msg" : "获取成功",
"datas" : {
"modules" : "d617169a9571a97fbf86120c2ccee7ef0c96118154f9e5eb1bf21778b5644f3713546fc4110fdceb9f461cd20cf858cb8525c154367059789bfd0a78dd7780bedebacfcc4438f64bc394d3fb09c6567b4a665919af50faa8c1e9aa864e8b294b2e8537320ac1879b4a945188ddf8312ec926be0d2db64ed70eca764adafb9187",
"exponent" : "10001"
}
}
# 返回值说明
参数 | 类型 | 描述 | 说明 |
---|---|---|---|
code | code | 状态码 | 0000-操作成功;详见状态码说明 |
msg | String | 信息说明 | |
modules | String | 模 | |
exponent | String | 公钥指数 |
# 账号登录并绑定
个人票夹登录
# URL
POST
http://{HOST}:{PORT}/cas/v1/mobile/user/mobileloginV2
# 请求体
{
"account": "XXXX",
"password": "c8ea0dacfb7e0ae4f06fcb188cde397b8f09107bb9d59e17c0c56dd340d806245da37ed3bb2f191b26eec4f317cf6d1fd0d09ba68ce28d4451ce9412c12fa3f6ba7db0fc6e33ee505ead7f83d85bff352da7d6d4a5e47ba15346f6f6330208d0e96cc9bce38b3e608b0a4357f88b752cc7a820840ce732b4be457a80160c0966_encrypted",
"srcapp": "mobile",
"isbind":"Y",
"usercode":"xxx",
"appid":"xxx"
}
# 请求体说明
参数 | 类型 | 长度 | 是否必填 | 描述 | 说明 |
---|---|---|---|---|---|
account | String | 是 | 用户名 | ||
password | String | 是 | 加密后密码 | ||
isbind | String | 否 | 是否绑定第三方系统用户 | 默认为N | |
usercode | String | 否 | 第三方系统绑定的账号 | 如果isbind为Y,此参数不能为空 | |
appid | String | 否 | appid | 如果isbind为Y,此参数不能为空 | |
srcapp | String | 否 | 来源app | ("mobile", "移动端登录"), ("bx", "报销登录 "), ("weixin_app","微信小程序"), ("weixin_gzh", "微信公众号"), ("client_app", "开票助手") |
# 返回值
{
"code" : "0000",
"msg" : "操作成功",
"datas" : {
"token" : "MGRjNmUxM2QtMzhmZC00MTEwLThjZTgtYzVmYTg5Nzg3M2Fm"
}
}
# 返回值说明
参数 | 类型 | 描述 | 说明 |
---|---|---|---|
code | code | 状态码 | 0000-操作成功;详见状态码说明 |
msg | String | 信息说明 | |
token | String |
# 票夹查询
# URL
POST
http://{HOST}:{PORT}/piaoeda-web/mobile/invoices/V2/advancequery?page=1&size=5&token=xxxxx
# url参数说明
参数 | 类型 | 必填 | 默认值 | 描述 | 说明 |
---|---|---|---|---|---|
page | String | 是 | 第几页 | page起始页为1 | |
size | String | 是 | 页数据量 | size必须小于等于100 | |
token | String | 是 | token | 接口1或者接口2返回的token值 |
# 请求体
{
"xsfMc":"",
"gmfMc":"",
"fpDm":"",
"fpHm":"",
"purchaserstatus":[-1,33]
}
# 请求体说明
参数 | 类型 | 必填 | 默认值 | 描述 | 说明 |
---|---|---|---|---|---|
xsfMc | String | 否 | 销售方名称 | ||
gmfMc | String | 否 | 邮箱 | ||
fpDm | String | 是 | 发票代码 | ||
fpHm | String | 是 | 发票号码 | ||
purchaserstatus | int[] | 否 | 发票账号 | -1:未设置;33:未报销;36:报销中;39:已报销;42:已记账 |
# 返回值
{
"code": "0000",
"msg": "操作成功",
"total":5,
"datas": [
{
"invoice": {
"fpDm": "0110xxxxxxx1",
"fpHm": "xxxxxxx1",
"purchaserstatus":33,
"classification":"通讯",
"kprq": "2016-07-01",
"fpMw":"15<*026+848686",
"jym":"57644233870940613901",
"xsfNsrsbh":"xxxxxx",
"xsfMc":"江苏圆周电子商务有限公司北京分公司",
"xsfDzdh":"北京市海淀区北清路68号用友软件园2号楼3层 62434888",
"xsfYhzh":"11001048600052502301",
"gmfNsrsbh":"xxxx",
"gmfMc":"北京某公司",
"gmfDzdh":"北京某公司地址电话",
"gmfYhzh":"北京某公司银行账号",
"kpr":"开票人",
"skr":"收款人",
"fhr":"复核人",
"yfpDm":"xxxxxxx",
"yfpHm":"xxxxxx",
"jshj": 5.0,
"hjje": 4.0,
"hjse": 1.0,
"kpr": "Z000DZQD",
"bz":"备注",
"items": [
{
"xmmc": "笔记本",
"ggxh": "14寸",
"dw": "台",
"xmsl": 1,
"xmdj": 4.8,
"xmje": 4.8,
"sl": 0.17,
"se": 0.82
}
]
}
},
{
"invoice": {
"fpDm": "0110xxxxxxx1",
"fpHm": "xxxxxxx1",
"purchaserstatus":36,
"classification":"餐饮",
"kprq": "2016-07-01",
"fpMw":"15<*026+848686",
"jym":"57644233870940613901",
"xsfNsrsbh":"xxxxxx",
"xsfMc":"江苏圆周电子商务有限公司北京分公司",
"xsfDzdh":"北京市海淀区北清路68号用友软件园2号楼3层 62434888",
"xsfYhzh":"11001048600052502301",
"gmfNsrsbh":"xxxx",
"gmfMc":"北京某公司",
"gmfDzdh":"北京某公司地址电话",
"gmfYhzh":"北京某公司银行账号",
"kpr":"开票人",
"skr":"收款人",
"fhr":"复核人",
"yfpDm":"xxxxxxx",
"yfpHm":"xxxxxx",
"jshj": 5.0,
"hjje": 4.0,
"hjse": 1.0,
"kpr": "Z000DZQD",
"bz":"备注",
"items": [
{
"xmmc": "笔记本",
"ggxh": "14寸",
"dw": "台",
"xmsl": 1,
"xmdj": 4.8,
"xmje": 4.8,
"sl": 0.17,
"se": 0.82
}
]
}
}
]
}
# 返回值说明
参数 | 类型 | 描述 | 说明 |
---|---|---|---|
code | String | 状态码 | 0000-操作成功详见状态码说明 |
msg | String | 信息说明 | |
total | int | 总条数 | |
fpDm | String | 发票代码 | |
fpHm | String | 发票号码 | |
fplx | String | 发票类型 | 1:增值税电子普通发票;3:增值税普通发票;4:增值税专用发票 |
purchaserstatus | int | 报销状态 | |
classification | String | 发票分类 | 目前支持:"交通","餐饮","通讯","其他" |
kprq | String | 开票日期 | |
fpMw | String | 发票密文 | |
jym | String | 校验码 | |
xsfNsrsbh | String | 销售方纳税人识别号 | |
xsfMc | String | 销售方名称 | |
xsfDzdh | String | 销售方地址电话 | |
xsfYhzh | String | 销售方银行账号 | |
gmfNsrsbh | String | 购买方纳税人识别号 | |
gmfMc | String | 购买方名称 | |
gmfDzdh | String | 购买方地址电话 | |
gmfYhzh | String | 购买方银行账号 | |
kpr | String | 开票人 | |
skr | String | 收款人 | |
fhr | String | 复核人 | |
yfpDm | String | 原发票代码 | |
yfpHm | String | 原发票号码 | |
jshj | Double | 价税合计 | |
hjje | Double | 合计金额 | |
hjse | Double | 合计税额 | |
bz | String | 备注 | |
xmmc | String | 项目名称 | 货物或应税劳务、服务名称 |
ggxh | String | 规格型号 | |
dw | String | 单位 | |
xmsl | double | 数量 | |
xmdj | double | 单价 | |
xmje | double | 金额 | |
sl | double | 税率 | |
se | double | 税额 |
# 账号取消绑定
用户取消绑定对接系统的个人账号与税务云账号,每批最多20个用户
# URL
POST
http://{HOST}:{PORT}/piaoeda-web/api/einvoice/v2/unbind-user?appid=XXXXXX
# 请求体
[
{
"mobile": "13888888888",
"email": "aaa@a.com",
"partnerUser":"XXXX"
},
{
"mobile": "131111111111",
"email": "bbb@a.com",
"partnerUser":"XXXX"
}
]
# 请求体说明
参数 | 类型 | 必填 | 默认值 | 描述 | 说明 |
---|---|---|---|---|---|
mobile | String | 是 | 手机号 | ||
String | 否 | 邮箱 | |||
partnerUser | String | 是 | 绑定系统的用户编码 | 对接系统的登录用户标识,此标识与打开票夹页的用户标识(usercode字段对应值)必须一致 |
# 返回值
{
"code": "0000",
"msg": "操作成功",
}
# 返回值说明
参数 | 类型 | 描述 | 说明 |
---|---|---|---|
code | String | 状态码 | 0000-操作成功详见状态码说明 |
msg | String | 信息说明 |