修订历史记录

日期	版本	说明	作者
2019-12-20	V1.0	初稿	王志成
2020-6-16	V1.1	增加安全校验机制	王俊东
2020-9-01	V1.2	调整链接路径与参数	王俊东
2022-03-11	V1.3	增加白名单描述	王俊东

1 前言

背景

文档是描述财云通平台数据对接的方案。旨在让财云通平台与各公司业务系统开发商明确财云通平台数据对接方案和具体技术细节，用于指导各业务系统开发商相关人员在设计、开发和测试联调的工作中，高效协同、高质量完成财云通平台与各公司业务系统的对接和数据交换。

适用范围

标准规范适用对象

财云通平台的系统集成单位。

标准规范适用范围

与财云通对接的各公司报税业务系统。

2 集成方案实现逻辑

集成流程

单点登录数据交互流程

集成流程

用户通过用户平台根据用户账号与密码生成签名，然后请求财云通平台授权服务。

财云通平台授权服务进行安全性校验，校验成功返回授权码，校验失败返回失败信息。

用户通过第二步获取到的授权码(security_token)、username、时间戳、redirect_uri，(https://uat-sso-fp.bigfintax.com/cas/v2/proxy?username=test123&visit_type=0&timestamp=1575972664334&redirect_uri=https://uat-gateway.bigfintax.com&security_token=400dd8737eb04ab69326227a618aaac9)请求财云通代理认证服务进行认证；认证成功后，重定向到财云通平台(redirect_url)系统首页，用户通过财云通平台首页进入申报服务。

[!NOTE]
用户信息同步有两种方式
第一种对接用户公司同步的接口
接口文档 https://www.yuque.com/shenzhouyunhe/mmvi8r/rdb9hsakto4vf1l2?singleDoc# 《平台管理系统接口》密码：hr7d
第二种两边维护用户信息需要客户系统记录用于用户登录的财云通的用户登录名

参数说明

功能及描述

功能	描述
服务标识	token
服务提供者	财云通平台
服务使用者	客户
服务管理者	财云通平台接口中心
服务实现方式	https
服务描述	客户需要集成财云通平台的时候调用
服务认证	测试暂无
测试服务URL	https://uat-sso-fp.bigfintax.com/cas/v2/proxy 生产：https://gateway.bigfintax.com/cas/v2/proxy
方法名称	-
功能描述 (适用场景)	集成财云通平台，需要提供IP,由云平台配置白名单放行
方法类型	GET
是否需要验签	是
格式	UTF-8

参数信息

参数名称	必选	参数类型	说明
security_token	是	String	通过平台服务获取的授权码
timeStamp	是	Long	访问时间戳,一定要时当前时间,不然会按超时处理
redirect_uri	是	String	测试环境为:https://uat-gateway.bigfintax.com/front/index 生产环境：https://gateway.bigfintax.com/front/index
username	是	String	用户code，用于区分登录平台的用户，code由财云通提供。
visit_type	是	String	平台集成取值：0

3 服务清单

序号	服务标识	服务名称	服务提供者	服务使用者	服务类型	服务实现方式
1	token	获取授权码接口	财云通平台	客户	授权类	https

4 验签

规则说明

授权码帐号密码说明：

每个接入用户提供一个用户名AccessKeyID、秘钥AccessKeySecret；使用秘钥基于HMC-SHA1算法进行请求内容的加密和解密；

检查AccessKeyID和公司编码orgCode对应关系。（账号这个AccessKeyID AccessKeySecret 要跟财云通的实施或者技术同学申请开通）

URL字符说明：

对于字符 A-Z、a-z、0-9 以及字符“-”、“_”、“.”、“~”不编码；

对于其他字符编码成“%XY”的格式

对于扩展的 UTF-8 字符，编码成“%XY%ZA…”的格式

需要说明的是英文空格（）要被编码是 %20，而不是加号（+）

时间类型"yyyy-MM-dd'T'HH:mm:ss'Z'"

SignatureNonce为32位随机数UUID

Signature 生成规则：

连接内容排序：将本URL中，除Signature外其他所有参数，按照参数名称的字典顺序

使用Password基于HMC-SHA1算法加密

对加密结果用MD5加密

举例参数：

AccessKeyID=userid

AccessKeySecret=password

Version=1.0

TimeStamp=2016-02-23 12:46:24

SignatureNonce=123456

根据参数名排序后：AccessKeyID=userid&SignatureNonce=123456&TimeStamp=2016-02-23T12:46:24Z&Version=1.0

使用Password基于HMAC-SHA1算法加密及MD5加密算法示范输出结果：B4B56FA44BCE1E353866F98EA9DDC665

签名生成流程

使用Password基于HMAC-SHA1算法加密及MD5加密算法示例

示例流程

示例代码：

初始化参数

生成签名方法

获取签名串方法

工具类（Md5生成器）

5 服务功能

服务目录

序号	服务标识	服务名称	服务提供者	服务使用者	服务类型	服务实现方式
1	token	获取授权码接口	财云通平台	客户	授权类	https

服务描述

功能及描述

功能	描述
服务标识	token
服务提供者	财云通平台
服务使用者	客户
服务管理者	财云通平台接口中心
服务实现方式	https
服务描述	客户需要集成财云通平台的时候调用
服务认证	测试暂无
测试服务URL	https://uat-ddapi.bigfintax.com/token/getToken 生产 https://gateway.bigfintax.com/declare-ports/token/getToken
方法名称	getToken
功能描述 (适用场景)	集成财云通平台，需要提供IP,由云平台配置白名单放行
方法类型	POST
是否需要验签	是
格式	UTF-8

输入参数

参数名称	必选	参数类型	说明
AccessKeyID	是	String	用户名称
TimeStamp	是	String	时间戳
SignatureNonce	是	String	随机数
Signature	是	String	签名串
Version	是	String	版本号

输出参数

参数名称	必选	参数类型	说明
Token	是	String	授权码
HostID	是	String	财云通平台服务标识
Code	是	String	返回码
Message	否	String	返回信息

请求示例：uat-ddapi.bigfintax.com
输出示例：

{
    "HostID": "https://ysb-p.bigfintax.com",
    "Code": "200",
    "Message": "调用成功",
    "Token": "b045eaba2ebd46b39919df1d8bfd7490"
}

6 码表

Code	Message
200	调用成功
400	签名结果错误
400	版本号不正确
400	时间差异超出范围
400	本次请求已完成，即SignatureNonce值已被使用，防重放
400	请求参数不正确（具体错误在括号内）
400	请求不合法
403	身份验证失败
403	未开通该接口
403	授权已过期
500	未知错误

单点登录

#

修订历史记录#

1 前言#

背景#

适用范围#

标准规范适用对象#

标准规范适用范围#

2 集成方案实现逻辑#

集成流程#

参数说明#

3 服务清单#

4 验签#

规则说明#

签名生成流程#

示例流程#

示例代码：#

5 服务功能#

服务目录#

服务描述#

6 码表#

修订历史记录

1 前言

背景

适用范围

标准规范适用对象

标准规范适用范围

2 集成方案实现逻辑

集成流程

参数说明

3 服务清单

4 验签

规则说明

签名生成流程

示例流程

示例代码：

5 服务功能

服务目录

服务描述

6 码表