# 数据同步

# 一、数据同步整体介绍

# 1、请求方式

接口支持http请求,目前仅支持get以及post两种方式的请求

以当前主流的axios为例,说明当前的接口支持类型情况

TYPE	Content-Type	SupportOrNot
GET		支持
post	application/x-www-form-urlencoded	支持
post	application/json	不支持
post	multipart/form-data	支持

请求的参数中必须有

字段	说明
appCode	应用的编码
appSecret	应用的秘钥

注意:应用编码及秘钥在应用模块创建应用之后,在认证模块中可以获取

# 2、数据同步流程

# 2.1 数据同步-总体流程简述

①获取同步数据编码（业务系统提供一个通知接口，当平台推送数据后会调用通知接口通知业务系统来获取同步数据）

②对数据编码进行存储

③通过数据编码获取同步数据

④对同步数据进行存储

⑤将存储的结果状态反馈给平台

流程图如下:

# 2.2 数据同步-业务系统方流程简述:

① 平台推送数据，调用接口通知对应业务系统

② 业务系统收到通知后调用dataSyncRequest获取同步数据编码（dataCode），并存储

③ 遍历本次请求获取到的同步数据编码（dataCode），调用querySyncDataInfo按次序根据dataCode获取同步数据

④ 处理获取到的同步数据

⑤ 调用feedbackRequest向平台反馈当前dataCode数据的同步情况

⑥ 是否还有未处理的dataCode，有则重复③、④、⑤步骤同步下一条数据，无则结束同步

流程图如下:

# 3、组织机构同步字段

序号	字段	说明	类型	长度
1	id	组织机构id，作为平台和业务系统数据对应关系的唯一值，请妥善保存,或者当做业务系统id使用	string	32
2	orgCname	机构的中文名称	string	200
3	orgShortCname	机构的中文简称	string	200
4	orgCode	机构的code	string	50
5	purpose	机构的类型(1为机构 2为部门)	string	1
6	deptType	当机构是部门时候该字段生效,内容为部门类型例如:信访部门,审理部门等等,可能存在一个部门有多个部门类型的情况	string	200
7	organType	当机构为机构时候,该字段生效,内容为机构类型例如:派驻机构,纪检监察机关等	string	200
8	validFlag	是否有效(0无效 1有效)	string	1
9	organOrder	组织机构排序	double
10	isParent	是否是父节点( 0否 1是)	string	1
11	parentOrgId	父节点id	string	32
12	validDate	有效结束日期(没有值表示长期有效,格式为yyyy-MM-dd)	string	date

# 4、人员账号同步字段

序号	字段	说明	类型	长度
1	innerCode	作为平台和业务系统数据对应关系的唯一值,请妥善保存	string	32
2	orgId	所属单位ID	string	32
3	orgCode	所属单位code	string	50
4	orgName	所属单位name	string	200
5	deptId	所属部门ID,作为和机构挂钩的唯一	string	32
6	deptCode	所属部门code	string	50
7	deptName	所属部门name	string	200
8	userEname	登录时账号	string	50
9	userCname	用户中文名称	string	50
10	leaderFlag	是否领导(0 否 1是)	string	1
11	userCode	用户编码	string	50
12	secretType	密级(2-重要 3-一般 4-内部)	string	1
13	rankCode	职级编码	string	50
14	rankName	职级名称	string	200
15	dutyCode	职务编码	string	50
16	dutyName	职务名称	string	200
17	userTypeCode	人员类型编码	string	50
18	userTypeName	人员类型名称	string	200
19	sexCode	性别编码	string	50
20	sexName	性别名称	string	200
21	cdTypeCode	证件类型code	string	50
22	cdTypeName	证件类型名称	string	200
23	cdNum	证件号码	string	50
24	userEmail	邮箱	string	50
25	telephone	电话号码	string	20
26	mobilePhone	手机号码	string	20
27	personOrder	排序	double
28	validFlag	是否有效(0 无效 1有效)	string	1

部分字典相关由于数据较多,请参见附表《同步字段相关字典数据表》

# 二、数据同步详细流程说明及注意事项

# 1、第一步：获取同步数据的数据编码

# 1.1 详细说明

