组织同步

• 1: V8同步至三方系统
• 1.1: COP提供增量查询OpenAPI（推荐）
• 1.2: 三方系统提供写入OpenAPI
• 1.3: 事件订阅
• 2: 三方系统同步至V8
• 2.1: COP平台开放写入OpenAPI
• 2.2: 数据库中间表（推荐）
• 2.3: 第三方同步到V8常见问题

1 - V8同步至三方系统

集成模式

1.1 - COP提供增量查询OpenAPI（推荐）

1、概述

COP提供增量查询OpenAPI，由三方异构系统定时调用OpenAPI，完成组织同步模式。

2、优缺点

a. 优点：

• COP集成压力小；

b. 缺点：

• 三方系统需要有一定的研发能力，按照COP平台接口要求完成接口调用和字段映射；
• 数据时效性差，依赖定时拉取时间间隔。

3、集成配置步骤

序号	步骤名称	责任方	使用场景
1	提供组织增量查询接口规范和文档	致远	必须，包含接口定义、签名规则、字段来源等信息
2	API启用	致远	必须，只有启用的API才可以正常进行授权访问
3	新建接入应用	致远	必须，负责分配AppKey和APPSecret、配置访问授权、访问白名单等配置页
4	启用接入应用	致远	必须，未启用的接入应用，访问时会提示接入应用未启用
5	分配APPKey和APPSecret	致远	必须，接口签名核心字段
6	API授权	致远	必须，只有添加权限的额API接口才可以正常访问
7	导出接口文档	致远	非必须，导出所有已经启用的API手册
8	配置访问限流	致远	非必须，根据服务器资源性能，可以配置指定时间段内调用上线
9	配置访问白名单	致远	非必须，开启后，访问白名单之后的API请求将会被拦截
10	调用测试	三方系统	必须，根据平台提供的接口文档和必须字段，使用postmen等工具直接调用，验证网络连通性和信息准确性

4、接口目录

API分类	API名称	接口描述
组织信息查询/维护	根据条件分页查询组织详情	组织（机构+部门）
组织信息同步（基于编码）	根据组织编码查询组织详情	组织详情（机构+部门）
岗位信息查询/维护	根据条件分页查询岗位	岗位
职务信息查询/维护	根据条件分页查询职务	职务
职级信息查询/维护	根据条件分页查询职级	职级
人员信息查询/维护	根据条件查询人员信息	人员详情
人员及任职信息同步（基于编码）	分页查询组织下人员	人员&任职

4.1、接口文档在线查看位置

4.2、接口签名

4.2.1、请求头（Header）

参数名称	是否必填	参数说明
app-key	true	应用的唯一标识，创建接入应用后生成，可在应用基础信息页面获得。 示例：d43b0b442cf34076a2c4af6bb8928afb
sign-type	true	固定值：MD5
sign	true	签名，字符串“AppSecret+请求体的JSON字符串+AppSecret”的MD5值（MD5值忽略大小写） AppSecret，为应用的秘钥，创建接入应用后生成，可在应用基础信息页面获得。 示例：154fa5bc7e294deda68a15559b07c845请求体的JSON字符串， 需要将请求体中的请求参数转换为JSON字符串。
Accept-Language	false	语种：用以设置开放平台OpenAPI运行时上下文的语种参数。 枚举项可选值列表：zh-CN（简体中文）， zh-TW（繁体中文）， en（英文）， 其他枚举项请参照平台语种列表。

4.2.2、签名示例（sign）

String secret = "154fa5bc7e294deda68a15559b07c845";
String body = "{"name": "张三", "age": 35, "company": {"name": "致远", "address": "北京"}";
String sign = Md5(secret + body + secret); // 结果是 01a8795a7fe6dda23aaec40de3d301b7;

5、接口清单

5.1、根据条件分页查询组织详情

请求地址

【接口请求地址前缀】/organization/base/unit/selectPageByConditions

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		TRUE	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
pageInfo		TRUE	PageInfo	分页
pageNumber	pageInfo	TRUE	int32	当前页数
pageSize	pageInfo	TRUE	int32	每页记录数
pages	pageInfo	TRUE	int32	总页数
total	pageInfo	TRUE	int32	总记录数
needTotal	pageInfo	TRUE	boolean	是否需要查询总记录数
params		TRUE	map	条件
sort		TRUE	Sort	排序
orders	sort	TRUE	array[Sort$Order]	排序
direction	orders	TRUE	enum	顺序,可用值:ASC,DESC。 枚举项可选值列表：ASC（ASC），DESC（DESC），
property	orders	TRUE	string	字段,可用值:DTO属性(请参照"响应参数"中content), createTime,updateTime

请求参数示例

{
  "requestId": 1693208244841,
  "pageInfo": {
    "total": 0,
    "needTotal": "true",
    "pageNumber": 1,
    "pages": 0,
    "pageSize": 20
  },
  "notifyUrl": "",
  "sort": {
    "orders": [
      {
        "property": "createTime",
        "direction": "ASC"
      }
    ]
  },
  "params": { "institutionId": -8572075675821718340},
  "timestamp": 1705902274910
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			PageData	组织信息详情分页列表
pageInfo	data		PageInfo	分页参数对象
pageNumber	pageInfo		int32	当前页数
pageSize	pageInfo		int32	每页记录数
pages	pageInfo		int32	总页数
total	pageInfo		int32	总记录数
needTotal	pageInfo		boolean	是否需要查询总记录数
content	data		array[OrgUnitDto]	数据集对象
id	content		int64	组织ID,新建时不必填，修改时必填
institutionId	content		int64	组织所属机构id。 如果是部门，就是所属机构id； 如果是机构，就是自己id(不作为入参保存)
name	content		string	组织名称
mnemonic	content		string	助记符
fullName	content		string	组织的全路径名称
shortName	content		string	组织简称
logo	content		string	图标
code	content		string	组织编号
type	content		enum	组织类型。 枚举项可选值列表： NONE（空）， INSTITUTION（机构）， DEPARTMENT（部门）， OUTSIDE_INSTITUTION（外部（编外）单位）， OUTSIDE_DEPARTMENT（外部（编外）部门），
typeName	content		string	组织类型名称
parentId	content		int64	上级组织id
parentName	content		string	上级组织名称
parentCode	content		string	上级组织编号
parentUnit	content		OrgUnitDto	上级组织
firstLevelDepartment	content		OrgUnitDto	一级部门
parentUnitIdCode	content		string	上级组织ID(参照使用)(编号)
firstLevelDepartmentIdCode	content		string	一级部门ID(参照使用)(编号)
effectiveTime	content		date	生效日期，毫秒时间戳
invalidTime	content		date	失效日期，毫秒时间戳
path	content		string	全路径
orgLevel	content		int32	机构层级
sortId	content		int32	排序号
isEnable	content		boolean	状态
description	content		string	备注
authUserIds	content		string	授权用户ID集合， 只保存有效人员的id，过滤掉不符合的id
authUserNames	content		string	授权用户名称集合
businessId	content		int64	多维组织
orgUnitMetadataDto	content		OrgUnitMetadataDto	扩展字段
orgId	orgUnitMetadataDto		int64	组织id
createTime	orgUnitMetadataDto		date	创建时间，毫秒时间戳
updateTime	orgUnitMetadataDto		date	更新时间，毫秒时间戳
id	orgUnitMetadataDto		int64	字段ID
businessId	orgUnitMetadataDto		int64	业务组织id
createTime	content		date	创建时间
updateTime	content		date	更新时间
address	content		string	地址
officeNumber	content		string	电话
tax	content		string	税号
bankAccount	content		string	银行账号
bank	content		string	开户银行
isLegalEntity	content		boolean	是否法人实体
socialCreditCode	content		string	统一社会信用代码
legalPersonName	content		string	法定代表人姓名
legalCertificateNumber	content		string	法定代表人身份证号码
legalPhoneNumber	content		string	法定代表人手机号号码
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "pageInfo": {
            "pageNumber": 1,
            "pageSize": 20,
            "pages": 1,
            "total": 1,
            "needTotal": true
        },
        "content": [
            {
                "validate": true,
                "id": "-8572075675821718340",
                "institutionId": "-8572075675821718340",
                "name": "集成演示",
                "mnemonic": "jichengyanshi",
                "fullName": null,
                "shortName": "集成演示",
                "logo": null,
                "code": "aa202401190001",
                "type": "INSTITUTION",
                "typeName": null,
                "parentId": "-1730833917365171641",
                "parentName": null,
                "parentCode": "group",
                "parentUnit": null,
                "firstLevelDepartment": null,
                "parentUnitId": null,
                "firstLevelDepartmentId": null,
                "effectiveTime": 1705593600000,
                "invalidTime": 253402271999000,
                "path": "-1730833917365171641.-8572075675821718340",
                "orgLevel": 2,
                "sortId": 50500,
                "isEnable": true,
                "description": null,
                "authUserIds": null,
                "authUserNames": null,
                "businessId": "-5038278851089511626",
                "orgUnitMetadataDto": {
                    "validate": true,
                    "orgId": "-8572075675821718340",
                    "createTime": 1705658364820,
                    "updateTime": 1705658364820,
                    "id": "-468981164249889576",
                    "businessId": "-5038278851089511626"
                },
                "createTime": 1705658364723,
                "updateTime": 1705658364723,
                "address": null,
                "officeNumber": null,
                "tax": null,
                "bankAccount": null,
                "bank": null,
                "isLegalEntity": false,
                "socialCreditCode": null,
                "legalPersonName": null,
                "legalCertificateNumber": null,
                "legalPhoneNumber": null,
                "upperName1": "集成演示",
                "upperName2": "集成演示",
                "upperName3": "集成演示",
                "upperName4": "集成演示",
                "upperName5": "集成演示",
                "upperName6": "集成演示",
                "upperName7": "集成演示"
            }
        ]
    }
}

5.2、根据组织编码查询组织详情

请求地址

【接口请求地址前缀】/organization/unit/code

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		TRUE	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		TRUE	SearchUnitConditionApiDto	请求参数数据
codes	data	TRUE	array[string]	组织编码
includeDisable	data	TRUE	boolean	是否包含失效组织，默认不包含
effectiveTime	data	TRUE	string	查询某个时间点时生效的组织,缺省为系统当前时间， includeDisable为true的时候该字段不生效

请求参数示例

{
  "data": {
    "codes": [
      "aa202401190001"
    ],
    "effectiveTime": "2021-12-30",
    "includeDisable": "true"
  },
  "requestId":1705902274910,
  "notifyUrl": "",
  "timestamp":1705902274910
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			ListData	组织详情
content	data		array[OrgUnitDataDto]	数据集对象
name	content		string	组织名称
shortName	content		string	组织简称
code	content		string	组织编号
type	content		enum	组织类型。 枚举项可选值列表： NONE（空）， INSTITUTION（机构）， DEPARTMENT（部门）， OUTSIDE_INSTITUTION（外部（编外）单位）， OUTSIDE_DEPARTMENT（外部（编外）部门），
parentCode	content		string	父组织Code,根节点不填
effectiveTime	content		string	生效日期
invalidTime	content		string	失效日期
sortId	content		int32	排序号
isEnable	content		boolean	状态
description	content		string	备注
metadataList	content		array[OrgMetadataValueDataDto]	自定义扩展属性数据
k	metadataList		string	扩展字段的名称
v	metadataList		string	扩展字段的的值
address	content		string	地址
officeNumber	content		string	电话
tax	content		string	税号
bankAccount	content		string	银行账号
bank	content		string	开户银行
isLegalEntity	content		boolean	是否法人实体
socialCreditCode	content		string	统一社会信用代码
legalPersonName	content		string	法定代表人姓名
legalCertificateNumber	content		string	法定代表人身份证号码
legalPhoneNumber	content		string	法定代表人手机号号码
createTime	content		date	创建时间，毫秒时间戳
updateTime	content		date	更新时间，毫秒时间戳
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "content": [
            {
                "validate": true,
                "name": "集成演示",
                "shortName": "集成演示",
                "code": "aa202401190001",
                "type": "INSTITUTION",
                "parentCode": "group",
                "effectiveTime": "2024-01-19",
                "invalidTime": "9999-12-31",
                "sortId": 50500,
                "isEnable": true,
                "description": null,
                "businessId": "-5038278851089511626",
                "metadataList": [],
                "address": null,
                "officeNumber": null,
                "tax": null,
                "bankAccount": null,
                "bank": null,
                "isLegalEntity": false,
                "socialCreditCode": null,
                "legalPersonName": null,
                "legalCertificateNumber": null,
                "legalPhoneNumber": null,
                "createTime": 1705658364723,
                "updateTime": 1705658364723
            }
        ]
    }
}

5.3、根据条件分页查询岗位

