主数据同步（主数据拉取数据）

一、应用场景

主数据集成是指物联云平台和第三方平台中的基础数据同步。物联云平台主要包含5大类基础数据，分别为组织、企业成员、业主、项目、空间。其中空间数据下细分为5类数据，包含区域、楼栋、单元、楼层、房屋。

保障第三方平台和物联云平台的数据一致性。

二、功能说明

物联云平台提供主动拉取数据的方式进行主数据的同步。需要企业按照规范提供接口进行数据同步。数据同步方式包含全量同步和增量同步，仅在查询到该类型数据不存在成功状态的同步记录时才会进行。当该类型数据已存在成功状态的同步记录时，会进行增量数据的同步，增量数据同步包含新增、更新、删除。删除操作需要通过指定字段（is_delete）进行标识。

三、前提条件

3.1、全量同步：

程序启动或者定时任务触发增量同步时，如果查询对应的租户与数据类型没有成功状态的同步记录，进行全量同步：分页拉取租户对应的主数据全量数据进行同步。

3.2、增量同步（包括新增，更新，删除）：

通过每个租户拟定的同步规则（详情请见同框下文）创建不同规则的定时任务线程进行数据的增量同步：通过分页拉取租户同步记录空缺时间时间段的数据进行同步。

3.3、同步规则

1、第三方主数据的删除操作都需要有删除识别，通过is_deleted字段标识，并且能通过第三方主数据提供的查询数据接口体现出来。
2、begin_time～end_time 能够查询该时间段内创建/更新/删除的数据。
3、begin_time , end_time 都是针对 update_time 字段进行筛选。
4、租户同步规则：请提供对应的同步规则包括：数据类型、同步时间时间段、同步时间间隔（如：项目类型数据、每天00：00：00到23：00：00、60分钟）。
5、数据全量同步请按照以下顺序进行同步（如果无对应类型，忽略即可）：组织→项目→区域→楼栋→单元→楼层→房屋→住户；组织→项目→员工
6、数据删除同步请按照以下顺序同步（如果无对应类型忽略即可）：住户→房屋→楼层→单元→楼栋→区域→项目→组织；员工→ 项目→组织

四、关键流程

4.1、主数据同步流程（拉取数据）

img

五、数据提供方接口规范

5.1 数据获取接口规范

各企业定义按该接口规范进行接口开发：

接口URI

请自定义

接口调用Method
POST
请求头

名称 必填 类型 备注
Content-Type True String application/json; charset=utf-8
corp_id True String 企业ID
timestamp True Long 时间戳，精确到秒，10分钟内数据有效
nonce True String 流水号nonce（防止重复提交），至少为10位
signature True String 请求签名MD5(corp_id（企业ID）timestamp（时间戳） nonce（随机字符串） appSecret（加密秘钥，创建规则时填写）) （直接字段串拼接，无分隔符），用于数据提供方进行安全校验

请求参数

名称 必填 类型 备注
project_id False String 项目id(同步项目时不需要传)
data_type True String 同步数据类型（请看6.1、数据类型）
begin_time False Long 开始时间点，（时间戳：毫秒）（如不传此参数则返回到end_time字段的所有数据，两者都不传则返回全量数据）
end_time False Long 结束时间点，（时间戳：毫秒）（如不传此参数则返回begin_time到现在的所有数据，两者都不传则返回全量数据）
page_no False Int 当前页，不传默认1
page_size False Int 页面大小，不传默认100

请求示例：

{
    "project_id": "xxxxx",
    "data_type": "building",
    "begin_time": 6271823901,
    "end_time": 6782138991,
    "page_no": 1,
    "page_size": 100
}

返回参数说明

名称 必填 类型 备注
status True Int HTTP状态码（400、401、403、404、500、503）
code True Int 业务错误码，由数据提供方自定义
msg True String 业务错误信息，由数据提供方自定义
data True Object 业务响应数据
data.count False Int 数据总数
data.list False Array 数据列表
data.list. False Object 具体数据（根据请求的不同数据类型，参考具体数据模型。请看5.2、数据说明）