dataSyncRequest —— 请求该接口可获取同步数据的数据编码。数据编码即dataCode，也可以说是门票，用于获取具体的同步数据。获取的范围以平台接收到该请求的时间为止，所有待同步更新的数据的数据编码，以数组形式返回（具体结构请看接口详细说明）。具体内容包含三个字段：dataCode-数据编码、dataOrder-数据次序和operateTime-推送时间。请求参数只有appCode和appSecret，平台会根据appCode识别是哪个应用，并返回对应应用的数据编码。

# 1.2 注意事项

请必须注意，所有数据编码只能获取一次，每次调用dataSyncRequest接口获取数据编码后，被获取的数据编码取用状态会被更新为“已取用”，不能再被获取，所以在完成同步前请妥善保管数据编码。

# 2、第二步：获取具体同步数据

# 1.1 详细说明

querySyncDataInfo —— 请求该接口可获取具体的同步数据。请求参数有：appCode、appSecret和dataCode，都是必填项。平台会根据dataCode获取指定的同步数据。返回值有：operateData-具体同步数据、dataType-标识同步数据的类型、dataOrder-数据次序、operateType-数据同步操作类型。**其中dataType：1-组织机构数据；2-人员账号数据；operateType：save-新增或更新；delete-删除。**具体返回值结构请看接口详细说明。

# 1.2 注意事项

根节点的判定，在平台数据同步模块-同步管理页面，开启组织同步功能时会要求输入根机构节点，根节点判定以此处输入的为准（详情请看数据同步模块操作手册）。

请注意必须按次序（dataOrder）对数据进行同步，若次序不对则可能无法获取到具体同步数据。同步数据可以反复获取。每获取并处理完一条同步数据，必须调用feedbackRequest接口反馈该数据的同步情况。

若返回ownCode状态码为201，则说明前一条dataCode未反馈或者是反馈状态为“失败”，这里会返回currDataCode（当前dataCode）和preDataCode（前一条dataCode），便于业务系统方处理。

# 3、第三步：反馈同步情况

# 1.1 详细说明

feedbackRequest —— 请求该接口反馈同步情况。请求参数有：appCode、appSecret、dataCode、feedback、errMsg、relationId、relationCode和relationName。feedback状态有三种：success、fail、ignore和exception。实际反馈哪种状态是由业务系统方自己决定的，平台只负责接收并记录此次同步情况，请业务系统方根据自己实际同步情况进行反馈，本次同步是成功还是失败。

# 1.2 注意事项

请注意success、fail和ignore是组织和账号通用反馈状态，exception是账号独有反馈状态。反馈为success则第二步能够获取下一条数据，反馈为fail则第二步不能获取下一条数据；如果是账号，可以反馈exception，第二步依然获取下一条数据。由于组织数据特殊性质，若当前数据同步出现异常，请如实反馈，暂停同步先排查问题，以免出现该组织数据是一个父节点会影响后续节点的同步。而账号数据互不影响，若同步出现异常不想暂停同步，可以反馈exception标记为“异常数据，待处理”，等全部同步完成后再排查处理。

# 三、接口详细说明

# 1、dataSyncInform——同步通知接口

该接口由业务系统方提供，当平台产生同步数据时，平台会调用该接口通知相应业务系统，业务系统收到通知后开启同步功能。平台默认使用“GET”方式发送请求。

# 2、dataSyncRequest —— 获取同步数据编码

URL: http://[ip]:[port]/taishanApi/tsSecApi/dataSyncRequest

Description: 发送请求获取同步数据编码。获取范围为请求发送时间为止数据池内存放的所有需要同步更新的数据的数据编码（相当于门票）。数据编码（门票）只能获取一次，请妥善保存。数据编码（门票）用于调用【querySyncDataInfo】接口获取具体的同步数据。

ownCode状态码说明：200-数据池内存在需要同步更新数据的数据编码。201-数据池内不存在需要同步更新数据的数据编码，或者数据编码已经被全部获取。209-请求过于频繁导致接口已锁定，需联系管理员解锁。

Query-parameters:

Parameter	Type	Description	Required	Since
appCode	string	应用编码	true	-
appSecret	string	应用密钥	true	-