请求地址

【接口请求地址前缀】/organization/base/post/selectPageByConditions

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		TRUE	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
pageInfo		TRUE	PageInfo	分页
pageNumber	pageInfo	TRUE	int32	当前页数
pageSize	pageInfo	TRUE	int32	每页记录数
pages	pageInfo	TRUE	int32	总页数
total	pageInfo	TRUE	int32	总记录数
needTotal	pageInfo	TRUE	boolean	是否需要查询总记录数
params		TRUE	map	条件
sort		TRUE	Sort	排序
orders	sort	TRUE	array[Sort$Order]	排序
direction	orders	TRUE	enum	顺序,可用值:ASC,DESC。 枚举项可选值列表：ASC（ASC），DESC（DESC），
property	orders	TRUE	string	字段,可用值:DTO属性(请参照"响应参数"中content), createTime,updateTime

请求参数示例

{
  "requestId": 1705902275548,
  "pageInfo": {
    "total": 0,
    "needTotal": "false",
    "pageNumber": 1,
    "pages": 0,
    "pageSize": 20
  },
  "notifyUrl": "",
  "sort": {
    "orders": [
      {
        "property": "createTime",
        "direction": "ASC"
      }
    ]
  },
  "params": {"isEnable":"true"},
  "timestamp": 1705902275548
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			PageData	岗位详情分页列表
pageInfo	data		PageInfo	分页参数对象
pageNumber	pageInfo		int32	当前页数
pageSize	pageInfo		int32	每页记录数
pages	pageInfo		int32	总页数
total	pageInfo		int32	总记录数
needTotal	pageInfo		boolean	是否需要查询总记录数
content	data		array[OrgPostDto]	数据集对象
id	content		int64	岗位ID
name	content		string	岗位名称
code	content		string	编号
type	content		int64	岗位分类的枚举id值
typeName	content		string	岗位分类的枚举名称
orgId	content		int64	所属组织
orgName	content		string	所属组织对应名称
category	content		enum	岗位分类。 枚举项可选值列表： NONE（空）， BENCH_MARK（基准岗）， SELF_BUILT（自用岗），
masterOrgId	content		int64	来源组织id
masterOrgName	content		string	来源名称
masterPostId	content		int64	来源岗位id
masterName	content		string	基准岗名称
issuedRule	content		enum	使用范围。 枚举项可选值列表： NONE（没有范围）， INSTITUTION（本机构）， INSTITUTIONS（本机构及下级机构）， ONLY_CHILDREN（仅下级机构）， SPECIFY_INSTITUTION（指定机构）， SPECIFY_INSTITUTIONS（指定机构及下级机构），
businessId	content		int64	所属业务线id
sortId	content		int32	排序号
isEnable	content		boolean	启用状态
description	content		string	备注
createTime	content		date	创建时间，毫秒时间戳
updateTime	content		date	更新时间，毫秒时间戳
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "pageInfo": {
            "pageNumber": 1,
            "pageSize": 20,
            "pages": 0,
            "total": 0,
            "needTotal": false
        },
        "content": [
            {
                "validate": true,
                "id": "-5045874864559469310",
                "name": "岗位1",
                "code": "P202110280001",
                "type": "-4620025823759349735",
                "typeName": null,
                "orgId": "-1730833917365171641",
                "orgName": "致远互联",
                "category": "SELF_BUILT",
                "masterOrgId": "-1",
                "masterOrgName": "",
                "masterPostId": "-1",
                "masterName": "",
                "issuedRule": "NONE",
                "businessId": "158912402929426432",
                "sortId": 60,
                "isEnable": true,
                "description": "",
                "createTime": 1635385247000,
                "updateTime": 1635385247000
            },
            {
                "validate": true,
                "id": "7568497936381004239",
                "name": "dx岗位",
                "code": "xwAMtn29yK",
                "type": "6541964214010466245",
                "typeName": "技术类",
                "orgId": "-2740929138088457741",
                "orgName": "dx的机构1",
                "category": "BENCH_MARK",
                "masterOrgId": "-1730833917365171641",
                "masterOrgName": "",
                "masterPostId": "2693847020086313280",
                "masterName": "",
                "issuedRule": "NONE",
                "businessId": "158912402929426432",
                "sortId": 70,
                "isEnable": true,
                "description": "",
                "createTime": 1635386908000,
                "updateTime": 1703161499014
            }
        ]
    }
}

5.4、根据条件分页查询职务

请求地址

【接口请求地址前缀】/organization/base/job/selectPageByConditions

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		TRUE	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
pageInfo		TRUE	PageInfo	分页
pageNumber	pageInfo	TRUE	int32	当前页数
pageSize	pageInfo	TRUE	int32	每页记录数
pages	pageInfo	TRUE	int32	总页数
total	pageInfo	TRUE	int32	总记录数
needTotal	pageInfo	TRUE	boolean	是否需要查询总记录数
params		TRUE	map	条件
sort		TRUE	Sort	排序
orders	sort	TRUE	array[Sort$Order]	排序
direction	orders	TRUE	enum	顺序,可用值:ASC,DESC。 枚举项可选值列表：ASC（ASC），DESC（DESC），
property	orders	TRUE	string	字段,可用值:DTO属性(请参照"响应参数"中content), createTime,updateTime

请求参数示例

{
  "requestId": "-3185185534174541324",
  "pageInfo": {
    "total": 0,
    "needTotal": "false",
    "pageNumber": 1,
    "pages": 0,
    "pageSize": 20
  },
  "notifyUrl": "",
  "sort": {
    "orders": [
      {
        "property": "createTime",
        "direction": "ASC"
      }
    ]
  },
   "params": {"isEnable":"true"},
  "timestamp": {{timestamp}}
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			PageData	职务详情分页列表
pageInfo	data		PageInfo	分页参数对象
pageNumber	pageInfo		int32	当前页数
pageSize	pageInfo		int32	每页记录数
pages	pageInfo		int32	总页数
total	pageInfo		int32	总记录数
needTotal	pageInfo		boolean	是否需要查询总记录数
content	data		array[OrgJobDto]	数据集对象
id	content		int64	职务主表id
name	content		string	职务名称
code	content		string	编号
orgId	content		int64	组织id
businessId	content		int64	所属业务线id
category	content		enum	职务类型。枚举项可选值列表： NONE（空）， BENCH_MARK（基准岗）， SELF_BUILT（自用岗），
masterOrgId	content		int64	来源组织id
masterOrgName	content		string	来源名称
masterJobId	content		int64	来源职务id
masterName	content		string	基准职务名称
issuedRule	content		enum	使用范围。枚举项可选值列表： NONE（没有范围）， INSTITUTION（本机构）， INSTITUTIONS（本机构及下级机构）， ONLY_CHILDREN（仅下级机构）， SPECIFY_INSTITUTION（指定机构）， SPECIFY_INSTITUTIONS（指定机构及下级机构），
orgName	content		string	组织id对应的名称(不作为入参保存)
sortId	content		int32	排序号
isEnable	content		boolean	启用状态
description	content		string	备注
createTime	content		date	创建时间，毫秒时间戳
updateTime	content		date	更新时间，毫秒时间戳
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "pageInfo": {
            "pageNumber": 1,
            "pageSize": 20,
            "pages": 0,
            "total": 0,
            "needTotal": false
        },
        "content": [
            {
                "validate": true,
                "id": "-1834341499691513847",
                "name": "PFJOB_1635933769253",
                "code": "PFJOB_1635933769253",
                "orgId": "-791902958315615749",
                "businessId": "158912402929426432",
                "category": "SELF_BUILT",
                "masterOrgId": "-1",
                "masterOrgName": "",
                "masterJobId": "-1",
                "masterName": "",
                "issuedRule": "NONE",
                "orgName": "",
                "sortId": 1,
                "isEnable": true,
                "description": "联系地址：北坞村路静芯园",
                "createTime": 1635933764000,
                "updateTime": 1635933770000
            },
            {
                "validate": true,
                "id": "-5262676242410946209",
                "name": "PFJOB_1635933767443",
                "code": "PFJOB_1635933767443",
                "orgId": "-8474839543092329115",
                "businessId": "158912402929426432",
                "category": "SELF_BUILT",
                "masterOrgId": "-1",
                "masterOrgName": "",
                "masterJobId": "-1",
                "masterName": "",
                "issuedRule": "NONE",
                "orgName": "",
                "sortId": 1,
                "isEnable": true,
                "description": "联系地址：北坞村路静芯园",
                "createTime": 1635933767000,
                "updateTime": 1635933767000
            }
        ]
    }
}

5.5、根据条件分页查询职级

请求地址

【接口请求地址前缀】/organization/base/level/selectPageByConditions

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		TRUE	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
pageInfo		TRUE	PageInfo	分页
pageNumber	pageInfo	TRUE	int32	当前页数
pageSize	pageInfo	TRUE	int32	每页记录数
pages	pageInfo	TRUE	int32	总页数
total	pageInfo	TRUE	int32	总记录数
needTotal	pageInfo	TRUE	boolean	是否需要查询总记录数
params		TRUE	map	条件
sort		TRUE	Sort	排序
orders	sort	TRUE	array[Sort$Order]	排序
direction	orders	TRUE	enum	顺序,可用值:ASC,DESC。 枚举项可选值列表： ASC（ASC）， DESC（DESC），
property	orders	TRUE	string	字段,可用值:DTO属性(请参照"响应参数"中content), createTime,updateTime

请求参数示例

{
  "requestId": "6230484731964183507",
  "pageInfo": {
    "total": 0,
    "needTotal": "false",
    "pageNumber": 1,
    "pages": 0,
    "pageSize": 20
  },
  "notifyUrl": "",
  "sort": {
    "orders": [
      {
        "property": "createTime",
        "direction": "ASC"
      }
    ]
  },
  "params": {"isEnable":"true"},
  "timestamp":1705902275451
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			PageData	职级详情分页列表
pageInfo	data		PageInfo	分页参数对象
pageNumber	pageInfo		int32	当前页数
pageSize	pageInfo		int32	每页记录数
pages	pageInfo		int32	总页数
total	pageInfo		int32	总记录数
needTotal	pageInfo		boolean	是否需要查询总记录数
content	data		array[OrgLevelDto]	数据集对象
id	content		int64	职级ID
name	content		string	职级名称
code	content		string	编号
businessId	content		int64	所属业务线id
orgId	content		int64	组织id
levelSort	content		int32	序号
isEnable	content		boolean	启用状态
description	content		string	备注
createTime	content		date	创建时间，毫秒时间戳
updateTime	content		date	更新时间，毫秒时间戳
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "pageInfo": {
            "pageNumber": 1,
            "pageSize": 20,
            "pages": 0,
            "total": 0,
            "needTotal": false
        },
        "content": [
            {
                "validate": true,
                "id": "9029437603602253763",
                "name": "测试职级",
                "code": "L202110270001",
                "businessId": "158912402929426432",
                "orgId": "-1730833917365171641",
                "levelSort": 10,
                "isEnable": true,
                "description": "",
                "createTime": 1635329898000,
                "updateTime": 1635329898000
            }
        ]
    }
}

5.6、根据条件查询人员信息

请求地址

【接口请求地址前缀】/organization/base/member/selectListByConditions

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		TRUE	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
params		TRUE	map	条件
sort		TRUE	Sort	排序
orders	sort	TRUE	array[Sort$Order]	排序
direction	orders	TRUE	enum	顺序,可用值:ASC,DESC。 枚举项可选值列表： ASC（ASC）， DESC（DESC），
property	orders	TRUE	string	字段,可用值:DTO属性(请参照"响应参数"中content), createTime,updateTime

请求参数示例