返回示例：

{
  "status": "HTTP状态码",
  "code": "业务错误码",
  "msg": "业务错误信息",
  "data": {
    "count": "总数",
    "list": [<T>]
  }
}

5.2 字段说明

5.2.1 组织数据

字段名称 类型 描述 备注 是否必填
id String 标识 组织ID 是
parent_id String 父级标识 否
name String 名称 是
remark String 描述 否
type Integer 组织分类 0:内部行政组织；1:内部行政组织；2:应用帐号组织;3:职能帐号组织;4:外部帐号组织;5:公共通讯录组织;6:业务组织，默认为6 否
sub_type Integer 组织性质 1:公司;2:分公司;3:子公司;4:片区公司;5:服务中心;6:部门，默认为1 否
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 由数据同步方填写 是 
{
    "id":"组织ID",
    "parent_id":"父级标识",
    "name": "名称",
    "remark": "描述",
    "type":6,
    "sub_type":1,
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源"
}

5.2.2 项目数据

字段名称 类型 描述 备注 是否必填
id String 标识 项目ID 是
name String 名称 是
type Int 项目类型 默认为 2 ：智慧社区（请参考：3.2.1 项目类型） 是
organization_id String 业务组织id 第三方组织ID 是
province String 省份 格式如：”广东省” 是
city String 城市 格式如:”广州市” 是
county String 县/区 无特殊格式要求 否
address String 项目的详细地址 否
remark String 项目备注 否
layout String 项目平面图的url 否
coordinate Array 项目经纬度数组 double数组, coordinate[0]是经度,coordinate[1]是纬度 否
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 由数据同步方填写 是 
{
    "id":"项目ID",
    "name": "项目名称",
    "type": 1,
    "organization_id":"项目的上层组织ID",
    "province": "省份",
    "city": "城市名",
    "county": "国家",
    "address": "详细地址",
    "remark": "备注",
    "layout": "项目平面图的url",
    "coordinate": [130.012,66.37],
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.3 区域数据

字段名称 类型 描述 备注 是否必填
id String 标识 是
project_id String 所属项目标识 是
parent_id String 父级区域标识 否
index Int 在同级中的排序 空间服务的业务属性 (如果没有,主数据是否自动生成) 否
remark String 备注 否
address String 详细地址 否
coordinate Array 经纬度数组 double数组 否
name String 名称 是
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 是 
{
    "id":"区域ID",
    "project_id":"所属项目标识",
    "parent_id":"父级区域标识",
    "index": 1,
    "remark": "备注",
    "address": "详细地址",
    "coordinate": [130.012,66.37],
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.4 公区数据

字段名称 类型 描述 备注 是否必填
id String 标识 是
project_id String 所属项目标识 是
parent_id String 父级空间标识 否
index Int 在同级中的排序 空间服务的业务属性 (如果没有,主数据是否自动生成) 否
remark String 备注 否
address String 详细地址 否
coordinate Array 经纬度数组 double数组 否
name String 名称 是
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 是 
{
    "id":"公区ID",
    "project_id":"所属项目标识",
    "parent_id":"父级空间标识",
    "index": 1,
    "remark": "备注",
    "address": "详细地址",
    "coordinate": [130.012,66.37],
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.5 楼栋数据

字段名称 类型 描述 备注 是否必填
id String 标识 是
project_id String 所属项目标识 是
parent_id String 所属父级标识 是
name String 名称 是
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 是 
{
    "id":"楼栋ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.6 单元数据

字段名称 类型 描述 备注 是否必填
id String 单元标识 是
project_id String 所属项目标识 是
parent_id String 所属父级标识 是
name String 名称 是
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 由数据同步方填写 是 
{
    "id":"单元ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.7 楼层数据

字段名称 类型 描述 备注 是否必填
id String 标识 是
project_id String 所属项目标识 是
parent_id String 所属父级标识 是
name String 名称 是
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 由数据同步方填写 是 
{
    "id":"楼层ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.8 房屋数据

字段名称 类型 描述 备注 是否必填
id String 标识 是
project_id String 所属项目标识 是
parent_id String 所属父级标识 是
name String 名称 是
type Int 房屋类型 1：家庭房屋，2：设备房3，公寓。对应的类型是家庭类型的房屋，会创建对应的home来供app用户使用。 是
sub_type Int 房屋子类型 完全由用户自定义的类型，不做限制 否
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 是 
{
    "id":"房屋ID",
    "project_id":"所属项目标识",
    "parent_id":"父级标识",
    "name": "名称",
    "type": 1,
    "sub_type": 1,
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源",
}

5.2.9 住户数据

字段名称 类型 描述 备注 是否必填
id String 标识 是
project_id String 所属项目标识 是
name String 名称 是
certificate_type Int 证件类型 1：身份证，2：护照，3：军官证，4：港澳通行证 是
certificate_id String 证件号 是
phone String 手机号 是
gender Int 性别 0：未知，1：男性，2：女性 是
birthday String 生日 否
register_time Long 注册时间 时间戳，毫秒数 是
houses Array 房产列表 是
houses.house_id String 房屋标识 否
houses.role Int 房屋下的角色 否
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 由数据同步方填写 是 
{
    "id":"住户ID",
    "project_id":"所属项目标识",
    "name": "名称",
    "certificate_type": 1,
    "certificate_id": "证件号",
    "phone": "手机号",
    "gender": 0,
    "birthday": "出生时间",
    "register_time": 1595385751001,
    "houses": [{
        "house_id":"房屋ID",
        "role":1
    }],
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源"
}

5.2.10 员工数据

字段名称 类型 描述 备注 是否必填
id String 标识 是
project_id String 所属项目标识 是
name String 名称 是
email String 邮箱 是
phone String 手机 是
certificate_id String 证件号 是
phone String 手机号 是
is_delete Boolean 是否已删除 true:已删除，false:没有删除 是
create_time Long 创建时间 时间戳，毫秒数 是
update_time Long 更新时间 时间戳，毫秒数 是
data_source String 数据来源 由数据同步方填写 是 
{
    "id":"员工ID",
    "project_id":"所属项目标识",
    "name": "名称",
    "phone": "手机号",
    "email": "邮箱",
    "is_delete": false,
    "create_time": 1595384829039,
    "update_time": 1595384829039,
    "data_source": "数据来源"
}

六、枚举详情

6.1、数据类型

数据类别 具体数据 data_type 数据类型
空间 项目 project String
空间 楼栋 building String
空间 区域 area String
空间 单元 unit String
空间 楼层 floor String
空间 房屋 house String
业主 业主 customer String
组织 组织 organization String
员工 员工 employee String

6.2、项目类型

枚举值 说明 数据类型
1 长租公寓 Int
2 智慧社区 Int
3 智慧家庭 Int
4 智慧路灯 Int
5 资产管理 Int
6 综合体 Int
7 标准类型 Int
8 联合办公 Int

6.3、同步操作类型

operation_type 说明 数据类型
update 修改（删除必须是逻辑删除，归类为修改类型） String
add 新增 String

6.4、房产角色类型

枚举值 说明 数据类型
0 未知 Int
1 业主 Int
2 亲属 Int
3 租客 Int
99 安装工 Int

6.5、房屋类型

枚举值 说明 数据类型
1 家庭房屋 Int
2 设备房（废弃） Int
3 公寓 Int

6.6、证件类型

枚举值 说明 数据类型
1 身份证 Int
2 护照 Int
3 军官证 Int
4 港澳通行证 Int

6.7、性别类型

枚举值 说明 数据类型
0 未知 Int
1 男性 Int
2 女性 Int
没找到需要的文档？
你可以提交工单反馈 或 阅读常见问题
客服工单常见问题