Request-example:

{
	"appCode": "tsda642866d93041d9908a695e827d2c5c",
	"appSecret": "912cc3640014d5467c234258cfe55b7bf36deaab708c9189c7c645514429ab97443c40c76d051769"
}

1
2
3
4

Response-fields:

Field	Type	Description	Since
dataCode	String	同步数据编码	-
dataOrder	Int	同步数据次序,在存储以及后面获取数据的时候请严格按照这个次序进行	-
operateTime	DateTime	操作时间(yyyy-MM-dd HH:mm:ss)	-

Response-example:

有需要更新同步的数据时：
{
    "code": 200,
    "data": {
        "result": [
            {
                "dataOrder": 1,
                "operateTime": "2022-08-08 09:39:03",
                "dataCode": "fd8e321d7bd4af3ce0f98bb8597e335c"
            },
            {
                "dataOrder": 2,
                "operateTime": "2022-08-08 09:39:03",
                "dataCode": "fd8e321d7b11d4af3ce0f98bb8597e335c"
            }
        ],
        "ownCode": 200,
        "innerMessage": "",
        "message": "成功"
    },
    "success": true,
    "message": "OK"
}
无需要更新同步的数据时：
{
    "code": 200,
    "data": {
        "result": [],
        "ownCode": 201,
        "innerMessage": "",
        "message": "没有需要更新同步的数据"
    },
    "success": true,
    "message": "OK"
}
接口锁定时：
{
    "code": 200,
    "data": {
        "result": [],
        "ownCode": 209,
        "innerMessage": "",
        "message": "接口已锁定，请到同步管理页面解除锁定"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# 3、querySyncDataInfo —— 获取同步数据

URL: http://[ip]:[port]/taishanApi/tsSecApi/querySyncDataInfo

Description: 根据【dataSyncRequest】接口所获取到的数据编码（dataCode），按次序逐条获取具体的同步数据。

ownCode状态码说明：200-正常；201-无法继续同步，需要暂停同步，排查并解决问题；202-请求的数据已失效、已完成同步或不存在，该状态无需特殊处理，继续往下同步即可。209-请求过于频繁导致接口已锁定，需联系管理员解锁。

Query-parameters:

Parameter	Type	Description	Required	Since
appCode	string	应用编码	true	-
appSecret	string	应用密钥	true	-
dataCode	string	同步数据编码	true	-

Request-example:

{
	"appCode": "tsda642866d93041d9908a695e827d2c5c",
	"appSecret": "912cc3640014d5467c234258cfe55b7bf36deaab708c9189c7c645514429ab97443c40c76d051769",
	"dataCode": "9ed6ebd0de734ecc9be60526ae00ea3d"
}

1
2
3
4
5

Response-fields:

Field	Type	Description	Since
operateData	JSON	具体的同步数据信息,具体数据已经在第一章中介绍过了	-
dataType	String	数据类型：1-组织机构；2-人员账号	-
operateType	String	操作类型：save-新增或更新；delete-删除	-
dataOrder	int	和编码的排序是一致的	-
syncType	String	同步类型：1-全量同步，2-增量同步，3-手动同步	-

Response-example:

正常情况下的返回

{
    "code": 200,
    "data": {
        "result": {
            "dataOrder": 1,
            "operateData": "{\"deptType\":\"01,03\",\"innerCode\":\"f7c5182a7cfd8f34281683a6f368b2b5\",\"isParent\":\"0\",\"orgCname\":\"南平部门一13\",\"orgCode\":\"35050000D001\",\"orgShortCname\":\"南平部门一13\",\"organOrder\":1000.0,\"parentInnerCode\":\"f8abe07d6c7d0cc39b1bff96ca6300ec\",\"parentOrgId\":\"f8abe07d6c7d0cc39b1bff96ca6300ec\",\"purpose\":\"2\",\"validFlag\":\"1\"}",
            "dataType": "1",
            "operateType": "save",
            "syncType": "1"
        },
        "ownCode": 200,
        "innerMessage": "",
        "message": "成功"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

异常情况

上一条数据未反馈,无法获取当前数据信息

ownCode状态码说明：201-无法继续同步，需要暂停同步，排查并解决问题。

{
    "code": 200,
    "data": {
        "result": "noFeedback",
        "ownCode": 201,
        "currDataCode": "734a646c3633420cbf5ff7aa22d87a82",
        "innerMessage": "",
        "message": "前一条同步数据[dataCode:2c04aae9648f40efa92468350474e1c5]未反馈成功，无法同步。当前同步数据[dataCode:734a646c3633420cbf5ff7aa22d87a82]",
        "preDataCode": "2c04aae9648f40efa92468350474e1c5"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12
13

数据已经同步成功,或者失效

ownCode状态码说明：202-请求的数据已失效、已完成同步或不存在，该状态无需特殊处理，继续往下同步即可。

{
    "code": 200,
    "data": {
        "result": "success",
        "ownCode": 202,
        "currDataCode": "734a646c3633420cbf5ff7aa22d87a821",
        "innerMessage": "",
        "message": "该数据已同步成功或已失效，无需同步。"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12

请求数据不存在

ownCode状态码说明：202-请求的数据已失效、已完成同步或不存在，该状态无需特殊处理，继续往下同步即可。

{
    "code": 200,
    "data": {
        "result": "noData",
        "ownCode": 202,
        "currDataCode": "734a646c3633420cbf5ff7aa22d87a821",
        "innerMessage": "",
        "message": "请求的数据[dataCode:734a646c3633420cbf5ff7aa22d87a821]不存在"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12

接口锁定

ownCode状态码说明：209-请求过于频繁导致接口已锁定，需联系管理员解锁。

接口锁定时：
{
    "code": 200,
    "data": {
        "result": [],
        "ownCode": 209,
        "innerMessage": "",
        "message": "接口已锁定，请到同步管理页面解除锁定"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12

# 4、feedbackRequest —— 反馈同步情况

URL: http://[ip]:[port]/taishanApi/tsSecApi/feedbackRequest

Description: 反馈数据同步的情况。与接口【querySyncDataInfo】关联，querySyncDataInfo每根据dataCode获取一条同步数据，处理后就必须调用feedbackRequest接口向平台反馈此次同步情况，实际反馈的信息由业务系统方自己决定，平台仅在接受到“成功”反馈信息时才允许获取下一条同步数据。

ownCode状态码说明：200-正常；201-该dataCode对应同步数据并未被获取，不能反馈；202-该dataCode不存在；203-反馈参数错误；204-该dataCode对应同步数据已反馈且状态为成功，成功数据不能重复反馈。209-请求过于频繁导致接口已锁定，需联系管理员解锁。

注：relationId、relationCode和relationName是必须回传的，作为平台判断同步是否成功的标识，以及将平台数据与对接方数据做关联用。

Query-parameters:

Parameter	Type	Description	Required	Since
appCode	string	应用编码	true	-
appSecret	string	应用密钥	true	-
dataCode	string	同步数据编码	true	-
feedback	string	反馈信息（success-成功，fail-失败，ignore-忽略，exception-异常（该状态仅人员账号使用））	true	-
errMsg	String	当反馈为失败时的失败原因，长度不能超过100	false	-
relationId	String	对接方的ID（机构就是机构的唯一标识，用户就是用户的唯一标识，注意！不是平台推送过去的ID，是对接方保存平台推送的同步数据时自己的唯一标识ID）	true	-
relationCode	String	关联编码：机构就是机构编码，用户就是登录账号	true	-
relationName	String	关联名称：机构就是机构名称，用户就是用户名称	true	-

Request-example:

{
	"appCode": "tsda642866d93041d9908a695e827d2c5c",
	"appSecret": "912cc3640014d5467c234258cfe55b7bf36deaab708c9189c7c645514429ab97443c40c76d051769",
	"dataCode": "110101000000",
	"feedback": "fail",
	"errMsg": "保存时异常"
}

1
2
3
4
5
6
7

Response-example:

反馈成功时

{
    "code": 200,
    "data": {
        "ownCode": 200,
        "innerMessage": "",
        "message": "成功接收反馈"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10

反馈异常时:

情况1

ownCode状态码说明：201-该dataCode对应同步数据并未被获取，不能反馈。

{
    "code": 200,
    "data": {
        "result": "notUse",
        "ownCode": 201,
        "innerMessage": "",
        "message": "检测到当前[dataCode:b5e7f4f3f7af1bb5802af0b78f556130]对应的同步数据尚未被请求获取，请检查同步过程是否正确！"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11

情况2

ownCode状态码说明：202-该dataCode不存在。

{
    "code": 200,
    "data": {
        "result": "noData",
        "ownCode": 202,
        "innerMessage": "",
        "message": "无法查询到数据，请检查当前[dataCode:b5e7f4f3f7af1bb5802af0b78f5561301]是否正确。"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11

情况3

ownCode状态码说明：203-反馈参数错误。

{
    "code": 200,
    "data": {
        "result": "fail",
        "ownCode": 203,
        "innerMessage": "",
        "message": "接收反馈失败，当前反馈参数[feedback:success1]的值不正确（应为“success或fail”）。"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11

情况4

ownCode状态码说明：204-该dataCode对应同步数据已反馈且状态为成功，成功数据不能重复反馈。

{
    "code": 200,
    "data": {
        "result": "duplicate",
        "ownCode": 204,
        "innerMessage": "",
        "message": "该条数据已反馈，反馈结果为[成功]，请勿重复反馈！"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11

情况5

ownCode状态码说明：209-请求过于频繁导致接口已锁定，需联系管理员解锁。

接口锁定时：
{
    "code": 200,
    "data": {
        "result": [],
        "ownCode": 209,
        "innerMessage": "",
        "message": "接口已锁定，请到同步管理页面解除锁定"
    },
    "success": true,
    "message": "OK"
}

1
2
3
4
5
6
7
8
9
10
11
12

# 四、数据映射说明

# 1、映射信息配置

在同步管理页面，当开启同步模式为“仅映射”或“映射及同步时”需要配置映射信息：

# （1）绑定根节点

映射前需要先绑定“平台根节点机构”与“对接方根节点机构”的orgId、orgCode和orgName；“平台根节点机构”是根据当前登录用户所属机构自动填充的，“对接方根节点机构”需要对接方根据自身情况填入应与“平台根节点机构”对应的机构信息。

# （2）录入对接方机构树查询接口

对接方需要提供一个异步查询对接方自身机构树的接口，并将完整路径（包括ip、端口、接口路径）在同步管理页面录入。

# 2、映射流程

# （1）仅映射

只需要在组织映射页面勾选相应节点进行映射保存即可。

# （2）映射及同步

需要先在组织映射页面勾选相应节点进行映射保存，在确认需要映射的节点都勾选映射完成后，点击列表右上方的“组织映射标记完成”，标记映射已完成，然后可以进行同步步骤。全量同步时，已映射节点和未映射节点都会推送，已映射节点会携带对接方机构信息（mappingOrgId、mappingOrgCode）。

注：映射相关功能详细操作方法请参考《数据同步模块操作手册》。

# 五、附表下载

下载地址：数据同步.xls

数据同步模块操作手册 →

# 数据同步

# 一、数据同步整体介绍

# 1、请求方式

# 2、数据同步流程

# 2.1 数据同步-总体流程简述

# 2.2 数据同步-业务系统方流程简述:

# 3、组织机构同步字段

# 4、人员账号同步字段

# 二、数据同步详细流程说明及注意事项

# 1、第一步：获取同步数据的数据编码

# 1.1 详细说明

# 1.2 注意事项

# 2、第二步：获取具体同步数据

# 1.1 详细说明

# 1.2 注意事项

# 3、第三步：反馈同步情况

# 1.1 详细说明

# 1.2 注意事项

# 三、 接口详细说明

# 1、dataSyncInform——同步通知接口

# 2、dataSyncRequest —— 获取同步数据编码

# 3、querySyncDataInfo —— 获取同步数据

# 4、feedbackRequest —— 反馈同步情况

# 四、数据映射说明

# 1、映射信息配置

# （1）绑定根节点

# （2）录入对接方机构树查询接口

# 2、映射流程

# （1）仅映射

# （2）映射及同步

# 五、附表下载

# 三、接口详细说明