{
  "requestId": "-6815387152900730785",
  "pageInfo": {
    "total": 0,
    "needTotal": "false",
    "pageNumber": 1,
    "pages": 0,
    "pageSize": 20
  },
  "notifyUrl": "",
  "sort": {
    "orders": [
      {
        "property": "createTime",
        "direction": "ASC"
      }
    ]
  },
  "params": {
    "code": "aa202401190001",
    "memberType": "MEMBER"
  },
  "timestamp": 1705902274312
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			ListData	人员详情列表
content	data		array[OrgMemberDto]	数据集对象
id	content		int64	人员id,新建时不必填，修改时必填
thirdId	content		string	第三方唯一标识
name	content		string	姓名
defaultName	content		string	默认语种姓名
mnemonic	content		string	助记符
code	content		string	编号
image	content		string	头像id
gender	content		enum	性别。枚举项可选值列表： NONE（空）， MALE（男）， FEMALE（女）， UN_KNOW（未知），
birthday	content		date	出生日期
phoneNumber	content		string	手机号码
officeNumber	content		string	工作电话
email	content		string	邮箱
effectiveTime	content		date	生效日期，毫秒时间戳
invalidTime	content		date	失效日期，毫秒时间戳
sortId	content		int32	排序号
isEnable	content		boolean	状态
description	content		string	备注
orgMemberPostDtoList	content		array[OrgMemberPostDto]	人员所有任职信息
id	orgMemberPostDtoList		int64	任职信息id
businessId	orgMemberPostDtoList		int64	业务组织id(缺省行政组织)
businessName	orgMemberPostDtoList		string	业务组织名称(缺省行政组织)
memberIdCode	orgMemberPostDtoList		string	人员id(编号)
memberName	orgMemberPostDtoList		string	人员名称
memberCode	orgMemberPostDtoList		string	人员编号
main	orgMemberPostDtoList		boolean	是否主岗
orgIdCode	orgMemberPostDtoList		string	所属组织(编号)
orgName	orgMemberPostDtoList		string	所属组织名称
orgCode	orgMemberPostDtoList		string	所属组织编号
fullName	orgMemberPostDtoList		string	组织全路径名称
path	orgMemberPostDtoList		string	path
institutionIdCode	orgMemberPostDtoList		string	组织所属机构(编号)
institutionName	orgMemberPostDtoList		string	组织所属机构名称
institutionCode	orgMemberPostDtoList		string	组织所属机构编号
postIdCode	orgMemberPostDtoList		string	岗位(编号)
postName	orgMemberPostDtoList		string	岗位名称
postCode	orgMemberPostDtoList		string	岗位编号
levelIdCode	orgMemberPostDtoList		string	职级(编号)
levelName	orgMemberPostDtoList		string	职级名称
levelCode	orgMemberPostDtoList		string	职级编号
jobId	orgMemberPostDtoList		int64	职务
jobName	orgMemberPostDtoList		string	职务名称
jobCode	orgMemberPostDtoList		string	职务编号
effectiveTime	orgMemberPostDtoList		date	生效日期，毫秒时间戳
invalidTime	orgMemberPostDtoList		date	失效日期，毫秒时间戳
sortId	orgMemberPostDtoList		int32	排序号
topSortId	orgMemberPostDtoList		int32	优先排序顺序
isEnable	orgMemberPostDtoList		boolean	状态
effective	orgMemberPostDtoList		boolean	生效状态
edit	orgMemberPostDtoList		boolean	是否可编辑
createTime	orgMemberPostDtoList		date	创建时间，毫秒时间戳
updateTime	orgMemberPostDtoList		date	更新时间，毫秒时间戳
type	orgMemberPostDtoList		enum	账号类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， EXTERNAL_MEMBER（外部联系人），
memberType	orgMemberPostDtoList		enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
outsideInstitutionId	orgMemberPostDtoList		int64	人员所在外部单位
mainMemberPost	content		OrgMemberPostDto	人员主岗任职信息
id	mainMemberPost		int64	任职信息id
businessId	mainMemberPost		int64	业务组织id(缺省行政组织)
businessName	mainMemberPost		string	业务组织名称(缺省行政组织)
memberIdCode	mainMemberPost		string	人员id(编号)
memberName	mainMemberPost		string	人员名称
memberCode	mainMemberPost		string	人员编号
main	mainMemberPost		boolean	是否主岗
orgIdCode	mainMemberPost		string	所属组织(编号)
orgName	mainMemberPost		string	所属组织名称
orgCode	mainMemberPost		string	所属组织编号
fullName	mainMemberPost		string	组织全路径名称
path	mainMemberPost		string	path
institutionIdCode	mainMemberPost		string	组织所属机构(编号)
institutionName	mainMemberPost		string	组织所属机构名称
institutionCode	mainMemberPost		string	组织所属机构编号
postIdCode	mainMemberPost		string	岗位(编号)
postName	mainMemberPost		string	岗位名称
postCode	mainMemberPost		string	岗位编号
levelIdCode	mainMemberPost		string	职级(编号)
levelName	mainMemberPost		string	职级名称
levelCode	mainMemberPost		string	职级编号
jobId	mainMemberPost		int64	职务
jobName	mainMemberPost		string	职务名称
jobCode	mainMemberPost		string	职务编号
effectiveTime	mainMemberPost		date	生效日期，毫秒时间戳
invalidTime	mainMemberPost		date	失效日期，毫秒时间戳
sortId	mainMemberPost		int32	排序号
topSortId	mainMemberPost		int32	优先排序顺序
isEnable	mainMemberPost		boolean	状态
effective	mainMemberPost		boolean	生效状态
edit	mainMemberPost		boolean	是否可编辑
createTime	mainMemberPost		date	创建时间，毫秒时间戳
updateTime	mainMemberPost		date	更新时间，毫秒时间戳
type	mainMemberPost		enum	账号类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， EXTERNAL_MEMBER（外部联系人），
memberType	mainMemberPost		enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
outsideInstitutionId	mainMemberPost		int64	人员所在外部单位
mainMemberPostId	content		int64	人员主岗任职Id信息
orgMemberMetadataDto	content		OrgMemberMetadataDto	扩展字段
memberId	orgMemberMetadataDto		int64	人员id
createTime	orgMemberMetadataDto		date	创建时间，毫秒时间戳
updateTime	orgMemberMetadataDto		date	更新时间，毫秒时间戳
id	orgMemberMetadataDto		int64	字段ID
businessId	orgMemberMetadataDto		int64	业务组织id
loginName	content		string	用户名
createTime	content		date	创建时间，毫秒时间戳
updateTime	content		date	更新时间，毫秒时间戳
certificateType	content		int64	证件类型
certificateNumber	content		string	证件号码
entryDate	content		date	入职日期
bankAccount	content		string	银行账号
bank	content		string	开户银行
bankOutlets	content		string	开户网点
memberType	content		enum	人员类型。 枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
pinyinShort	content		string	简拼
nickName	content		string	昵称
orgName	content		string	主部门名称
postName	content		string	主岗位名称
jobName	content		string	主职务名称
levelName	content		string	主职级名称
naturalMemberType	content		int64	外部个人用户类型
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "content": [
            {
                "validate": true,
                "id": "3428073205378313571",
                "thirdId": null,
                "name": "V5-韩聚江",
                "defaultName": "V5-韩聚江",
                "mnemonic": "V5-hanjujiang",
                "code": "17301103865",
                "image": null,
                "gender": "UN_KNOW",
                "birthday": null,
                "phoneNumber": "17301103865",
                "officeNumber": null,
                "email": "",
                "effectiveTime": 1703520000000,
                "invalidTime": 253402271999000,
                "sortId": 1,
                "isEnable": true,
                "description": null,
                "orgMemberPostDtoList": [
                    {
                        "validate": true,
                        "id": "5994200321357481820",
                        "businessId": "-5038278851089511626",
                        "businessName": null,
                        "memberName": null,
                        "memberCode": null,
                        "main": true,
                        "orgName": "集成演示",
                        "orgCode": "aa202401190001",
                        "fullName": "致远互联/集成演示",
                        "path": null,
                        "institutionName": null,
                        "institutionCode": null,
                        "postName": "集团基准岗位",
                        "postCode": "P202309080001",
                        "levelName": "经理级",
                        "levelCode": "M1",
                        "jobId": "-1",
                        "jobName": null,
                        "jobCode": null,
                        "effectiveTime": 1703520000000,
                        "invalidTime": 253402271999000,
                        "sortId": 1,
                        "topSortId": 0,
                        "isEnable": true,
                        "effective": null,
                        "edit": null,
                        "createTime": 1703557326026,
                        "updateTime": 1705658413047,
                        "type": "MEMBER",
                        "memberType": "MEMBER",
                        "outsideInstitutionId": "-1",
                        "memberIdCode": "17301103865",
                        "orgIdCode": "aa202401190001",
                        "institutionIdCode": "aa202401190001",
                        "postIdCode": "P202309080001",
                        "levelIdCode": "M1"
                    }
                ],
                "mainMemberPost": {
                    "validate": true,
                    "id": "5994200321357481820",
                    "businessId": "-5038278851089511626",
                    "businessName": null,
                    "memberName": null,
                    "memberCode": null,
                    "main": true,
                    "orgName": "集成演示",
                    "orgCode": "aa202401190001",
                    "fullName": "致远互联/集成演示",
                    "path": null,
                    "institutionName": null,
                    "institutionCode": null,
                    "postName": "集团基准岗位",
                    "postCode": "P202309080001",
                    "levelName": "经理级",
                    "levelCode": "M1",
                    "jobId": "-1",
                    "jobName": null,
                    "jobCode": null,
                    "effectiveTime": 1703520000000,
                    "invalidTime": 253402271999000,
                    "sortId": 1,
                    "topSortId": 0,
                    "isEnable": true,
                    "effective": null,
                    "edit": null,
                    "createTime": 1703557326026,
                    "updateTime": 1705658413047,
                    "type": "MEMBER",
                    "memberType": "MEMBER",
                    "outsideInstitutionId": "-1",
                    "memberIdCode": "17301103865",
                    "orgIdCode": "aa202401190001",
                    "institutionIdCode": "aa202401190001",
                    "postIdCode": "P202309080001",
                    "levelIdCode": "M1"
                },
                "mainMemberPostId": "5994200321357481820",
                "orgMemberMetadataDto": {
                    "validate": true,
                    "id": "8947821149131146285",
                    "businessId": null,
                    "extAttr1": "",
                    "extAttr2": null,
                    "extAttr3": "17301103865",
                    "extAttr4": null,
                    "extAttr5": "V5-韩聚江",
                    "extAttr6": "17301103865",
                    "extAttr7": null,
                    "extAttr8": null,
                    "extAttr9": null,
                    "extAttr10": null,
                    "memberId": "3428073205378313571",
                    "createTime": 1703557324415,
                    "updateTime": 1705658413129
                },
                "loginName": "17301103865",
                "createTime": 1703557324142,
                "updateTime": 1705658413004,
                "certificateType": null,
                "certificateNumber": null,
                "entryDate": null,
                "bankAccount": null,
                "bank": null,
                "bankOutlets": null,
                "memberType": "MEMBER",
                "pinyinShort": "V5-hjj",
                "nickName": null,
                "orgName": "集成演示",
                "postName": "集团基准岗位",
                "jobName": null,
                "levelName": "经理级",
                "naturalMemberType": null
            }
        ]
    }
}

5.7、分页查询组织下人员

请求地址

【接口请求地址前缀】/organization/unit/members

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		TRUE	string	异步回调URL。如果此参数非空， 表示使用异步方式调用开放API，执行结果将通过此URL异步通知调用者。
params		TRUE	SearchMemberApiDto	泛型参数对象
code	params	TRUE	string	组织code
includeChild	params	TRUE	boolean	是否包含下级
effectiveTime	params	TRUE	string	人员生效时间,缺省系统当前时间， 配置了搜索开始/结束时间，该值不生效
startTime	params	TRUE	string	搜索开始时间
endTime	params	TRUE	string	搜索结束时间
includeDisable	params	TRUE	boolean	是否包含失效人员，默认不包含
memberType	params	TRUE	enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
sort		TRUE	Sort	排序
orders	sort	TRUE	array[Sort$Order]	排序
direction	orders	TRUE	enum	顺序,可用值:ASC,DESC。 枚举项可选值列表：ASC（ASC），DESC（DESC），
property	orders	TRUE	string	字段,可用值:DTO属性(请参照"响应参数"中content), createTime,updateTime
pageInfo		TRUE	PageInfo	分页
pageNumber	pageInfo	TRUE	int32	当前页数
pageSize	pageInfo	TRUE	int32	每页记录数
pages	pageInfo	TRUE	int32	总页数
total	pageInfo	TRUE	int32	总记录数
needTotal	pageInfo	TRUE	boolean	是否需要查询总记录数

请求参数示例

