# 个人票夹后台对接

TIP

此文档适用于第3方系统自己开发票选择页面,对接税务云,获取税务云个人账号中的发票数据。

# 流程设计

# 对接主体流程

1547533853574

如上图所示,第3方系统从税务云票夹获取发票,必须个人进行授权。

目前采用第3方系统与税务云账号绑定的方案实现该需求。

对于未进行绑定的第3方系统账号,登陆验证身份是会进行绑定操作,如果绑定成功,后续可以不再需要用户输入用户名及密码。

另外,同时提供解绑接口,满足解除绑定的需求。

第3方系统中,用户存在2中状态,未绑定和以绑定,处理流程

# 未绑定账号

1547616112764

# 已绑定账号

1547535039681

# 接口列表

# 账号绑定验证

# 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 手机号
email String 邮箱
partnerUser String 绑定系统的用户编码 对接系统的登录用户标识,此标识与打开票夹页的用户标识(usercode字段对应值)必须一致

# 返回值

{
    "code": "0000",
    "msg": "操作成功",
}

# 返回值说明

参数 类型 描述 说明
code String 状态码 0000-操作成功详见状态码说明
msg String 信息说明
Last Updated: 11/6/2021, 1:30:08 PM