通达OA系统对接 单点登录 标准SaaS技术服务说明
1 标准技术服务项目
| 标准业务类型 |
服务说明 |
服务项目 |
预估工期 （人/天） |
| HR接口对接 （人员组织同步） |
支持HR接口信息对接（因钉钉服务限制，做钉钉接口需要单独购买服务器进行部署） • 支持平台：兼容市面上大部分oa系统，但必须以标准格式返回数据，具体以技术文档为准 • 支持同步的数据：同步人员、组织架构、岗位架构 • 对接方式：客户需要按照技术文档开发接口 |
钉钉、企业微信对接 （接口只能同步人员和组织信息） |
3 |
| 其他OA平台对接 |
5 |
||
| 消息对接 |
通过企业微信、钉钉信息对接后，支持消息对接（需要先做人员组织同步） • 支持平台：企业微信、钉钉 • 支持内容：提供文本消息通知 • 对接方式：需要企业微信或钉钉管理员配置相关信息 |
消息对接 |
1 |
| 第三方免登录 |
支持使用通达OA标准接口，实现PC端、手机端免登陆进入平台 1、PC端 • 支持平台：兼容市面上大部分oa系统，具体技术文档为准 • 对接方式：支持通达OA标准接口，需要客户开发接口；CAS单点登录，提供跳转链接和服务地址，无需开发 2、手机端 • 支持平台：客户APP、企业微信 • 对接方式：APP需要开发接口，企业微信需要提供信息配置，无需开发 |
PC端，标准接口开发 |
3 |
| PC端，CAS单点登录方式 |
1 |
||
| 手机端，客户APP |
3 |
||
| 手机端，企业微信 |
1 |
||
| 标准H5接入 |
支持内嵌通达OA标准H5页面，实现使用账号密码登陆之后30天内免登陆 · 支持平台：钉钉、微信公众号、APP（需要支持H5链接） · 对接方式：需要提供相关信息配置，无需开发 |
标准H5接入 |
1 |
2 具体服务项目说明
2.1 HR接口对接
支持服务：通过HR接口进行信息同步
预估工期：5个工作日
| 项目 |
服务说明 |
客户是否需求开发 |
| HR接口 信息对接 |
支持平台：兼容市面上大部分oa系统，但必须以标准格式返回数据，具体以技术文档为准。（因钉钉服务限制，做钉钉接口需要单独购买服务器进行部署）
支持同步的数据：同步人员、组织架构、岗位架构 (目前钉钉，企业微信目前只支持同步人员、组织架构，无岗位接口)
对接方式：客户需要按照技术文档开发接口 |
需要
|
2.1.1 标准接口技术说明
学习系统支持两种同步方式：http restful、webservice，学习系统每天会定时进行数据采集，支持全量、增量两种数据传输形式，必须按照返回标准提供数据。
2.1.2 返回值标准
数据唯一性：返回数据必须具有唯一性，不能存在一个用户多条数据的情况
返回格式：数据返回格式为xml、json，具体请参考下方示例
返回格式示例
xml两种格式 如下：
<?xml version="1.0" encoding="UTF-8"?>
<result>
<list>
<email>[email protected]</fullName>
<fullName>测试账号</fullName>
<name>00001</name>
<organizationId>9f68d-37b8-493b-a75e-dac2a112fe3</organizationId >
<status>2</status>
</list>
<list>
<email>[email protected]</fullName>
<fullName>测试账号2</fullName>
<name>00002</name>
<organizationId>1s233-7b8-493b-a75e-dac2a112fe3</organizationId >
<status>1</status>
</list>
</result>
或
<?xml version="1.0" encoding="UTF-8"?>
<result>
[{"fullName": "测试账号1",
"id": "0224c309-61a3ff-9034-b10224c3094d",
"name": "00001",
"organizationId": “001”,
"phoneNumber": “13323423456”
},{
"fullName": "测试账号2",
"id": "ff102b68-61a3ff-9034-b10224c3094d",
"name": "00002",
"organizationId": “002”,
"phoneNumber": “13223423456”
}]
</result>
json格式 如下：
[{"fullName": "测试账号1",
"id": "0224c309-61a3ff-9034-b10224c3094d",
"name": "00001",
"organizationId": “001”,
"phoneNumber": “13323423456”
},{
"fullName": "测试账号2",
"id": "ff102b68-61a3ff-9034-b10224c3094d",
"name": "00002",
"organizationId": “002”,
"phoneNumber": “13223423456”
}]
2.1.3 返回字段说明
组织信息所需同步字段说明：
| 信息名称 |
是否必传 |
备注 |
| 组织名称 |
是 |
|
| 组织简称 |
否 |
|
| 组织编码 |
是 |
组织唯一标识 |
| 上级组织 |
是 |
用来关联上级 |
| 公司分类 |
否 |
区分该组织是分公司还是部门 |
| 排序 |
否 |
|
| 组织状态 |
否 |
启用/禁用 |
人员信息所需同步字段说明：
| 信息名称 |
是否必传 |
备注 |
| 姓名 |
是 |
|
| 账号 |
是 |
|
| 手机号码 |
否 |
|
| 邮箱 |
否 |
|
| 性别 |
否 |
|
| 归属部门标识 |
是 |
|
| 岗位标识 |
否 |
|
| 在职状态 |
否 |
|
| 账号有效期 |
否 |
|
| 用户状态 |
否 |
|
职位体系信息：
| 信息名称 |
是否必传 |
备注 |
| 职务名称 |
否 |
|
| 职务编码 |
否 |
|
| 归属部门标识 |
否 |
|
| 职务状态 |
否 |
|
| 岗位名称 |
否 |
|
| 岗位编码 |
否 |
|
| 归属部门标识 |
否 |
|
| 岗位状态 |
否 |
|
2.2 消息对接
支持服务：通过钉钉或企业微信信息对接后，支持消息对接
预估工期：1个工作日
| 项目 |
服务说明 |
客户是否需求开发 |
|
| 消息对接 |
支持平台：钉钉、企业微信需要先做人员组织同步）
支持内容：提供文本消息通知
对接方式：需要企业微信管理员配置相关信息 |
不需要 |
|
|
|
|
|
|
2.3 第三方免登录
支持服务：使用了统一接口和统一配置，实现PC端、手机端
预估工期：3个工作日
| 免登陆类型 |
服务说明 |
客户是否需要开发 |
| PC端免登陆 |
支持平台：兼容市面上大部分oa系统，具体技术文档为准 对接方式：支持通达OA标准接口，需要客户开发接口；CAS单点登录，提供跳转链接和服务地址，无需开发 |
部分需要 |
| APP端免登陆 |
支持平台：客户APP、企业微信 对接方式：APP需要开发接口，企业微信需要提供信息配置，无需开发 |
部分需要 |
2.3.1 PC集成免登陆方案说明
2.3.1.1 标准单点技术说明
通达OA向外部系统提供一个登录URL, 外部系统按照约定的参数格式, 请求该URL即可直接登录到通达OA的首页, 无需再输入账号与密码登录。
如果外部系统有统一的“身份认证系统”， 通达OA系统在验证登陆请求时，将会回调对方的认证系统进行二次确认，确认通过后才可以登录通达OA系统。具体接入规范依据不同的外部“身份认证系统”会有不同。
安全等级：中
接口格式及参数说明
URL接口格式如下：
https://{host}/api/v1/security-center/external-auth/auth?cid=${cid}&encrypt_type=${encryptType}×tamp=${timestamp}&encrypt=${encrypt}&signature=${signature}
URL参数说明：
（HTTP请求方式为Get）
| 参数 |
类型 |
是否必填 |
说明 |
| host |
string |
是 |
通达OA系统提供的域名 |
| cid |
string |
是 |
通达OA系统分配的公司ID |
| encrypt_type |
integer |
是 |
加密类型，默认为1表示AES加密 |
| timestamp |
long |
是 |
外部系统当前时间, 单位ms |
| encrypt |
string |
是 |
约定算法加密后的请求参数。 参数格式为JSON, 如下： {“username”: “用户名”} 参数说明： username: 知学运系统中的用户名 加密算法：AES, 128位 加密处理过程： 1. 使用AES 128对JSON格式的请求参数进行加密（AES加密KEY由通达OA系统提供） 2. 将加密的内容转为为base64编码 3. 最后将base64编码内容设为URL中的encrypt参数值即可。 |
| signature |
string |
是 |
参数防修改签名。 使用SHA-1算法对URL中的参数生成签名，知学运服务端会对签名进行校验，以防止数据传输过程中参数被修改。
具体方法如下： 1. 按照参数在列表中的顺序(signature除外), 将参数都转换为string, 然后拼接，如： Cid值 + encrypt_type值 + timestamp值 + encrypt值。 2. 将拼接后的字符串，使用SHA-1算法生成一个签名字符串。 3. 将签名字符串设为signture参数值即可。
|
错误码:
| 错误码 |
说明 |
| 90202 |
参数签名验证失败 |
| 90203 |
解密消息数据失败 |
| 90113 |
不存在组织 |
| 90105 |
不存在用户 |
| 900001 |
无效输入参数 |
| 0 |
服务器内部错误 |
最终请求的URL示例：
2.3.1.2 token单点集成技术说明
客户只需要在自己系统配置通达OA接口入口 传入token值，再通过客户提供的token获取用户信息。
安全等级：高
URL接口格式如下：
https://{host}/api/v1/security-center/free-login/auth?companyId=${companyId}& code=${ code }&type=2
URL参数说明：
HTTP请求方式为Get
最终请求的URL示例：
https:// {host}/api/v1/security-center/free-login/auth?companyId=c26-4007-bda6-efbdcdcab19c&type=2
| 参数 |
类型 |
是否必填 |
说明 |
| host |
string |
是 |
通达OA系统提供的域名 |
| companyId |
string |
是 |
通达OA系统分配的公司ID |
| code |
String |
是 |
客户提供的token值，以便后面获取用户信息 |
| type |
int |
是 |
通达OA系统分配固定为2 |
注：客户需提供通过token获取用户信息URL接口
2.3.1.3 CAS单点集成技术说明
客户只需要在自己系统配置通达OACAS接口入口
安全等级：高
URL接口格式如下：
https://{host}/api/v1/security-center/cas/author?companyId=${companyId }
URL参数说明：
HTTP请求方式为Get
最终请求的URL示例：
https://{host}/api/v1/security-center/cas/author?companyId=87733719cfb26696c2df
| 参数 |
类型 |
是否必填 |
说明 |
| host |
string |
是 |
通达OA系统提供的域名 |
| companyId |
string |
是 |
通达OA系统分配的公司ID |
CAS地址说明：
CAS站点地址：客户提供
CAS登录验证地址：客户提供
2.3.2 APP集成免登陆方案说明
接入方式
甲方APP通过webview嵌入通达OAH5链接：
https://{host}/app/wechat/free-auth.html?ticket=xxx&companyId=xxx&ticketType=1
通过这个链接的ticket参数做单点登录，成功之后跳入通达OAH5首页。
链接参数说明
| 序号 |
参数名 |
类型 |
必填项 |
描述 |
| 1 |
ticket |
String |
Y |
甲方APP登录账号(需要DES加密) |
| 2 |
companyId |
String |
Y |
甲方企业id，值乙方提供 |
| 3 |
ticketType |
String |
Y |
固定传1 |
| 4 |
qrswitch |
String |
N |
1 = 打开扫一扫，0 = 关闭扫一扫 |
ticket参数DES加密说明
ticket参数传入时需要先DES加密，加密key值:J7Y7EABXOBSsuXMKNfi8fGkwrXYFundV
特殊功能说明——二维码扫描功能
如果需要扫一扫功能，则需要甲方提供接口，不需要则关闭
甲方APP原生需要提供js 方法调起APP原生扫码功能方法输出到页面，Android & iOS 输出js方法统一命名:AppScanQRCode。
乙方调用扫一扫:
window.AppScanQRCode(); // 这个方法是甲方向h5页面输出的js的方式
甲方调用乙方js将扫码结果传入：
window.getAppScanQRCodeResult( result ); // 这个方法是乙方提供给甲方调用将结果输出的方法
2.4 标准H5接入
支持服务：通过内嵌通达OA标准H5页面，实现使用账号密码登陆之后30天内免登陆
预估工期：1个工作日
| 项目 |
服务说明 |
客户是否需要开发 |
| 标准H5接入 |
支持平台：钉钉、微信公众号、APP（需要支持H5链接）
对接方式：需要提供相关信息配置，无需开发 |
不需要 |