{
  "requestId": "-6815387152900730785",
  "pageInfo": {
    "total": 0,
    "needTotal": "false",
    "pageNumber": 1,
    "pages": 0,
    "pageSize": 20
  },
  "notifyUrl": "",
  "sort": {
    "orders": [
      {
        "property": "createTime",
        "direction": "ASC"
      }
    ]
  },
  "params": {
    "code": "aa202401190001",
    "memberType": "MEMBER"
  },
  "timestamp": 1705902274312
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			PageData	人员信息分页列表
pageInfo	data		PageInfo	分页参数对象
pageNumber	pageInfo		int32	当前页数
pageSize	pageInfo		int32	每页记录数
pages	pageInfo		int32	总页数
total	pageInfo		int32	总记录数
needTotal	pageInfo		boolean	是否需要查询总记录数
content	data		array[OrgMemberDataDto]	数据集对象
thirdId	content		string	第三方唯一标识
name	content		string	姓名
code	content		string	编号
username	content		string	用户名
gender	content		enum	性别。枚举项可选值列表： NONE（空）， MALE（男）， FEMALE（女）， UN_KNOW（未知），
birthday	content		string	出生日期
phoneNumber	content		string	手机号码
officeNumber	content		string	工作电话
email	content		string	邮箱
effectiveTime	content		string	生效日期
invalidTime	content		string	失效日期
sortId	content		int32	排序号
isEnable	content		boolean	状态
description	content		string	备注
memberPosts	content		array[OrgMemberPostDataDto]	人员的任职信息
main	memberPosts		boolean	是否主岗
unitCode	memberPosts		string	组织编码
postCode	memberPosts		string	岗位编码(内部人员必填)
levelCode	memberPosts		string	职级编码
jobCode	memberPosts		string	职务编码
effectiveTime	memberPosts		string	生效日期
invalidTime	memberPosts		string	失效日期
sortId	memberPosts		int32	排序号
topSortId	memberPosts		int32	优先置顶排序
isEnable	memberPosts		boolean	状态
memberType	memberPosts		enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
metadataList	content		array[OrgMetadataValueDataDto]	自定义扩展属性数据
k	metadataList		string	扩展字段的名称
v	metadataList		string	扩展字段的的值
certificateType	content		string	证件类型
certificateNumber	content		string	证件号码
entryDate	content		string	入职日期
bankAccount	content		string	银行账号
bank	content		string	开户银行
bankOutlets	content		string	开户网点
image	content		string	头像路径
memberType	content		enum	人员类型。枚举项可选值列表： NONE（空），MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
createTime	content		date	创建时间，毫秒时间戳
updateTime	content		date	更新时间，毫秒时间戳
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "pageInfo": {
            "pageNumber": 1,
            "pageSize": 20,
            "pages": 1,
            "total": 2,
            "needTotal": false
        },
        "content": [
            {
                "validate": true,
                "thirdId": null,
                "name": "V5-韩聚江",
                "code": "17301103865",
                "username": "17301103865",
                "gender": "UN_KNOW",
                "birthday": null,
                "phoneNumber": "17301103865",
                "officeNumber": null,
                "email": "",
                "effectiveTime": "2023-12-26",
                "invalidTime": "9999-12-31",
                "sortId": 1,
                "isEnable": true,
                "description": null,
                "memberPosts": [
                    {
                        "validate": true,
                        "main": true,
                        "businessId": "administrative",
                        "unitCode": "aa202401190001",
                        "postCode": "P202309080001",
                        "levelCode": "M1",
                        "jobCode": "",
                        "effectiveTime": "2023-12-26",
                        "invalidTime": "9999-12-31",
                        "sortId": 1,
                        "topSortId": 0,
                        "isEnable": true,
                        "memberType": "MEMBER"
                    }
                ],
                "metadataList": null,
                "certificateType": null,
                "certificateNumber": null,
                "entryDate": null,
                "bankAccount": null,
                "bank": null,
                "bankOutlets": null,
                "image": null,
                "memberType": "MEMBER",
                "createTime": 1703557324142,
                "updateTime": 1705658413004
            },
            {
                "validate": true,
                "thirdId": null,
                "name": "韩聚江",
                "code": "MD80002724",
                "username": "15131872776",
                "gender": "MALE",
                "birthday": null,
                "phoneNumber": "15131872776",
                "officeNumber": null,
                "email": null,
                "effectiveTime": "2024-01-19",
                "invalidTime": "9999-12-31",
                "sortId": 50430,
                "isEnable": true,
                "description": null,
                "memberPosts": [
                    {
                        "validate": true,
                        "main": true,
                        "businessId": "administrative",
                        "unitCode": "aa202401190001",
                        "postCode": "P202206150020",
                        "levelCode": "M1",
                        "jobCode": "",
                        "effectiveTime": "2024-01-19",
                        "invalidTime": "9999-12-31",
                        "sortId": 50430,
                        "topSortId": 0,
                        "isEnable": true,
                        "memberType": "MEMBER"
                    }
                ],
                "metadataList": null,
                "certificateType": "861893055660261888",
                "certificateNumber": null,
                "entryDate": null,
                "bankAccount": null,
                "bank": null,
                "bankOutlets": null,
                "image": null,
                "memberType": "MEMBER",
                "createTime": 1705642397823,
                "updateTime": 1705658448012
            }
        ]
    }
}

6、注意事项

为了三方系统更快集成，建议每个三方系统提供postmen调用示例，这样可以极大的节省集成联调周期。

1.2 - 三方系统提供写入OpenAPI

1、概述

COP负责新建、编辑、启停等组织数据维护，三方异构系统提供写入OpenAPI，由COP定时调用接口主动推送，完成组织同步模式。

2、优缺点

a. 优点：

i. 三方系统集成压力小；

ii. 通过事件订阅触发数据同步，数据时效性高；

b. 缺点：

i. 实施团队需要了解三方系统接口字段要求和数据用途；

ii. 实施团队需要了解COP平台字段要求和用途；

iii. 实施团队需要配置字段映射；

iv. 每增加一个三方系统，就需要重新配置一遍一下步骤；

3、操作步骤

序号	步骤名称	责任方	使用场景
1	提供组织增量写入接口规范和文档	三方系统	必须，
2	注册并配置鉴权AppID和秘钥	三方系统	非必须，如果三方系统接口调用时涉及到安全鉴权，则需要提供
3	提供接口调用示例	三方系统	必须，为了集成效率， 强烈建议三方系统提供可直接使用的postman接口调用示例，
4	新建三方集成应用	致远	必须，三方集成应用负责封装三方系统接口和配置数据映射
5	发布启用三方集成应用	致远	必须，三方集成应用只有发布后才能正常使用
6	封装安全认证	致远	非必须，如果三方系统接口调用时涉及到安全鉴权，则需要配置安全认证
7	接口封装	致远	必须，三方系统提供的接口只有正常封装后才能供给COP使用
8	在线调试验证	致远	必须，三方系统接口封装完成后，需要在线调试，验证网络通信、 接口返回结果是否正确等
9	启用组织同步	致远	必须，主动推送场景中，字段映射、同步周期需要在基础集成中配置
10	配置同步内容	致远	必须，本场景下固定选择模式为：从三方系统获取
11	配置同步周期	致远	必须，根据数据量和服务器消费能力，合理配置同步周期
12	配置字段映射	致远	必须：三方系统接口文档中的字段名，字段释义与COP不一致， 需要配置参数映射、层级转换等
13	使用日志	致远	必须，配置完成并启用后，查看使用日志

4、 集成配置步骤

4.1、 新建三方集成应用

4.2、 发布启用三方集成应用

4.3、 封装安全认证

4.4、 枚举定义

4.5、 接口封装

4.6、 在线调试验证

4.7、 启用组织同步

4.8、 配置同步内容

4.9、 配置同步周期

4.10、 使用日志

5、 注意事项

5.1、 当三方系统需要的数据维度较COP更加丰富时，可以通过集成扩展-微流程编排实现；

1.3 - 事件订阅

1、概述

COP开放事件，三方异构系统订阅事件，完成组织同步模式。

2、事件清单

事件名称	事件标识	返回数据类型	描述
更新职务	organization.job.update	JSON	更新职务
更新组织	organization.unit.update	JSON	更新组织
更新职级	organization.level.update	JSON	更新职级
创建组织	organization.unit.create	JSON	创建组织
创建人员	organization.member.create	JSON	创建人员
创建岗位	organization.post.create	JSON	创建岗位
更新岗位	organization.post.update	JSON	更新岗位
创建职务	organization.job.create	JSON	创建职务
更新人员	organization.member.update	JSON	更新人员
创建职级	organization.level.create	JSON	创建职级

3、订阅说明

收到事件通知请求后，需要返回200HTTP响应。其余响应码表示失败，开放平台会自动重发。重发的间隔越来越长，最多尝试10次。事件通知数据使用application/json格式发送。 事件通知的HTTP请求头中，包含回调令牌（需在接入应用的事件订阅中配置开启，默认不开启），用于接入应用验证事件来源。

若开启加密因子（需在接入应用的事件订阅中配置开启，默认不开启），将对事件通知的JSON内容进行加密，只有一个属性encrypt，需要进行解密处理。

4、解密示例

 @SuppressWarnings("rawtypes")
    @PostMapping("open-event-map")
    @ResponseBody
    public String openEventCallBack(HttpServletRequest request, @RequestBody Map map) {
      // 事件发生时间
      String createTime = request.getHeader("createTime");
      // 事件的流水号
      String eventId = request.getHeader("eventId");
      // 如果订阅事件时设置了回调token，可以获取token进行校验
      String eventToken = request.getHeader("eventToken");
      if (!OpenApiGlobalConfig.EVENT_CALL_BACK_TOKEN.equals(eventToken)) {
        System.err.println("token不匹配，这是非法的请求！");
        return "error";
      }
      // eventName：事件名称，解码处理
      try {
        String eventName = URLDecoder.decode(request.getHeader("eventName"), StandardCharsets.UTF_8.displayName());
        System.err.println("收到事件：" + eventName);
      } catch (UnsupportedEncodingException e) {
        e.printStackTrace();
      }
      // 事件标识，可以用此字段区分是什么事件发生了
      String eventKey = request.getHeader("eventKey");
      if (!"".equals(OpenApiGlobalConfig.EVENT_CALL_BACK_KEY)) {
        // 如果设置了加密key，那么返回的数据是加密的，需要解密。加解密算法是AES算法。
        String encryptContent = (String) map.get("encrypt");
        String realContent = OpenApiClient.decrypt(encryptContent, OpenApiGlobalConfig.EVENT_CALL_BACK_KEY);
        System.err.println("原始的JSON数据是：" + realContent);
        // 拿到原始的json串以后，可以json串转map或者转对应的DTO，继续处理
        Map dataMap = OpenApiUtil.fromJson(realContent, Map.class);
        // 后续处理
        System.err.println("事件真实数据：" + dataMap);
      } else {
        // 如果没有配置加密，那么是明文传输的，收到的Map就是真实的数据
        Map dataMap = map;
        // 后续处理
        System.err.println("事件真实数据：" + dataMap);
      }
      return "OK";
    }

5、事件消息体

5.1、更新职务

参数名称	参数类型	参数描述
更新职务消息	OrgJobUpdateMessage
jobId	int64	职务id
code	string	职务编号
orgId	int64	所属组织
isEnable	boolean	状态
oldCode	string	更新前职务编号
oldOrgId	int64	更新前所属组织
oldIsEnable	boolean	更新前状态
eventKey	string	消息标识

5.2、更新组织

参数名称	参数类型	参数描述
更新组织消息体	OrgUnitUpdateMessage
type	enum	组织类型。枚举项可选值列表： NONE（空）， INSTITUTION（机构）， DEPARTMENT（部门）， OUTSIDE_INSTITUTION（外部（编外）单位）， OUTSIDE_DEPARTMENT（外部（编外）部门），
orgId	int64	组织id
oldOrgName	string	组织名称
orgName	string	组织名称
oldParentId	int64	原上级id
parentId	int64	上级id
oldIsEnable	boolean	原状态
isEnable	boolean	状态
oldEffectiveTime	date	原生效日期
effectiveTime	date	生效日期
oldInvalidTime	date	原失效日期
invalidTime	date	失效日期
eventKey	string	消息标识

5.3、更新职级

参数名称	参数类型	参数描述
更新职级消息	OrgLevelUpdateMessage
levelId	int64	职级id
code	string	职级编号
levelSort	int32	职级序号
isEnable	boolean	状态
oldCode	string	职级编号
oldLevelSort	int32	更新前职级序号
oldIsEnable	boolean	更新前状态
eventKey	string	消息标识

5.4、创建组织

参数名称	参数类型	参数描述
创建组织消息体	OrgUnitCreateMessage
orgId	int64	组织id
orgName	string	组织名称
parentId	int64	上级id
type	enum	组织类型。枚举项可选值列表： NONE（空）， INSTITUTION（机构）， DEPARTMENT（部门）， OUTSIDE_INSTITUTION（外部（编外）单位）， OUTSIDE_DEPARTMENT（外部（编外）部门），
isEnable	boolean	状态
effectiveTime	date	生效日期
invalidTime	date	失效日期
eventKey	string	消息标识

5.5、创建人员

数名称	参数类型	参数描述
创建人员消息体	OrgMemberMessage
memberId	int64	人员id
name	string	姓名
phoneNumber	string	手机号
email	string	邮箱
type	enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
image	string	头像
orgId	int64	主岗组织id
orgName	string	主岗组织名称
orgIds	array[int64]	主岗所属机构id
isEnable	boolean	启用状态
effectiveTime	date	生效日期
invalidTime	date	失效日期
eventKey	string	消息标识
memberPostList	array[OrgMemberPostBaseDto]	任职信息
id	int64	任职id
main	boolean	是否主岗
orgId	int64	组织id
postId	int64	岗位id
levelId	int64	职级id
jobId	int64	职务id
sortId	int32	排序号
isEnable	boolean	状态
effectiveTime	date	生效日期，毫秒时间戳
invalidTime	date	失效日期，毫秒时间戳

5.6、创建岗位

参数名称	参数类型	参数描述
创建岗位消息	OrgPostCreateMessage
postId	int64	岗位id
code	string	岗位编号
orgId	int64	所属组织
isEnable	boolean	状态
eventKey	string	消息标识

5.7、更新岗位

参数名称	参数类型	参数描述
更新岗位消息	OrgPostUpdateMessage
postId	int64	岗位id
code	string	岗位编号
orgId	int64	所属组织
isEnable	boolean	状态
oldCode	string	更新前岗位编号
oldOrgId	int64	更新前所属组织
oldIsEnable	boolean	更新前状态
eventKey	string	消息标识

5.8、创建职务

参数名称	参数类型	参数描述
创建职务消息	OrgJobCreateMessage
jobId	int64	职务id
code	string	职务编号
orgId	int64	所属组织
isEnable	boolean	状态
eventKey	string	消息标识

5.9、更新人员

参数名称	参数类型	参数描述
更新人员消息体	OrgUpdateMemberMessage
memberId	int64	人员id
name	string	姓名
phoneNumber	string	手机号
email	string	邮箱
type	enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
image	string	头像
orgId	int64	主岗组织id
orgName	string	主岗组织名称
orgIds	array[int64]	主岗所属机构id
isEnable	boolean	启用状态
effectiveTime	date	生效日期
invalidTime	date	失效日期
eventKey	string	消息标识
oldMemberPostList	array[OrgMemberPostBaseDto]	更新前任职信息
id	int64	任职id
main	boolean	是否主岗
orgId	int64	组织id
postId	int64	岗位id
levelId	int64	职级id
jobId	int64	职务id
sortId	int32	排序号
isEnable	boolean	状态
effectiveTime	date	生效日期，毫秒时间戳
invalidTime	date	失效日期，毫秒时间戳
memberPostList	array[OrgMemberPostBaseDto]	更新后任职信息
id	int64	任职id
main	boolean	是否主岗
orgId	int64	组织id
postId	int64	岗位id
levelId	int64	职级id
jobId	int64	职务id
sortId	int32	排序号
isEnable	boolean	状态
effectiveTime	date	生效日期，毫秒时间戳
invalidTime	date	失效日期，毫秒时间戳

5.10、创建职级

参数名称	参数类型	参数描述
创建职级消息	OrgLevelCreateMessage
levelId	int64	职级id
code	string	职级编号
levelSort	int32	职级序号
isEnable	boolean	状态
eventKey	string	消息标识

---

2 - 三方系统同步至V8

集成模式

2.1 - COP平台开放写入OpenAPI

1、概述

COP平台开放写入OpenAPI，由三方异构系统定时增量推送，完成组织同步模式。

2、优缺点分析

a. 优点：

COP集成压力小；

b. 缺点：

三方系统需要有一定的研发能力，完成接口调用和字段映射；

3、集成配置

序号	步骤名称	责任方	使用场景
1	提供组织增量查询接口规范和文档	致远	必须，包含接口定义、签名规则、字段来源等信息
2	API启用	致远	必须，只有启用的API才可以正常进行授权访问
3	新建接入应用	致远	必须，负责分配AppKey和APPSecret、配置访问授权、访问白名单等配置页
4	启用接入应用	致远	必须，未启用的接入应用，访问时会提示接入应用未启用
5	分配APPKey和APPSecret	致远	必须，接口签名核心字段
6	API授权	致远	必须，只有添加权限的额API接口才可以正常访问
7	导出接口文档	致远	非必须，导出所有已经启用的API手册
8	配置访问限流	致远	非必须，根据服务器资源性能，可以配置指定时间段内调用上线
9	配置访问白名单	致远	非必须，开启后，访问白名单之后的API请求将会被拦截
10	调用测试	三方系统	必须，根据平台提供的接口文档和必须字段，使用postmen等工具直接调用，验证网络连通性和信息准确性

4、接口目录

API分类	API名称	接口描述
组织信息同步（基于编码）	批量新建/更新组织	组织（机构+部门）
职务信息同步（基于编码）	批量新建/更新职务	职务
职级信息同步（基于编码）	批量新建/更新职级	职级
岗位信息同步（基于编码）	批量新建/更新岗位	岗位
人员及任职信息同步（基于编码）	批量新建/更新人员及任职	人员&任职

4.1、接口文档在线查看位置

4.2、接口签名

4.2.1、请求头（Header）

参数名称	是否必填	参数说明
app-key	true	应用的唯一标识，创建接入应用后生成，可在应用基础信息页面获得。 示例：d43b0b442cf34076a2c4af6bb8928afb
sign-type	true	固定值：MD5
sign	true	签名，字符串“AppSecret+请求体的JSON字符串+AppSecret”的MD5值（MD5值忽略大小写） AppSecret，为应用的秘钥，创建接入应用后生成，可在应用基础信息页面获得。 示例：154fa5bc7e294deda68a15559b07c845请求体的JSON字符串， 需要将请求体中的请求参数转换为JSON字符串。
Accept-Language	false	语种：用以设置开放平台OpenAPI运行时上下文的语种参数。 枚举项可选值列表：zh-CN（简体中文）， zh-TW（繁体中文）， en（英文）， 其他枚举项请参照平台语种列表。

4.2.2、签名示例（sign）

String secret = "154fa5bc7e294deda68a15559b07c845";
String body = "{"name": "张三", "age": 35, "company": {"name": "致远", "address": "北京"}";
String sign = Md5(secret + body + secret); // 结果是 01a8795a7fe6dda23aaec40de3d301b7;

5、接口清单

5.1、批量新建/更新组织

请求地址

【接口请求地址前缀】/organization/unit/batch

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		FALSE	string	异步回调URL。如果此参数非空， 表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		TRUE	OrgBatchUnitDto	请求参数数据
units	data	TRUE	array[OrgUnitDataDto]	组织数据
name	units	TRUE	string	组织名称
shortName	units	FALSE	string	组织简称 ，类型为机构时，简称必填，类型为部门时，简称非必填
code	units	TRUE	string	组织编号
type	units	TRUE	enum	组织类型。枚举项可选值列表： NONE（空）， INSTITUTION（机构）， DEPARTMENT（部门）， OUTSIDE_INSTITUTION（外部（编外）单位）， OUTSIDE_DEPARTMENT（外部（编外）部门），
parentCode	units	TRUE	string	父组织Code,根节点不填
effectiveTime	units	FALSE	string	生效日期
invalidTime	units	FALSE	string	失效日期
sortId	units	TRUE	int32	排序号
isEnable	units	FALSE	boolean	状态
description	units	FALSE	string	备注
metadataList	units	FALSE	array[OrgMetadataValueDataDto]	自定义扩展属性数据
k	metadataList	FALSE	string	扩展字段的名称
v	metadataList	FALSE	string	扩展字段的的值
address	units	FALSE	string	地址
officeNumber	units	FALSE	string	电话
tax	units	FALSE	string	税号
bankAccount	units	FALSE	string	银行账号
bank	units	FALSE	string	开户银行
isLegalEntity	units	FALSE	boolean	是否法人实体
socialCreditCode	units	FALSE	string	统一社会信用代码
legalPersonName	units	FALSE	string	法定代表人姓名
legalCertificateNumber	units	FALSE	string	法定代表人身份证号码
legalPhoneNumber	units	FALSE	string	法定代表人手机号号码
createTime	units	FALSE	date	创建时间，毫秒时间戳
updateTime	units	FALSE	date	更新时间，毫秒时间戳
syncChildMetadataValue	data	FALSE	boolean	是否同步下级组织扩展字段值，默认是false

请求参数示例

{
  "data": {
    "syncChildMetadataValue": "false",
    "units": [
      {
        "bankAccount": "",
        "legalPhoneNumber": "",
        "code": "CoolAcademyImport1001",
        "address": "",
        "effectiveTime": "2023-09-01",
        "officeNumber": "",
        "description": "",
        "tax": "",
        "updateTime": {{timestamp}},
        "invalidTime": "2024-12-31",
        "type": "INSTITUTION",
        "socialCreditCode": "",
        "isEnable": "true",
        "legalPersonName": "",
        "bank": "",
        "legalCertificateNumber": "",
        "parentCode": "group",
        "createTime": {{timestamp}},
        "sortId": 10,
        "name": "集成演示Import1001",
        "isLegalEntity": "false",
        "shortName": "集成演示1001"
      }
    ]
  },
  "requestId":1705902274340,
  "notifyUrl": "",
  "timestamp":1705902274340
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			SingleData	批量处理结果
content	data		OrgSyncInfoDto	数据对象
type	content		enum	任务类型。枚举项可选值列表： BATCH_UNITS（批量处理组织数据）， BATCH_POSTS（批量处理岗位数据）， BATCH_MEMBERS（批量处理人员数据）， BATCH_JOBS（批量处理职务数据）， BATCH_LEVELS（批量处理职级数据）， BATCH_MEMBER_POSTS（批量处理任职数据）， BATCH_UNIT_METADATA（批量处理组织扩展字段数据）， BATCH_MEMBER_METADATA（批量处理人员扩展字段数据）， BATCH_NATURAL_MEMBERS（批量处理外部个人用户数据），
status	content		enum	状态。枚举项可选值列表：COMPLETE（完成），
startTime	content		date	开始时间
endTime	content		date	结束时间
totalNum	content		int32	总条数
successNum	content		int32	任务当前执行成功的条数
failNum	content		int32	任务当前执行失败的条数
details	content		array[OrgMessageDto]	详情
line	details		int32	行号
id	details		int64	id
name	details		string	名称
code	details		string	编号
status	details		enum	状态。枚举项可选值列表： SUCCESS（成功）， FAILED（失败）， SKIP（跳过），
messageCode	details		string	错误码
message	details		string	信息
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "content": {
            "validate": true,
            "type": "BATCH_UNITS",
            "status": "COMPLETE",
            "startTime": 1705913688259,
            "endTime": 1705913688492,
            "totalNum": 1,
            "successNum": 1,
            "failNum": 0,
            "details": [
                {
                    "validate": true,
                    "line": 1,
                    "id": "1659577340788737399",
                    "name": "集成演示Import1001",
                    "code": "CoolAcademyImport1001",
                    "status": "SUCCESS",
                    "messageCode": null,
                    "message": "成功"
                }
            ]
        }
    }
}

5.2、批量新建/更新职务

请求地址

【接口请求地址前缀】/organization/job/batch

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		False	string	异步回调URL。如果此参数非空， 表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		TRUE	OrgBatchJobDto	请求参数数据
jobs	data	TRUE	array[OrgJobDataDto]	职务数据
name	jobs	TRUE	string	职务名称
code	jobs	TRUE	string	编号
unitCode	jobs	TRUE	string	所属组织编号
category	jobs	TRUE	enum	职务性质。枚举项可选值列表： NONE（空）， BENCH_MARK（基准岗）， SELF_BUILT（自用岗），
sortId	jobs	TRUE	int32	排序号
isEnable	jobs	TRUE	boolean	启用状态
description	jobs	TRUE	string	备注

请求参数示例

{
  "data": {
    "jobs": [
      {
        "code": "JobWorkor",
        "sortId": 10,
        "unitCode": "CoolAcademyImport1001",
        "name": "干事",
        "description": "",
        "category": "SELF_BUILT",
        "isEnable": "true"
      }
    ]
  },
  "requestId": 1705913739277,
  "notifyUrl": "",
  "timestamp": 1705913739277
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			SingleData	批量处理结果
content	data		OrgSyncInfoDto	数据对象
type	content		enum	任务类型。枚举项可选值列表： BATCH_UNITS（批量处理组织数据）， BATCH_POSTS（批量处理岗位数据）， BATCH_MEMBERS（批量处理人员数据）， BATCH_JOBS（批量处理职务数据）， BATCH_LEVELS（批量处理职级数据）， BATCH_MEMBER_POSTS（批量处理任职数据）， BATCH_UNIT_METADATA（批量处理组织扩展字段数据）， BATCH_MEMBER_METADATA（批量处理人员扩展字段数据）， BATCH_NATURAL_MEMBERS（批量处理外部个人用户数据），
status	content		enum	状态。枚举项可选值列表：COMPLETE（完成），
startTime	content		date	开始时间
endTime	content		date	结束时间
totalNum	content		int32	总条数
successNum	content		int32	任务当前执行成功的条数
failNum	content		int32	任务当前执行失败的条数
details	content		array[OrgMessageDto]	详情
line	details		int32	行号
id	details		int64	id
name	details		string	名称
code	details		string	编号
status	details		enum	状态。枚举项可选值列表： SUCCESS（成功）， FAILED（失败）， SKIP（跳过），
messageCode	details		string	错误码
message	details		string	信息
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "content": {
            "validate": true,
            "type": "BATCH_JOBS",
            "status": "COMPLETE",
            "startTime": 1705913739212,
            "endTime": 1705913739234,
            "totalNum": 1,
            "successNum": 1,
            "failNum": 0,
            "details": [
                {
                    "validate": true,
                    "line": 1,
                    "id": "1660303025123624311",
                    "name": "{\"zh_CN\":\"干事\"}",
                    "code": "JobWorkor",
                    "status": "SUCCESS",
                    "messageCode": "成功",
                    "message": null
                }
            ]
        }
    }
}

5.3、批量新建/更新职级

请求地址

【接口请求地址前缀】/organization/level/batch

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		TRUE	OrgBatchLevelDto	请求参数数据
levels	data	TRUE	array[OrgLevelDataDto]	职级数据
name	levels	TRUE	string	职级名称(必填)
code	levels	TRUE	string	编号(必填)
levelSort	levels	TRUE	int32	序号
isEnable	levels	TRUE	boolean	启用状态
description	levels	TRUE	string	备注

请求参数示例

{
  "data": {
    "levels": [
      {
        "code": "M22",
        "levelSort": 1,
        "name": "M22",
        "description": "M22,酷学院",
        "isEnable": "true"
      }
    ]
  },
  "requestId":1705913759647,
  "notifyUrl": "",
  "timestamp": 1705913759647
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			SingleData	批量处理结果
content	data		OrgSyncInfoDto	数据对象
type	content		enum	任务类型。枚举项可选值列表： BATCH_UNITS（批量处理组织数据）， BATCH_POSTS（批量处理岗位数据）， BATCH_MEMBERS（批量处理人员数据）， BATCH_JOBS（批量处理职务数据）， BATCH_LEVELS（批量处理职级数据）， BATCH_MEMBER_POSTS（批量处理任职数据）， BATCH_UNIT_METADATA（批量处理组织扩展字段数据）， BATCH_MEMBER_METADATA（批量处理人员扩展字段数据）， BATCH_NATURAL_MEMBERS（批量处理外部个人用户数据），
status	content		enum	状态。枚举项可选值列表：COMPLETE（完成），
startTime	content		date	开始时间
endTime	content		date	结束时间
totalNum	content		int32	总条数
successNum	content		int32	任务当前执行成功的条数
failNum	content		int32	任务当前执行失败的条数
details	content		array[OrgMessageDto]	详情
line	details		int32	行号
id	details		int64	id
name	details		string	名称
code	details		string	编号
status	details		enum	状态。枚举项可选值列表： SUCCESS（成功）， FAILED（失败）， SKIP（跳过），
messageCode	details		string	错误码
message	details		string	信息
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "content": {
            "validate": true,
            "type": "BATCH_JOBS",
            "status": "COMPLETE",
            "startTime": 1705913759662,
            "endTime": 1705913759700,
            "totalNum": 1,
            "successNum": 1,
            "failNum": 0,
            "details": [
                {
                    "validate": true,
                    "line": 1,
                    "id": "1660303424790463863",
                    "name": "{\"zh_CN\":\"M22\"}",
                    "code": "M22",
                    "status": "SUCCESS",
                    "messageCode": "成功",
                    "message": null
                }
            ]
        }
    }
}

5.4、批量新建/更新岗位

请求地址

【接口请求地址前缀】/organization/post/batch

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		TRUE	OrgBatchPostDto	请求参数数据
posts	data	TRUE	array[OrgPostDataDto]	岗位数据
name	posts	TRUE	string	岗位名称
code	posts	TRUE	string	编号
type	posts	TRUE	string	岗位分类的枚举code值
unitCode	posts	TRUE	string	所属组织编号
category	posts	TRUE	enum	岗位性质。枚举项可选值列表： NONE（空）， BENCH_MARK（基准岗）， SELF_BUILT（自用岗），
sortId	posts	TRUE	int32	排序号
isEnable	posts	TRUE	boolean	启用状态
description	posts	TRUE	string	备注

请求参数示例

{
  "data": {
    "posts": [
      {
        "code": "salesEngineer",
        "sortId": 10,
        "unitCode": "CoolAcademyImport1001",
        "name": "销售工程师",
        "description": "",
        "type": "Management",
        "category": "SELF_BUILT",
        "isEnable": "true"
      }
    ]
  },
  "requestId": 1705913779906,
  "notifyUrl": "",
  "timestamp": 1705913779906
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			SingleData	批量处理结果
content	data		OrgSyncInfoDto	数据对象
type	content		enum	任务类型。枚举项可选值列表： BATCH_UNITS（批量处理组织数据）， BATCH_POSTS（批量处理岗位数据）， BATCH_MEMBERS（批量处理人员数据）， BATCH_JOBS（批量处理职务数据）， BATCH_LEVELS（批量处理职级数据）， BATCH_MEMBER_POSTS（批量处理任职数据）， BATCH_UNIT_METADATA（批量处理组织扩展字段数据）， BATCH_MEMBER_METADATA（批量处理人员扩展字段数据）， BATCH_NATURAL_MEMBERS（批量处理外部个人用户数据），
status	content		enum	状态。枚举项可选值列表：COMPLETE（完成），
startTime	content		date	开始时间
endTime	content		date	结束时间
totalNum	content		int32	总条数
successNum	content		int32	任务当前执行成功的条数
failNum	content		int32	任务当前执行失败的条数
details	content		array[OrgMessageDto]	详情
line	details		int32	行号
id	details		int64	id
name	details		string	名称
code	details		string	编号
status	details		enum	状态。枚举项可选值列表： SUCCESS（成功）， FAILED（失败）， SKIP（跳过），
messageCode	details		string	错误码
message	details		string	信息
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": {
        "content": {
            "validate": true,
            "type": "BATCH_POSTS",
            "status": "COMPLETE",
            "startTime": 1705913779967,
            "endTime": 1705913780058,
            "totalNum": 1,
            "successNum": 0,
            "failNum": 1,
            "details": [
                {
                    "validate": true,
                    "line": 1,
                    "id": "1660309690828981623",
                    "name": "{\"zh_CN\":\"销售工程师\"}",
                    "code": "salesEngineer",
                    "status": "FAILED",
                    "messageCode": "ORG_0102",
                    "message": "岗位分类枚举值不存在!"
                }
            ]
        }
    }
}

5.5、批量新建/更新人员及任职

请求地址

【接口请求地址前缀】/organization/member/batch

请求方式

POST

请求参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
requestId		TRUE	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		TRUE	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		TRUE	OrgBatchMemberDto	请求参数数据
members	data	TRUE	array[OrgMemberDataDto]	人员数据
thirdId	members	TRUE	string	第三方唯一标识
name	members	TRUE	string	姓名
code	members	TRUE	string	编号
username	members	TRUE	string	用户名
gender	members	TRUE	enum	性别。枚举项可选值列表： NONE（空）， MALE（男）， FEMALE（女）， UN_KNOW（未知），
birthday	members	TRUE	string	出生日期
phoneNumber	members	TRUE	string	手机号码
officeNumber	members	TRUE	string	工作电话
email	members	TRUE	string	邮箱
effectiveTime	members	TRUE	string	生效日期
invalidTime	members	TRUE	string	失效日期
sortId	members	TRUE	int32	排序号
isEnable	members	TRUE	boolean	状态
description	members	TRUE	string	备注
memberPosts	members	TRUE	array[OrgMemberPostDataDto]	人员的任职信息
main	memberPosts	TRUE	boolean	是否主岗
unitCode	memberPosts	TRUE	string	组织编码
postCode	memberPosts	TRUE	string	岗位编码(内部人员必填)
levelCode	memberPosts	TRUE	string	职级编码
jobCode	memberPosts	TRUE	string	职务编码
effectiveTime	memberPosts	TRUE	string	生效日期
invalidTime	memberPosts	TRUE	string	失效日期
sortId	memberPosts	TRUE	int32	排序号
topSortId	memberPosts	TRUE	int32	优先置顶排序
isEnable	memberPosts	TRUE	boolean	状态
memberType	memberPosts	TRUE	enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
metadataList	members	TRUE	array[OrgMetadataValueDataDto]	自定义扩展属性数据
k	metadataList	TRUE	string	扩展字段的名称
v	metadataList	TRUE	string	扩展字段的的值
certificateType	members	TRUE	string	证件类型
certificateNumber	members	TRUE	string	证件号码
entryDate	members	TRUE	string	入职日期
bankAccount	members	TRUE	string	银行账号
bank	members	TRUE	string	开户银行
bankOutlets	members	TRUE	string	开户网点
image	members	TRUE	string	头像路径
memberType	members	TRUE	enum	人员类型。枚举项可选值列表： NONE（空）， MEMBER（内部人员）， OUTSIDE_MEMBER（外部单位用户）， NATURAL_MEMBER（外部个人用户），
createTime	members	TRUE	date	创建时间，毫秒时间戳
updateTime	members	TRUE	date	更新时间，毫秒时间戳

请求参数示例

{
  "data": [
      {
        "birthday": "",
        "code": "KXY1081001",
        "gender": "MALE",
        "bankOutlets": "",
        "effectiveTime": "2023-09-01",
        "officeNumber": "",
        "description": "",
        "invalidTime": "2024-12-31",
        "isEnable": "true",
        "bank": "",
        "sortId": 10,
        "email": "",
        "bankAccount": "",
        "image": "",
        "thirdId": "KXY1081001",
        "entryDate": "2023-09-01",
        "updateTime": 1705913802791,
        "memberPosts": [
          {
            "levelCode": "M22",
            "effectiveTime": "2023-09-01",
            "sortId": 10,
            "unitCode": "InformationCenter",
            "jobCode": "JobWorkor",
            "main": "true",
            "postCode": "salesEngineer",
            "invalidTime": "2024-12-31",
            "memberType": "MEMBER",
            "isEnable": "true"
          }
        ],
        "phoneNumber": "18701021001",
        "certificateNumber": "",
        "createTime": 1705913802791,
        "name": "集成演示-张三",
        "memberType": "MEMBER",
        "username": "18701021001",
        "certificateType": "idCard"
      }
    ]
  ,
  "requestId": 1705913802791,
  "notifyUrl": "",
  "timestamp": 1705913802791
}

响应参数（Body）

参数名称	父节点	是否必填	参数类型	参数描述
data			SingleData	批量处理结果
content	data		OrgSyncInfoDto	数据对象
type	content		enum	任务类型。枚举项可选值列表： BATCH_UNITS（批量处理组织数据）， BATCH_POSTS（批量处理岗位数据）， BATCH_MEMBERS（批量处理人员数据）， BATCH_JOBS（批量处理职务数据）， BATCH_LEVELS（批量处理职级数据）， BATCH_MEMBER_POSTS（批量处理任职数据）， BATCH_UNIT_METADATA（批量处理组织扩展字段数据）， BATCH_MEMBER_METADATA（批量处理人员扩展字段数据）， BATCH_NATURAL_MEMBERS（批量处理外部个人用户数据），
status	content		enum	状态。枚举项可选值列表：COMPLETE（完成），
startTime	content		date	开始时间
endTime	content		date	结束时间
totalNum	content		int32	总条数
successNum	content		int32	任务当前执行成功的条数
failNum	content		int32	任务当前执行失败的条数
details	content		array[OrgMessageDto]	详情
line	details		int32	行号
id	details		int64	id
name	details		string	名称
code	details		string	编号
status	details		enum	状态。枚举项可选值列表： SUCCESS（成功）， FAILED（失败）， SKIP（跳过），
messageCode	details		string	错误码
message	details		string	信息
status			int32	状态
code			string	错误码
message			string	返回信息

响应参数示例

{
  "code": "200",
  "data": {
    "content": {
      "failNum": 1,
      "totalNum": 100,
      "successNum": 99,
      "startTime": "",
      "details": [
        {
          "code": "",
          "line": 10,
          "name": "",
          "messageCode": "",
          "id": "10828711522402302",
          "message": "SUCCESS",
          "status": ""
        }
      ],
      "endTime": "",
      "type": "BATCH_MEMBERS",
      "status": "READY"
    }
  },
  "message": "成功",
  "status": "FRONT"
}

5、注意事项

接口授权和分配AppKey、AppSecret请参考【数据开放】操作步骤

2.2 - 数据库中间表（推荐）

1、概述

针对三方异构系统与COP组织人员数据结构差异较大场景，COP开放数据库中间表，三方异构系统按要求将组织数据写入中间表后，COP重新组装后完成组织同步模式。

2、优缺点

a. 优点

i. 集成压力小；

ii. 对数据质量要求低；

ⅲ.问题跟踪，问题定位速度快

b. 缺点

i. 无

3、操作步骤

3.1、开放OpenAPI模式（推荐）

序号	步骤名称	责任方	使用场景
1	开放OpenAPI	致远	必须，提供组织数据写入OpenAPI和调用示例
2	新建集成应用，获取集成应用ID	致远	必须，获取集成应用ID，接口必须入参
3	启用API	致远	必须，只有启用API，才能分配授权
4	新建接入应用	致远	必须，分配授权APPKey和AppSecret
5	查看AppKey和AppSecret	致远	必须，接口鉴权使用
6	API授权	致远	必须，未启用时，接口调用直接报错
7	启用接入应用	致远	必须，未启用时，接口调用直接报错
8	选择同步模式	致远	必须，选择中间表模式
9	配置同步周期	致远	必须，配置数据处理周期
10	配置字段映射	致远	必须，字段映射、默认值、过滤条件等
11	调用接口写入数据	三方异构系统	必须，三方异构系统负责写入数据到中间表
12	查看日志	致远	非必须，监控过程数据

3.2、直接写入数据库模式

序号	步骤名称	责任方	使用场景
1	提供数据库连接信息和库表结构	致远	必须，
2	新建集成应用，获取集成应用ID	致远	必须，获取集成应用ID，接口必须入参
3	选择同步模式	致远	必须，选择中间表模式
4	配置同步周期	致远	必须，配置数据处理周期
5	配置字段映射	致远	必须，字段映射、默认值、过滤条件等
6	连接数据库写入数据	三方异构系统	必须，三方异构系统负责写入数据到中间表
7	查看日志	致远	非必须，监控过程数据

4、集成配置步骤

4.1、开放OpenAPI模式（推荐）

4.1.1、开放OpenAPI

参照接口清单

4.1.2、新建集成应用，获取集成应用ID

4.1.3、启用API

4.1.4、新建接入应用

4.1.5、查看AppKey和AppSecret

4.1.6、API授权

4.1.7、启用接入应用

4.1.8、选择同步模式

4.1.9、内容配置

4.1.10、配置同步周期

4.1.11、调用接口写入数据

参考接口清单调用接口处理

4.1.12、查看日志

4.2、直接写入数据库模式

4.2.1、提供数据库连接信息和库表结构

请参照物理表接口定义

4.2.2、新建集成应用，获取集成应用ID

4.2.3、选择同步模式

4.2.4、配置同步内容

4.2.5、配置同步周期

5、接口清单

4.1、接口鉴权

4.1.1、请求头（Header）

参数名称	是否必填	参数说明
app-key	true	应用的唯一标识，创建接入应用后生成，可在应用基础信息页面获得。 示例：d43b0b442cf34076a2c4af6bb8928afb
sign-type	true	固定值：MD5
sign	true	签名，字符串“AppSecret+请求体的JSON字符串+AppSecret”的MD5值（MD5值忽略大小写） AppSecret，为应用的秘钥，创建接入应用后生成，可在应用基础信息页面获得。 示例：154fa5bc7e294deda68a15559b07c845请求体的JSON字符串， 需要将请求体中的请求参数转换为JSON字符串。
Accept-Language	false	语种：用以设置开放平台OpenAPI运行时上下文的语种参数。 枚举项可选值列表：zh-CN（简体中文）， zh-TW（繁体中文）， en（英文）， 其他枚举项请参照平台语种列表。

4.1.2、签名示例（sign）

String secret = "154fa5bc7e294deda68a15559b07c845";
String body = "{"name": "张三", "age": 35, "company": {"name": "致远", "address": "北京"}";
String sign = Md5(secret + body + secret); // 结果是 01a8795a7fe6dda23aaec40de3d301b7;

4.2、批量插入组织中间表（机构/部门）

请求地址：

【接口请求地址前缀】/cip-connector/middle-table/unit-create

请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	UnitInfoReqDto	请求参数数据
linkerId	data	true	int64	集成应用ID
data	data	true	array[UnitInfoDto]	数据列表
code	data	true	string	编码
name	data	true	string	组织名称
parentCode	data	true	string	父组织code
shortName	data	false	string	简称
type	data	false	enum	类型。枚举项可选值列表： INSTITUTION（机构）， DEPARTMENT（部门），
thirdId	data	false	string	第三方组织id
enable	data	false	boolean	是否启用
thirdUpdateTime	data	true	date	第三方数据最新时间
sortId	data	false	int32	排序号
str1	data	false	string	扩展字段1
str2	data	false	string	扩展字段2
str3	data	false	string	扩展字段3
str4	data	false	string	扩展字段4
str5	data	false	string	扩展字段5
str6	data	false	string	扩展字段6
str7	data	false	string	扩展字段7
str8	data	false	string	扩展字段8
str9	data	false	string	扩展字段9
str10	data	false	string	扩展字段10

请求示例

{
  "data": {
    "data": [
      {
        "code": "100101",
        "thirdId": "100101",
        "type": "INSTITUTION",
        "str7": "",
        "str8": "",
        "str5": "",
        "str6": "",
        "str3": "",
        "parentCode": "group",
        "str4": "",
        "enable": "true",
        "sortId": 1,
        "str1": "",
        "str2": "",
        "name": "API导入致远",
        "str10": "",
        "shortName": "API导入致远",
        "thirdUpdateTime": "2024-01-01",
        "str9": ""
      }
    ],
    "linkerId": "-4511464491497948501"
  },
  "requestId": "3799345662156838701",
  "notifyUrl": "",
  "timestamp": 1720592508046
}

返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	void	数据对象
status		int32	状态
code		string	错误码
message		string	返回信息

返回示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": null
}

4.3、批量插入岗位中间表

请求地址：

【接口请求地址前缀】/cip-connector/middle-table/post-create

请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	PostInfoReqDto	请求参数数据
linkerId	data	true	int64	集成应用ID
data	data	true	array[PostInfoDto]	数据列表
code	data	true	string	编码
name	data	true	string	名称
unitCode	data	true	string	组织code
thirdId	data	false	string	第三方id
type	data	false	string	岗位分类枚举值code
category	data	false	enum	岗位性质。枚举项可选值列表： NONE（空）， BENCH_MARK（基准岗）， SELF_BUILT（自用岗），
enable	data	false	boolean	是否启用
thirdUpdateTime	data	true	date	第三方数据最新时间
sortId	data	false	int32	排序号

请求示例

{
  "data": {
    "data": [
      {
        "code": "001",
        "thirdId": "12345",
        "enable": "true",
        "sortId": 1,
        "unitCode": "100101",
        "name": "P0",
        "type": "1",
        "category": "BENCH_MARK",
        "thirdUpdateTime": "2024-01-01"
      }
    ],
    "linkerId": "-4511464491497948501"
  },
  "requestId": "-4579930924623847185",
  "notifyUrl": "",
  "timestamp": 1720592507597
}

返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	void	数据对象
status		int32	状态
code		string	错误码
message		string	返回信息

返回示例

{
    "status": 0,
    "code": "BOOT_0000",
    "message": "SUCCESS",
    "data": null
}

4.4、批量插入职级中间表

请求地址：

【接口请求地址前缀】/cip-connector/middle-table/level-create

请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	LevelInfoReqDto	请求参数数据
linkerId	data	true	int64	集成应用ID
data	data	true	array[LevelInfoDto]	数据列表
code	data	true	string	编码
name	data	true	string	名称
thirdId	data	false	string	第三方id
enable	data	false	boolean	是否启用
thirdUpdateTime	data	true	date	第三方数据最新时间
sortId	data	false	int32	排序号(默认：1)

请求示例

{
  "data": {
    "data": [
      {
        "code": "001",
        "thirdId": "12345",
        "enable": "true",
        "sortId": 1,
        "name": "P0",
        "thirdUpdateTime": "2024-01-01"
      }
    ],
    "linkerId": "158933225308768072"
  },
  "requestId": "-395422794033167315",
  "notifyUrl": "",
  "timestamp": 1720592508081
}

返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	void	数据对象
status		int32	状态
code		string	错误码
message		string	返回信息

返回示例

{
  "code": "200",
  "data": {
    "content": ""
  },
  "message": "成功",
  "status": "FRONT"
}

4.5、批量插入人员中间表

请求地址：

【接口请求地址前缀】/cip-connector/middle-table/member-create

请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	MemberInfoReqDto	请求参数数据
linkerId	data	true	int64	集成应用ID
data	data	true	array[MemberInfoDto]	数据列表
code	data	true	string	编码
name	data	true	string	名称
thirdId	data	false	string	第三方id
email	data	false	string	邮箱
phoneNumber	data	false	string	手机
gender	data	false	enum	性别。枚举项可选值列表： NONE（空）， MALE（男）， FEMALE（女）， UN_KNOW（未知），
unitCode	data	true	string	组织code
thirdJobId	data	false	string	第三方任职id
main	data	false	boolean	是否主岗
postCode	data	false	string	岗位code
levelCode	data	false	string	职级code
effectiveTime	data	false	date	生效日期
invalidTime	data	false	date	失效日期
enable	data	true	boolean	是否启用
thirdUpdateTime	data	true	date	第三方数据最新时间
sortId	data	false	int32	排序号(默认：1)
str1	data	false	string	扩展字段1
str2	data	false	string	扩展字段2
str3	data	false	string	扩展字段3
str4	data	false	string	扩展字段4
str5	data	false	string	扩展字段5
str6	data	false	string	扩展字段6
str7	data	false	string	扩展字段7
str8	data	false	string	扩展字段8
str9	data	false	string	扩展字段9
str10	data	false	string	扩展字段10

请求示例

{
  "data": {
    "data": [
      {
        "code": "001",
        "gender": "MALE",
        "effectiveTime": "2023-12-31 00:00:00",
        "main": "true",
        "invalidTime": "9999-12-31 00:00:00",
        "str7": "aaa",
        "levelCode": "001",
        "str8": "aaa",
        "str5": "aaa",
        "str6": "aaa",
        "str3": "aaa",
        "str4": "aaa",
        "enable": "true",
        "sortId": 1,
        "str1": "aaa",
        "unitCode": "seeyon",
        "str2": "aaa",
        "str10": "aaa",
        "email": "pan@163.com",
        "thirdUpdateTime": "2024-01-01",
        "str9": "aaa",
        "thirdId": "12345",
        "thirdJobId": "12345456",
        "phoneNumber": "1345668900",
        "name": "P0",
        "postCode": "defaultCode"
      }
    ],
    "linkerId": "158933225308768072"
  },
  "requestId": "1121213206799116311",
  "notifyUrl": "",
  "timestamp": 1720592507997
}

返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	void	数据对象
status		int32	状态
code		string	错误码
message		string	返回信息

返回示例

{
  "code": "200",
  "data": {
    "content": ""
  },
  "message": "成功",
  "status": "FRONT"
}

4.6、确认全量同步完毕（必须）

说明：

全量模式下，每次全量数据写入中间表后，必须调用当前接口，否则即使满足集成平台配置的定时执行时间，也不会执行同步

请求地址：

【接口请求地址前缀】/cip-connector/middle-table/sync-finish

请求参数

参数名称	父节点	是否必填	参数类型	参数描述
requestId		true	string	请求流水号。同一接入应用下的流水号不要重复； 最长32位，超过部分会被截断。
timestamp		true	int64	请求时间戳。请求时间和服务器时间不能相差过大， 默认5分钟以内。
notifyUrl		false	string	异步回调URL。如果此参数非空，表示使用异步方式调用开放API， 执行结果将通过此URL异步通知调用者。
data		true	int64	集成应用ID

请求示例

{
  "data": "-4511464491497948501",
  "requestId": "-4875171919230719752",
  "notifyUrl": "",
  "timestamp": 1720592508031
}

返回参数

参数名称	父节点	参数类型	参数描述
data		SingleData	返回值数据
content	data	string	数据对象
status		int32	状态
code		string	错误码
message		string	返回信息

返回示例

{
  "code": "200",
  "data": {
    "content": ""
  },
  "message": "成功",
  "status": "FRONT"
}

6、物理表结构

注意：库名称：cip-connector

6.1、机构/部门

CREATE TABLE `cip_sync_unit` (
  `id` bigint(20) NOT NULL COMMENT '主键',
  `tenant_id` bigint(20) NOT NULL COMMENT '租户ID',
  `create_time` datetime NOT NULL COMMENT '创建时间',
  `update_time` datetime NOT NULL COMMENT '修改时间',
  `version` smallint(6) NOT NULL COMMENT '版本号',
  `linker_id` bigint(20) NOT NULL COMMENT '连接器ID',
  `code` varchar(100) DEFAULT NULL COMMENT '组织编号',
  `name` varchar(255) DEFAULT NULL COMMENT '组织名称',
  `short_name` varchar(255)  DEFAULT NULL COMMENT '简称',
  `type` smallint  NOT NULL COMMENT '类型(机构=1，部门=2)',
  `parent_code` varchar(100)  DEFAULT NULL COMMENT '父组织code',
  `third_id` varchar(100) DEFAULT NULL COMMENT '组织id',
  `is_enable` tinyint(1)  NOT NULL COMMENT '是否启用(1-启用，0-停用)',
  `third_update_time` datetime NOT NULL COMMENT '第三方数据最新时间',
  `status` smallint  NOT NULL DEFAULT 0 COMMENT '同步状态(不处理=-1，未处理=0，失败=1，成功=2)',
  `retry` smallint NOT NULL DEFAULT 0 COMMENT '重试次数',
  `batch` varchar(20) DEFAULT NULL COMMENT '批次号',
  `sort_id` int(11) NOT NULL DEFAULT 1 COMMENT '排序号',
  `v8_id` bigint(20) NOT NULL DEFAULT -1 COMMENT 'V8ID',
  `str1` varchar(255)  DEFAULT NULL COMMENT '扩展字段1',
  `str2` varchar(255)  DEFAULT NULL COMMENT '扩展字段2',
  `str3` varchar(255)  DEFAULT NULL COMMENT '扩展字段3',
  `str4` varchar(255)  DEFAULT NULL COMMENT '扩展字段4',
  `str5` varchar(255)  DEFAULT NULL COMMENT '扩展字段5',
  `str6` varchar(255)  DEFAULT NULL COMMENT '扩展字段6',
  `str7` varchar(255)  DEFAULT NULL COMMENT '扩展字段7',
  `str8` varchar(255)  DEFAULT NULL COMMENT '扩展字段8',
  `str9` varchar(255)  DEFAULT NULL COMMENT '扩展字段9',
  `str10` varchar(255)  DEFAULT NULL COMMENT '扩展字段10',
  `msg` longtext  DEFAULT NULL COMMENT '异常信息',
  PRIMARY KEY (`id`)
) COMMENT='组织同步组织中间表';

6.2、职级

CREATE TABLE `cip_sync_level` (
  `id` bigint(20) NOT NULL COMMENT '主键',
  `tenant_id` bigint(20) NOT NULL COMMENT '租户ID',
  `create_time` datetime NOT NULL COMMENT '创建时间',
  `update_time` datetime NOT NULL COMMENT '修改时间',
  `version` smallint(6) NOT NULL COMMENT '版本号',
  `linker_id` bigint(20) NOT NULL COMMENT '连接器ID',
  `code` varchar(50) DEFAULT NULL COMMENT '职级编号',
  `name` varchar(100) DEFAULT NULL COMMENT '职级名称',
  `third_id` varchar(100) DEFAULT NULL COMMENT '职级id',
  `is_enable` tinyint(1)  NOT NULL COMMENT '是否启用(1-启用，0-停用)',
  `third_update_time` datetime NOT NULL COMMENT '第三方数据最新时间',
  `status` smallint NOT NULL DEFAULT 0 COMMENT '同步状态(不处理=-1，未处理=0，失败=1，成功=2)',
  `retry` smallint NOT NULL DEFAULT 0 COMMENT '重试次数',
  `batch` varchar(20) DEFAULT NULL COMMENT '批次号',
  `sort_id` int(11) NOT NULL DEFAULT 1 COMMENT '排序号',
  `v8_id` bigint(20) NOT NULL DEFAULT -1 COMMENT 'V8ID',
  `msg` longtext  DEFAULT NULL COMMENT '异常信息',
  PRIMARY KEY (`id`)
) COMMENT='组织同步职级中间表';

6.3、岗位

CREATE TABLE `cip_sync_post` (
  `id` bigint(20) NOT NULL COMMENT '主键',
  `tenant_id` bigint(20) NOT NULL COMMENT '租户ID',
  `create_time` datetime NOT NULL COMMENT '创建时间',
  `update_time` datetime NOT NULL COMMENT '修改时间',
  `version` smallint(6) NOT NULL COMMENT '版本号',
  `linker_id` bigint(20) NOT NULL COMMENT '连接器ID',
  `code` varchar(50) DEFAULT NULL COMMENT '岗位编号',
  `name` varchar(100) DEFAULT NULL COMMENT '岗位名称',
  `unit_code` varchar(100) DEFAULT NULL COMMENT '组织code',
  `type` varchar(100) DEFAULT NULL COMMENT '岗位分类枚举值code',
  `category` smallint NOT NULL DEFAULT 0 COMMENT '岗位性质(基准岗=0，自用岗=1)',
  `third_id` varchar(100) DEFAULT NULL COMMENT '岗位id',
  `is_enable` tinyint(1)  NOT NULL COMMENT '是否启用(1-启用，0-停用)',
  `third_update_time` datetime NOT NULL COMMENT '第三方数据最新时间',
  `status` smallint NOT NULL DEFAULT 0 COMMENT '同步状态(不处理=-1，未处理=0，失败=1，成功=2)',
  `retry` smallint NOT NULL DEFAULT 0 COMMENT '重试次数',
  `batch` varchar(20) DEFAULT NULL COMMENT '批次号',
  `sort_id` int(11) NOT NULL DEFAULT 1 COMMENT '排序号',
  `v8_id` bigint(20) NOT NULL DEFAULT -1 COMMENT 'V8ID',
  `msg` longtext  DEFAULT NULL COMMENT '异常信息',
  PRIMARY KEY (`id`)
) COMMENT='组织同步岗位中间表';

6.4、人员&任职

CREATE TABLE `cip_sync_member` (
  `id` bigint(20) NOT NULL COMMENT '主键',
  `tenant_id` bigint(20) NOT NULL COMMENT '租户ID',
  `create_time` datetime NOT NULL COMMENT '创建时间',
  `update_time` datetime NOT NULL COMMENT '修改时间',
  `version` smallint(6) NOT NULL COMMENT '版本号',
  `linker_id` bigint(20) NOT NULL COMMENT '连接器ID',
  `code` varchar(50) DEFAULT NULL COMMENT '工号',
  `name` varchar(50) DEFAULT NULL COMMENT '姓名',
  `third_id` varchar(100) DEFAULT NULL COMMENT '第三方人员id',
  `gender` smallint NOT NULL DEFAULT 0 COMMENT '性别(男=0，女=1)',
  `email` varchar(255) DEFAULT NULL COMMENT '邮箱',
  `phone_number` varchar(20) DEFAULT NULL COMMENT '手机号码',
  `unit_code` varchar(100) DEFAULT NULL COMMENT '组织code',
  `third_job_id` varchar(100) DEFAULT NULL COMMENT '第三方任职id',
  `is_main` tinyint(1) NOT NULL DEFAULT '1' COMMENT '是否主岗(主岗=1，副岗=0)',
  `post_code` varchar(50) DEFAULT NULL COMMENT '岗位code',
  `level_code` varchar(50) DEFAULT NULL COMMENT '职级code',
  `effective_time` datetime NOT NULL DEFAULT '2024-01-01' COMMENT '生效日期',
  `invalid_time` datetime NOT NULL DEFAULT '9998-12-31' COMMENT '失效日期',
  `is_enable` tinyint(1)  NOT NULL COMMENT '是否启用(1-启用，0-停用)',
  `third_update_time` datetime NOT NULL COMMENT '第三方数据最新时间',
  `status` smallint NOT NULL DEFAULT 0 COMMENT '同步状态(不处理=-1，未处理=0，失败=1，成功=2)',
  `retry` smallint NOT NULL DEFAULT 0 COMMENT '重试次数',
  `batch` varchar(20) DEFAULT NULL COMMENT '批次号',
  `sort_id` int(11) NOT NULL DEFAULT 1 COMMENT '排序号',
  `v8_id` bigint(20) NOT NULL DEFAULT -1 COMMENT 'V8ID',
  `str1` varchar(255)  DEFAULT NULL COMMENT '扩展字段1',
  `str2` varchar(255)  DEFAULT NULL COMMENT '扩展字段2',
  `str3` varchar(255)  DEFAULT NULL COMMENT '扩展字段3',
  `str4` varchar(255)  DEFAULT NULL COMMENT '扩展字段4',
  `str5` varchar(255)  DEFAULT NULL COMMENT '扩展字段5',
  `str6` varchar(255)  DEFAULT NULL COMMENT '扩展字段6',
  `str7` varchar(255)  DEFAULT NULL COMMENT '扩展字段7',
  `str8` varchar(255)  DEFAULT NULL COMMENT '扩展字段8',
  `str9` varchar(255)  DEFAULT NULL COMMENT '扩展字段9',
  `str10` varchar(255)  DEFAULT NULL COMMENT '扩展字段10',
  `msg` longtext  DEFAULT NULL COMMENT '异常信息',
  PRIMARY KEY (`id`)
) COMMENT='组织同步人员中间表';

7、注意事项

7.1、更新标识【重重重】

选择OpenAPI模式时，为了防止同一批次数据全部写入前，定时处理任务开始执行，造成数据不完整，请务必再同一批次数据写入完成后调用【全量同步完毕】接口，更新批次同步完成标识。

7.2、扩展字段定义

7.3、集成应用ID

7.4、开放OpenAPI

如需要限制访问IP、限流控制等高级设计，请参考集成开发-开放平台-接入应用配置说明

7.5、手工同步

如果同步频率配置的为手工同步，请在调用OpenAPI写入数据，调用【全部同步完毕】接口后，手工点击执行同步，否则数据不会再日志表中执行同步。

---

2.3 - 第三方同步到V8常见问题

1、拉取方式

适合全量 从上到下依次进行。第一遍，要单个逐次手动同步。组织同步标识都是作为v8的code进行同步的。 拉取有一定的制约性，比如人员接口入参是机构id，如果前面机构同步，用code做标识，那么后面循环拉取就获取不到人员信息。

1.1、常见问题

1、任职→查询底表是否已经有该人员→调用组织模型接口 任职数据，需先同步人员基本信息，如果手动系统录入人员，目前任职无法通过连接器进入系统。 2、如果组织的扩展字段是人员，那么还需同步第二遍。 3、拉取接口变化成分页，因为业务路径会变化，所有配置项需要重新选一遍。 4、内部根节点，外部根节点如果选错同步后，因为组织模型目前不支持跨单位调整部门，所以需要手动进行维护，或者找组织模型部门人员，清空数据库重新同步。 5、如果是导入的连接器，要核实一下所有页签的业务路径和参数。 6、偶尔有表达式感觉不生效的情况，重新清空保存然后再选一遍重试。 7、如果日志中，接口中有日志，但是组织同步页签没有日志，那么应该后台报错了，需要取服务器日志（cip-connector）进一步分析。 搜索关键字为:执行组织同步任务项。 常见的一种情况是机构授权数不够，无法新建机构，这个找商务进行license授权 8、组织同步日志表，如果量大也可以手动清理。 cip-connector库： select * from cip_p_sync_his where plugin_id=(select id from cip_p_plugin_info where connector_id={连接器id}) and data_type in(0,1,2,3,4,5,6,7); 其中：data_type: 0=组织（单位+部门）基本信息，1=组织（单位+部门）扩展信息，2=岗位信息，3=职务信息，4=职级信息，5=人员基本信息，6=人员扩展信息，7=人员任职信息

2、第三方推送

2.1、事件订阅和消息队列

事件订阅：监听第三方回调事件 消息队列：监听mq 因为组织模型的关联性和异步性，可以作为中间的一种技术手段，不建议作为直接交付使用。

2.2、中间表

支持全量/增量。支持重试。暂不支持自动创建用户映射。一般需第三方开发或者结合微流程开发使用。 可以直接将数据直插数据库表，也可以通过openapi进行插入。 全量模式： 1、如果第三方只给最新的启用的组织，停用数据不给，那么会比较v8数据，自动进行停用。 2、需要同步完全部数据后，再给予一个同步完成标识。 增量模式： 按照[第三方数据最新时间]比对出最新数据，定时同步。每次同步为一个批次。 【写入02】任职变化时，写入用户的全部任职，与【写入01】只能二选一，这个意思是人员增量，但是对应的任职必须是该人全部的。如果人员第一次同步任职有两条任职，第二次同步有一条新增任职，目前因为没有组织模型没有记录任职唯一标识，无法判断第二次任职是新增还是更新已有的某个岗位。