基础数据OpenAPI接口文档V1.1

1. 概述

本文档定义了基础数据服务中包括但不限于空间、设备、项目、组织、企业、人员等六大核心数据实体的标准化开放接口规范，旨在为第三方业务系统提供统一、安全、高可用的主数据管理能力。

2. 前置准备/步骤

为保障接口安全，所有请求需进行身份认证。具体流程如下：

2.1. 申请clientId，clientSecret

三方应用向平台对接人申请，三方应用需要提供应用名称以及回调地址（非必填，只有门户单点登录需要其他管家对接时不需要）。

申请后将获得以下凭证：

clientId：应用唯一标识
clientSecret：应用密钥（请妥善保管，切勿泄露）

请求签名（sign）生成：
在发起接口请求前，需使用 clientSecret 对请求参数进行加密，生成签名 sign，并随请求一同传递。
服务端将根据传入的 clientId 查找对应的 clientSecret，对 sign 进行校验，验证通过后方可提供服务。
⚠️ 注意：未携带有效 sign 或签名验证失败的请求将被拒绝。

2.2. 统一认证机制

所有请求必须携带以下 Header。其中 sign 由 HMAC-SHA1 算法生成。

具体步骤请查看 2.3 签名机制。本文附录包含Java完整实现代码。

参数名	示例值	参数类型	必填	参数描述
Authorization	clientId:sign	string	是	权限认证
Date	Tue,18 Nov 2025 02:09:56 GMT	string	是	请求时间（EEE, dd MMM yyyy HH:mm:ss zzz）
Content-Type	application/json; charset=UTF-8	string	是	请求内容类型

2.3. 签名机制

⚠️注意：未携带有效sign或签名验证失败的请求将被拒绝。

3. 数据结构

（原文档包含图片，此处省略）

4. 名词解释

名词	详细说明
企业	具有法人主体资格的组织单位，可能是入驻办公企业、开发商、物业服务企业、运营商或其他机构。本文中企业特指项目下入驻办公的企业。
供应商	本文中特指为项目提供商品、材料、设备、服务的主体，可以是制造商、分销商、服务承包商或专业机构。如摄像头供应商-海康
设备设施	指用于居住、办公、商业运营或公共服务的物理实体及其相关设备、系统，包括建筑结构、机电系统、公共区域设施等。
围合	指围合或围护起来的区域边界及其封闭结构，用于实现安全、私密、分区管理的空间单元。
空间	指物业中可用来服务、使用或经营的面积与场所，包含建筑空间、公共空间、功能空间等

5. 接口文档

5.1. 空间位置模块

5.1.1. 查询楼栋列表

接口描述： 通过项目编码查询楼栋列表

接口定义： POST /api/open/master-data/v2/selectBuildingList

请求参数

参数名	参数类型	必填	参数描述
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）
projectCode	string	是	项目编码

请求示例

json

{
    "pageNum": 1,
    "pageSize": 10,
    "projectCode": "P123456"
}

响应参数

参数名	参数类型	长度	必填	参数描述
code	string	varchar(64)	是	楼栋编码
name	string	varchar(128)	是	楼栋名称
abbreviation	string	varchar(128)	否	楼栋俗称
serialNumber	string	varchar(32)	否	楼宇编号
projectCode	string	varchar(64)	是	项目编码
projectName	string	varchar(256)	是	项目名称

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "code": "B001",
            "name": "1号楼",
            "abbreviation": "A座",
            "serialNumber": "01",
            "projectCode": "P123456",
            "projectName": "测试项目"
        }
    ]
}

5.1.2. 查询单元列表

接口描述： 通过项目编码查询单元列表

接口定义： POST /api/open/master-data/v2/selectUnitList

请求参数

参数名	参数类型	必填	参数描述
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）
projectCode	string	是	项目编码
buildingCode	string	否	楼栋编码

请求示例

json

{
    "pageNum": 1,
    "pageSize": 10,
    "projectCode": "P123456",
    "buildingCode": "B001"
}

响应参数

参数名	类型	长度	必填	描述
code	string	varchar(64)	是	单元编码
name	string	varchar(128)	是	单元名称
buildingName	string	varchar(64)	是	楼栋名称
buildingCode	string	varchar(128)	是	楼栋编码
projectCode	string	varchar(64)	是	项目编码
projectName	string	varchar(256)	是	项目名称

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "code": "U001",
            "name": "一单元",
            "buildingName": "1号楼",
            "buildingCode": "B001",
            "projectCode": "P123456",
            "projectName": "测试项目"
        }
    ]
}

5.1.3. 查询围合列表

接口描述： 通过项目编码查询围合列表

接口定义： POST /api/open/master-data/v2/selectEnclosureList

请求参数

参数名	参数类型	必填	参数描述
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）
projectCode	string	是	项目编码

请求示例

json

{
    "pageNum": 1,
    "pageSize": 10,
    "projectCode": "P123456"
}

响应参数

字段名	类型	长度	描述
code	string	varchar(64)	围合编码
name	string	varchar(128)	围合名称
type	string	varchar(2)	围合类型。0-停车场，1-商业街，2-共管街
projectCode	string	varchar(64)	项目编码
projectName	string	varchar(256)	项目名称

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "code": "E001",
            "name": "地下停车场",
            "type": "0",
            "projectCode": "P123456",
            "projectName": "测试项目"
        }
    ]
}

5.1.4. 查询楼层列表

接口描述： 通过项目编码查询楼层列表

接口定义： POST /api/open/master-data/v2/selectFloorList

注意事项： 楼栋编码与围合编码不可同时存在

请求参数

参数名	参数类型	必填	参数描述
enclosureCode	string	否	围合编码
buildingCode	string	否	楼栋编码
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）
projectCode	string	是	项目编码

请求示例

json

{
    "pageNum": 1,
    "pageSize": 10,
    "projectCode": "P123456",
    "buildingCode": "B001"
}

响应参数

字段名	类型	长度	必填	描述
code	string	varchar(64)	是	楼层编码
name	string	varchar(128)	是	楼层名称
serialNumber	string	varchar(32)	否	楼层编号
projectName	string	varchar(256)	是	项目名称
projectCode	string	varchar(64)	是	项目编码
buildingName	string	varchar(64)	否	楼栋名称
buildingCode	string	varchar(64)	否	楼栋编码
unitName	string	varchar(128)	否	单元名称
unitCode	string	varchar(64)	否	单元编码
enclosureName	string	varchar(128)	否	围合名称
enclosureCode	string	varchar(64)	否	围合编码

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "code": "F001",
            "name": "1层",
            "serialNumber": "01",
            "projectName": "测试项目",
            "projectCode": "P123456",
            "buildingName": "1号楼",
            "buildingCode": "B001"
        }
    ]
}

5.1.5. 查询房屋列表

接口描述： 通过项目编码查询空间房屋列表

接口地址： POST /api/open/master-data/v2/selectPropertyList

请求参数

参数名	参数类型	必填	参数描述
isPublic	string	否	是否公区。1公区、0非公区
publicSpaceType	string	否	公区空间类型
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）
projectCode	string	是	项目编码

请求示例

json

{
    "pageNum": 1,
    "pageSize": 10,
    "projectCode": "P123456",
    "isPublic": "0"
}

响应参数

字段名	类型	长度	描述
name	string	varchar(128)	空间名称
code	string	varchar(64)	空间编码
serialNumber	string	varchar(32)	空间编号
isPublic	integer	tinyint(1)	是否公区
publicSpaceType	string	varchar(32)	公区空间类型(编码)
publicSpaceTypeValue	string	varchar(64)	公区空间类型(名称)
projectCode	string	varchar(64)	项目编码
projectName	string	varchar(256)	项目名称
buildingCode	string	varchar(64)	楼栋编码
buildingName	string	varchar(128)	楼栋名称
unitCode	string	varchar(64)	单元编码
unitName	string	varchar(128)	单元名称
floorCode	string	varchar(64)	楼层编码
floorName	string	varchar(128)	楼层名称
orgCode	string	varchar(64)	委托主体（编码）
orgCodeValue	string	varchar(128)	委托主体（名称）
type	string	tinyint	空间类型
manageType	string	varchar(2)	运营模式（编码）
manageTypeValue	string	varchar(64)	运营模式（名称）
businessDistribution	string	varchar(10)	业态分布（编码）
businessDistributionValue	string	varchar(64)	业态分布（名称）
houseType	string	varchar(16)	空间户型（编码）
houseTypeValue	string	varchar(64)	空间户型（名称）
buildingArea	string	varchar(16)	建筑面积
rentableArea	string	varchar(16)	计租面积
rentalStandard	string	varchar(64)	租金标准

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "name": "101室",
            "code": "R001",
            "serialNumber": "101",
            "isPublic": 0,
            "projectCode": "P123456",
            "projectName": "测试项目",
            "buildingCode": "B001",
            "buildingName": "1号楼",
            "unitCode": "U001",
            "unitName": "一单元",
            "floorCode": "F001",
            "floorName": "1层",
            "buildingArea": "89.50",
            "rentableArea": "85.00"
        }
    ]
}

5.2. 设备模块

5.2.1. 查询设备列表

接口描述： 通过项目编码查询设备设施列表

接口定义： POST /api/open/master-data/v2/selectEquipmentList

请求参数

参数名	参数类型	必填	参数描述
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）
projectCode	string	是	项目编码
status	integer	是	数据状态。1:有效,2:草稿
buildingCode	string	否	楼栋编码
enclosureCode	string	否	围合编码
unitCode	string	否	单元编码
floorCode	string	否	楼层编码
propertyCode	string	否	空间

请求示例

json

{
    "pageNum": 1,
    "pageSize": 10,
    "projectCode": "Pxxxx",
    "status": 1
}

响应参数

字段名	类型	长度	描述
code	string	varchar(64)	设备编码
name	string	varchar(128)	设备名称
type	string	varchar(32)	设备类型编码
typeValue	string	varchar(32)	设备分类名称
productTypeValue	string	varchar(256)	产品分类名称
equipmentStatus	integer	tinyint(1)	设备状态。见附录
maintenanceCycle	integer	tinyint(1)	维保周期。见附录
installationDate	string	varchar(32)	安装日期
warrantyExpiryDate	string	varchar(32)	质保到期日期
serialNumber	string	varchar(64)	设备编号
projectCode	string	varchar(64)	项目编码
projectName	string	varchar(256)	所属项目
buildingCode	string	varchar(64)	楼栋编码
buildingName	string	varchar(128)	所属楼栋
enclosureCode	string	varchar(64)	围合编码
enclosureName	string	varchar(128)	所属围合
unitName	string	varchar(128)	所属单元
floorName	string	varchar(128)	所属楼层
propertyName	string	varchar(128)	所属空间
unitCode	string	varchar(64)	单元编码
floorCode	string	varchar(64)	楼层编码
propertyCode	string	varchar(64)	空间编码
brand	string	varchar(64)	品牌名称
manufactureCompany	string	varchar(64)	生产单位
manufactureCompanyTel	string	varchar(64)	生产单位电话
commissioningDate	string	varchar(32)	投用日期
takeoverStatus	integer	tinyint(1)	接管状态。见附录
controlArea	string	varchar(64)	控制区域
responsible	string	varchar(64)	设备责任人
purchaseDate	string	varchar(32)	购置日期
manufacturingDate	string	varchar(32)	出厂日期
acceptanceDate	string	varchar(32)	验收日期
installationLocation	string	varchar(128)	安装位置
occupiedArea	BigDecimal	decimal(16,4)	占地面积
installationCompany	string	varchar(128)	安装单位
warrantyStartDate	string	varchar(32)	质保开始时间
warrantyPeriod	string	varchar(2)	质保年限
scrapDate	string	varchar(32)	报废时间
useStatus	integer	tinyint(1)	使用状态。见附录
prpRight	integer	tinyint(1)	产权归属。见附录
upkeepDate	string		保养日期
status	integer	tinyint(1)	数据状态。1有效，2草稿
longitude	string	varchar(32)	经度
latitude	string	varchar(32)	纬度
height	string	varchar(32)	高度
thirdCode	string	varchar(64)	设备did编码
valid	integer	tinyint	数据源状态。1有效，0无效
x	string	varchar(255)	坐标X
y	string	varchar(255)	坐标Y
z	string	varchar(255)	坐标Z

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "code": "EQ001",
            "name": "智能摄像头",
            "type": "CAM",
            "typeValue": "摄像头",
            "equipmentStatus": 2,
            "serialNumber": "SN123456",
            "projectCode": "Pxxxx",
            "projectName": "测试项目",
            "status": 1
        }
    ]
}

5.3. 设备品类模块

5.3.1. 查询设备产品列表

接口描述： 根据产品分类查询产品列表

接口定义： GET /api/open/master-data/v2/selectProductList

请求参数

参数名	参数类型	必填	参数描述
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

GET /api/open/master-data/v2/selectProductList?pageNum=1&pageSize=10

响应参数

字段名	类型	长度	描述
code	string	varchar(64)	产品编码
name	string	varchar(128)	产品名称
productType	string	varchar(32)	产品类型
productTypeValue	string	varchar(128)	产品类型名称
model	string	varchar(64)	产品型号
supplier	string	varchar(64)	供应商
supplierValue	string	varchar(64)	供应商名称
unit	string	varchar(32)	单位
specification	string	varchar(255)	规格
size	string	varchar(32)	尺寸
note	string	varchar(255)	备注
thirdCode	string	varchar(64)	外部产品编码
visualModel	string	varchar(255)	可视化模型
status	string	tinyint(1)	数据状态。1有效，0失效

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "code": "P001",
            "name": "高清网络摄像机",
            "productType": "CAM",
            "productTypeValue": "摄像头",
            "model": "DS-2CD2T25",
            "supplier": "SUP001",
            "supplierValue": "海康威视",
            "unit": "台",
            "status": "1"
        }
    ]
}

5.3.2. 查询产品品类列表

接口描述： 查询产品品类列表

接口定义： GET /api/open/master-data/v2/selectProductTypeList

注意事项： 获取下级数据则parentCode为当前品类编码

请求参数

参数名	参数类型	必填	参数描述
parentCode	string	是	父编码，默认根节点为-1

请求示例

GET /api/open/master-data/v2/selectProductTypeList?parentCode=-1

响应参数

字段名	类型	长度	描述
name	string	varchar(128)	品类名称
code	string	varchar(128)	品类编码
parentCode	string	varchar(128)	上级编码
pathCode	string	varchar(128)	路径编码
level	integer	int	层级

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "name": "安防设备",
            "code": "SEC",
            "parentCode": "-1",
            "pathCode": "/SEC",
            "level": 1
        }
    ]
}

5.4. 组织模块

5.4.1. 查询组织列表

接口描述： 通过应用权限查询组织列表

接口定义： GET /api/open/master-data/v2/selectOrganizationList

注意事项： 获取下级数据则parentCode为当前组织编码

请求参数

参数名	参数类型	必填	参数描述
parentCode	string	是	父编码，默认根节点为-1

请求示例

GET /api/open/master-data/v2/selectOrganizationList?parentCode=-1

响应参数

字段名	类型	长度	描述
code	string	varchar(64)	组织编码
name	string	varchar(128)	组织名称
type	integer	int	组织类型。1：公司，2：部门，3：供应商
parentCode	string	varchar(64)	上级编码
sort	integer	int	排序。以正序排列

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "code": "ORG001",
            "name": "测试公司",
            "type": 1,
            "parentCode": "-1",
            "sort": 1
        }
    ]
}

5.4.2. 新增组织部门

接口描述： 新增组织下部门信息。如果组织未授权则无权限新增

接口定义： POST /api/open/master-data/v2/addOrganization

请求参数

参数名	参数类型	必填	参数描述
name	string	是	组织名称
parentCode	string	是	上级组织编码。（需要授权）如：OO0000022
type	integer	是	组织类型。1公司，2部门
sort	integer	否	排序，以正序排列。默认999

请求示例

json

{
    "name": "技术部",
    "parentCode": "ORG001",
    "type": 2,
    "sort": 10
}

响应参数

字段名	类型	长度	描述
code	string	varchar(64)	组织编码
name	string	varchar(128)	组织名称
type	integer	int	组织类型。1公司，2部门
parentCode	string	varchar(64)	上级编码
sort	integer	int	排序，以正序排列。默认999

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": {
        "code": "DEPT001",
        "name": "技术部",
        "type": 2,
        "parentCode": "ORG001",
        "sort": 10
    }
}

5.4.3. 编辑组织部门

接口描述： 更新组织下部门信息。如果组织未授权则无权限更新

接口定义： POST /api/open/master-data/v2/updateOrganization

请求参数

参数名	参数类型	必填	参数描述
code	string	是	部门编码
name	string	是	部门名称
sort	integer	否	排序。以正序排列

请求示例

json

{
    "code": "DEPT001",
    "name": "技术研发部",
    "sort": 5
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.4.4. 删除组织部门

接口描述： 通过编码删除部门数据

接口定义： Delete /api/open/master-data/v2/delOrganization

请求参数

参数名	参数类型	是否必填	参数描述
code	string	是	部门编码

请求示例

Delete /api/open/master-data/v2/delOrganization?code=DEPT001

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.5. 项目模块

5.5.1. 查询项目列表

接口描述： 通过应用权限查询项目列表

接口定义： POST /api/open/master-data/v2/selectProjectList

请求参数

参数名	参数类型	必填	参数描述
type	integer	否	项目类型。1 自营可租，2 自营可售，3 外拓，4 政企，5 案场，6 人力外包，7 回购，8 规模化租赁，9 移交商业
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

json

{
    "pageNum": 1,
    "pageSize": 10,
    "type": 1
}

响应参数

字段名	类型	长度	描述
projectCode	string	varchar(64)	项目编码
projectName	string	varchar(128)	项目名称
parentCode	string	varchar(64)	父级项目编码
abbreviation	string	varchar(128)	项目简称
province	string	varchar(64)	所在省份名称
provinceCode	string	varchar(32)	省份行政区划代码
city	string	varchar(64)	所在城市名称
cityCode	string	varchar(32)	城市行政区划代码
county	string	varchar(64)	所在区/县名称
countyCode	string	varchar(32)	区/县行政区划代码
street	string	varchar(64)	所在街道名称
streetCode	string	varchar(32)	街道行政区划代码
address	string	varchar(128)	详细地址
type	integer	tinyint(1)	项目类型。见附录
acquireType	integer	tinyint(1)	获取方式。见附录
businessType	integer	tinyint(1)	业务类型。见附录
orgName	string	varchar(64)	产权主体（所属组织）
propertyNature	integer	tinyint(1)	产权性质。见附录
parcelNumber	string	varchar(128)	宗地号
totalOccupiedArea	BigDecimal	decimal	总占地面积
totalBuildingArea	BigDecimal	decimal	总建筑面积
joinDate	string	varchar(32)	入伙时间（项目启用/交付日期）
mobile	string	varchar(32)	联系电话。脱敏展示：138****1234
status	integer	tinyint(1)	数据状态
orgCode	string	varchar(64)	所属组织编码
sort	integer	int	排序。以正序排列
des	string	varchar(500)	项目简介

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "projectCode": "P123456",
            "projectName": "测试项目",
            "type": 1,
            "city": "深圳市",
            "address": "南山区科技园",
            "status": 1
        }
    ]
}

5.6. 供应商模块

5.6.1. 查询供应商列表

接口描述： 查询供应商列表

接口定义： GET /api/open/master-data/v2/selectSupplierList

请求参数

参数名	参数类型	必填	参数描述
serviceType	string	否	服务类型。见附录
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

GET /api/open/master-data/v2/selectSupplierList?pageNum=1&pageSize=10&serviceType=0

响应参数

字段名	类型	长度	描述
name	string	varchar(64)	供应商名称
code	string	varchar(32)	供应商编码
contacts	string	varchar(16)	联系人
mobile	string	varchar(32)	联系人电话。脱敏展示：138****1234
serviceType	string	varchar(32)	服务类型
qualification	string	varchar(64)	资质信息
serviceStart	string	varchar(32)	服务开始时间
serviceEnd	string	varchar(32)	服务结束时间
serviceRange	string	varchar(255)	服务范围
address	string	varchar(128)	地址
state	integer	int	状态。0启用，1禁用

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "name": "海康威视",
            "code": "SUP001",
            "contacts": "张三",
            "mobile": "138****1234",
            "serviceType": "0",
            "state": 0
        }
    ]
}

5.7. 岗位模块

5.7.1. 查询岗位列表

接口描述： 查询岗位列表

接口定义： GET /api/open/master-data/v2/selectPostList

请求参数（Query）

参数名	参数类型	必填	参数描述
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）
postType	integer	否	岗位类型。见附录

请求示例

GET /api/open/master-data/v2/selectPostList?pageNum=1&pageSize=10&postType=1

响应参数

字段名	类型	长度	描述
postName	string	varchar(32)	岗位名称
code	string	varchar(64)	岗位编码
postType	string	int	岗位类型
postSort	integer	int	排序。以正序排列
postRemark	string	varchar(255)	岗位备注

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "postName": "工程师",
            "code": "POST001",
            "postType": "1",
            "postSort": 1,
            "postRemark": "技术岗位"
        }
    ]
}

5.8. 员工模块

5.8.1. 查询员工列表

接口描述： 通过组织查询员工列表

接口定义： GET /api/open/master-data/v2/selectUserList

数据安全性要求： 您通过该接口获取员工数据，表示您同意按《隐私数据保护与加密存储说明》内容约定处理数据。

请求参数

参数名	类型	必填	说明
orgCode	string	是	所属组织
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

GET /api/open/master-data/v2/selectUserList?orgCode=ORG001&pageNum=1&pageSize=10

响应参数

字段名	类型	长度	说明
jobNum	string	varchar(64)	工号
name	string	varchar(128)	姓名
mobile	string	varchar(20)	手机号。脱敏展示：138****1234
companyCode	string	varchar(64)	公司编码
companyName	string	varchar(128)	公司名称
outSourcing	integer	int	人员编制。0公司内部，1外包，2企业人员
cardType	string	int	证件类型
cardNum	string	varchar(64)	证件号码。脱敏展示：110101******1234
email	string	varchar(64)	邮箱
orgCode	string	varchar(64)	部门/组织编码
orgName	string	varchar(128)	部门/组织名称
entryTime	string	varchar(64)	入职时间
resiTime	string	varchar(64)	离职时间
sex	integer	int	性别。1男，2女
status	integer	int	数据状态。1有效，0失效
code	string	varchar(64)	员工编码
serveEnterprises	string	json	服务企业编码
serveEnterpriseNames	string	varchar(255)	服务企业名称列表
postList	list	见岗位列表信息	员工岗位列表

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "jobNum": "10001",
            "name": "李四",
            "mobile": "139****5678",
            "companyCode": "ORG001",
            "companyName": "测试公司",
            "orgCode": "DEPT001",
            "orgName": "技术部",
            "status": 1,
            "code": "EMP001"
        }
    ]
}

5.8.2. 新增员工

接口描述： 新增公司员工

接口定义： POST /api/open/master-data/v2/addUser

请求参数

参数名	类型	长度	必填	说明
jobNum	string	varchar(64)	是	工号
name	string	varchar(128)	是	姓名
sex	string	int	否	性别
mobile	string	varchar(20)	是	手机号
cardType	string	int	否	证件类型
cardNum	string	varchar(64)	否	证件号码
email	string	varchar(64)	否	邮箱
companyCode	string	varchar(64)	是	组织编码
orgCode	string	varchar(64)	是	部门编码
entryTime	string	varchar(64)	否	入职时间
resiTime	string	varchar(64)	否	离职时间
postList	list	见岗位列表	否	岗位信息列表

请求示例

json

{
    "jobNum": "10002",
    "name": "王五",
    "mobile": "13800138000",
    "companyCode": "ORG001",
    "orgCode": "DEPT001"
}

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": {
        "code": "EMP002"
    }
}

5.8.3. 更新员工

接口描述： 更新员工信息

接口定义： POST /api/open/master-data/v2/updateUser

请求参数

参数名	类型	长度	必填	说明
code	string	varchar(64)	是	员工编码
name	string	varchar(128)	是	姓名
sex	string	int	否	性别
mobile	string	varchar(20)	是	手机号
cardType	string	int	否	证件类型
cardNum	string	varchar(64)	否	证件号码
email	string	varchar(64)	否	邮箱
entryTime	string	varchar(64)	否	入职时间
resiTime	string	varchar(64)	否	离职时间
postList	list		否	岗位信息列表

请求示例

json

{
    "code": "EMP002",
    "name": "王小明",
    "mobile": "13900139000"
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.8.4. 删除员工

接口描述： 通过编码删除员工数据

接口定义： Delete /api/open/master-data/v2/delUser

请求参数

参数名	类型	必填	说明
code	string	是	员工编码

请求示例

Delete /api/open/master-data/v2/delUser?code=EMP002

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.9. 企业入驻项目

5.9.1. 查询已入驻企业

接口描述： 通过项目编码查询已入住企业列表

接口定义： GET /api/open/master-data/v2/selectErpProjectList

请求参数

参数名	类型	必填	说明
projectCode	string	是	项目编码
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

GET /api/open/master-data/v2/selectErpProjectList?projectCode=P123456&pageNum=1&pageSize=10

响应参数

字段名	类型	长度	说明
erpCode	string	varchar(64)	企业编码
code	string	varchar(128)	企业项目组合编码
name	string	varchar(128)	名称
contactName	string	varchar(64)	联系人姓名
contactNumber	string	varchar(32)	联系电话

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "erpCode": "ERP001",
            "code": "ERP001_P123456",
            "name": "某某科技有限公司",
            "contactName": "张经理",
            "contactNumber": "138****0000"
        }
    ]
}

5.9.2. 新增企业入驻

接口描述： 通过项目编码与企业编码创建入驻关联

接口定义： POST /api/open/master-data/v2/addErpProject

请求参数

参数名	类型	长度	必填	说明
projectCode	string	varchar(64)	是	项目编码
erpCodeList	list		是	企业编码集合。需调用「查询组织列表」接口，获取根组织节点对应的组织编码（code）字段值

请求示例

json

{
    "projectCode": "P123456",
    "erpCodeList": ["ERP001", "ERP002"]
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.9.3. 删除企业入驻

接口描述： 通过项目编码与企业编码删除入驻关联

接口定义： POST /api/open/master-data/v2/delErpProject

请求参数

参数名	类型	长度	必填	说明
projectCode	string	varchar(64)	是	项目编码
erpCodeList	list		是	企业编码集合

请求示例

json

{
    "projectCode": "P123456",
    "erpCodeList": ["ERP001"]
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.9.4. 查询已入驻企业员工

接口描述： 查询已入驻企业员工列表

接口定义： POST /api/open/master-data/v2/selectUserOfErpProjectList

请求参数

参数名	类型	必填	说明
projectCode	string	是	项目编码
erpCode	string	是	企业编码
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "pageNum": 1,
    "pageSize": 10
}

响应参数

字段名	类型	长度	说明
jobNum	string	varchar(64)	工号
name	string	varchar(128)	姓名
mobile	string	varchar(20)	手机号。脱敏展示：138****1234
code	string	varchar(64)	员工编码
companyCode	string	varchar(64)	公司编码
companyName	string	varchar(128)	公司名称
orgCode	string	varchar(64)	部门编码
orgName	string	varchar(128)	部门名称

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "jobNum": "10001",
            "name": "李四",
            "mobile": "139****5678",
            "code": "EMP001",
            "companyCode": "ORG001",
            "companyName": "测试公司",
            "orgCode": "DEPT001",
            "orgName": "技术部"
        }
    ]
}

5.9.5. 查询未入驻企业员工

接口描述： 查询未入驻企业员工列表

接口定义： POST /api/open/master-data/v2/selectUserNotInErpProjectList

请求参数

参数名	类型	必填	说明
projectCode	string	是	项目编码
erpCode	string	是	企业编码
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "pageNum": 1,
    "pageSize": 10
}

响应参数

字段名	类型	长度	说明
jobNum	string	varchar(64)	工号
name	string	varchar(128)	姓名
mobile	string	varchar(20)	手机号
code	string	varchar(64)	员工编码
companyCode	string	varchar(64)	公司编码
companyName	string	varchar(128)	公司名称
orgCode	string	varchar(64)	部门编码
orgName	string	varchar(128)	部门名称

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "jobNum": "10003",
            "name": "赵六",
            "mobile": "137****9999",
            "code": "EMP003",
            "companyCode": "ORG001",
            "companyName": "测试公司",
            "orgCode": "DEPT002",
            "orgName": "市场部"
        }
    ]
}

5.9.6. 新增员工入驻

接口描述： 添加员工与企业项目关联

接口定义： POST /api/open/master-data/v2/addErpProjectUser

请求参数

参数名	类型	长度	必填	说明
projectCode	string	varchar(64)	是	项目编码
erpCode	string	varchar(64)	是	企业编码
userCodes	list		是	员工编码集合

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "userCodes": ["EMP001", "EMP003"]
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.9.7. 取消员工入驻

接口描述： 移除企业入驻的员工

接口定义： POST /api/open/master-data/v2/delErpProjectUser

请求参数

参数名	类型	长度	必填	说明
projectCode	string	varchar(64)	是	项目编码
erpCode	string	varchar(64)	是	企业编码
userCodes	list		是	员工编码集合

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "userCodes": ["EMP001"]
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.9.8. 查询企业已入驻空间

接口描述： 查询已入驻企业空间列表

接口定义： POST /api/open/master-data/v2/selectPropertyOfErpProjectList

请求参数

参数名	类型	必填	说明
projectCode	string	是	项目编码
erpCode	string	是	企业编码
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "pageNum": 1,
    "pageSize": 10
}

响应参数

字段名	类型	长度	说明
name	string	varchar(64)	空间名称
code	string	varchar(128)	空间编码
location	string	varchar(128)	完整空间路径

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "name": "101室",
            "code": "R001",
            "location": "1号楼/1单元/1层/101室"
        }
    ]
}

5.9.9. 查询企业待入驻空间

接口描述： 查询未入驻企业空间列表

接口定义： POST /api/open/master-data/v2/selectPropertyNotInErpProjectList

请求参数

参数名	类型	必填	说明
projectCode	string	是	项目编码
erpCode	string	是	企业编码
pageNum	integer	是	当前页码（默认第1页）
pageSize	integer	是	每页大小（默认15条,最大单页200条）

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "pageNum": 1,
    "pageSize": 10
}

响应参数

字段名	类型	长度	说明
name	string	varchar(64)	空间名称
code	string	varchar(128)	空间编码
location	string	varchar(128)	完整空间路径

响应示例

json

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "name": "102室",
            "code": "R002",
            "location": "1号楼/1单元/1层/102室"
        }
    ]
}

5.9.10. 企业入驻空间

接口描述： 添加空间与项目企业关联

接口定义： POST /api/open/master-data/v2/addErpProperty

请求参数

参数名	类型	长度	必填	说明
projectCode	string	varchar(64)	是	项目编码
erpCode	string	varchar(64)	是	企业编码
propertyCodes	list		是	空间编码集合

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "propertyCodes": ["R002"]
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

5.9.11. 企业移除已入驻空间

接口描述： 移除企业入驻的空间

接口定义： POST /api/open/master-data/v2/delErpProperty

请求参数

参数名	类型	长度	必填	说明
projectCode	string	varchar(64)	是	项目编码
erpCode	string	varchar(64)	是	企业编码
propertyCodes	list		是	空间编码集合

请求示例

json

{
    "projectCode": "P123456",
    "erpCode": "ERP001",
    "propertyCodes": ["R002"]
}

响应示例

json

{
    "code": 0,
    "msg": "success"
}

6. 附录

6.1. 签名生成（完整Java示例）

（原文档内容，此处保留占位，实际应有代码）

6.2. 状态码说明

code值	描述	说明
200	操作成功	请求成功
400	请求参数错误	缺少必填字段、格式非法等，具体信息查看错误msg
401	无效签名	clientId 无效或无权限
403	无对应权限	详情查看错误msg
404	未找到资源	请检查路径是否错误
500	服务器异常	服务端内部错误，请联系平台支持

6.3. 枚举字典

空间相关

参数名	参数描述
isPublic	是否公区。• "-1" = 是默认值为空，• 1公区、0非公区
publicSpaceType	公区空间类型（详见原文档，此处省略部分列表）
manageType	运营模式。• sc = 市场化租赁，• zc = 政策性住宅，• sy = 商业
businessDistribution	业态分布（详见原文档）
propertyType	空间运营类型（详见原文档）
houseType	房间户型（详见原文档）

设备相关

参数名	参数描述
equipmentStatus	设备状态：1=未使用，2=已使用，3=故障，4=报废，5=闲置，99=其他
useStatus	使用状态：0=闲置，1=启用
prpRight	产权归属：1=分公司，2=小业主，3=经营单位
maintenanceCycle	维保周期：1=天，2=周，3=月，4=季度，5=半年，6=年
status	数据状态：0=失效，1=有效，2=草稿
takeoverStatus	接管状态：1=已接管，2=未接管

项目相关

参数名	参数描述
acquireType	项目获取方式：1=租赁，2=购买，3=棚改，4=合建，5=新建
businessType	项目经营方式：1=租赁，2=售卖
propertyNature	产权性质：1=自有产权，2=规模化租赁，3=混合产权
type	项目类型：1=自营可租，2=自营可售，3=外拓，4=政企，5=案场，6=人力外包，7=回购，8=规模化租赁，9=移交商业

组织与岗位

参数名	参数描述
organization.type	组织类型：1=公司，2=部门，3=供应商，4=入驻企业
postType	岗位类型："1"=基层，"2"=中层，"3"=高层
serviceType	供应商服务类型："0"=设备采购，"1"=设备维护，"2"=设备维修

6.4. 隐私数据保护与加密存储说明

为确保通过接口采集的人员敏感信息（如手机号、身份证号码等）在数据库中的安全存储，必须遵循以下安全与合规要求：

加密存储
- 对所有敏感数据字段采用业界认可的强加密算法进行加密存储（如 AES-256 对称加密）。
- 加密密钥应由专门的密钥管理系统（KMS）安全管理。
- 加密操作应在服务端完成。
访问控制与最小权限原则
- 严格实现基于角色的访问控制（RBAC）。
- 敏感数据的访问应经审计记录。
合规与合法使用
- 遵守《中华人民共和国个人信息保护法》及公司隐私政策。
- 明确告知数据主体并获得授权。
数据传输安全
- 必须采用 HTTPS/TLS。
数据生命周期管理
- 严格管理存储期限，超期安全销毁或脱敏。
- 支持数据主体的访问、更正、删除权利。
安全风险评估与防护
- 定期安全评估和漏洞扫描。
- 实施密钥轮换、权限复审。

7. Q&A

Q1: 如何申请OpenAPI接入权限？

A1: 请向基础数据组提交应用接入申请，提供三方系统名称。审核通过后，将获得clientId和clientSecret凭证。

Q2: 签名验证失败怎么办？

A2: 请检查：1. clientSecret是否正确；2. Date头是否为RFC 1123格式且时区为GMT；3. CanonicalizedResource是否完整；4. 签名算法是否正确实现（HMAC-SHA1）；5. 签名截取是否正确（base64结果的第5-15位）。

Q3: 接口返回404错误如何处理？

A3: 检查baseUrl、API路径、HTTP方法是否正确。

Q4: 数据更新时如何避免覆盖空值？

A4: 建议采用"先查询、再合并、后更新"的策略。

Q5: 如何处理分页查询大数据量？

A5: 合理设置pageSize（不超过100），通过pageNum分批获取，使用增量同步策略。

基础数据OpenAPI接口文档V1.1 ​

1. 概述 ​

2. 前置准备/步骤 ​

2.1. 申请clientId，clientSecret ​

2.2. 统一认证机制 ​

2.3. 签名机制 ​

3. 数据结构 ​

4. 名词解释 ​

5. 接口文档 ​

5.1. 空间位置模块 ​

5.1.1. 查询楼栋列表 ​

5.1.2. 查询单元列表 ​

5.1.3. 查询围合列表 ​

5.1.4. 查询楼层列表 ​

5.1.5. 查询房屋列表 ​

5.2. 设备模块 ​

5.2.1. 查询设备列表 ​

5.3. 设备品类模块 ​

5.3.1. 查询设备产品列表 ​

5.3.2. 查询产品品类列表 ​

5.4. 组织模块 ​

5.4.1. 查询组织列表 ​

5.4.2. 新增组织部门 ​

5.4.3. 编辑组织部门 ​

5.4.4. 删除组织部门 ​

5.5. 项目模块 ​

5.5.1. 查询项目列表 ​

5.6. 供应商模块 ​

5.6.1. 查询供应商列表 ​

5.7. 岗位模块 ​

5.7.1. 查询岗位列表 ​

5.8. 员工模块 ​

5.8.1. 查询员工列表 ​

5.8.2. 新增员工 ​

5.8.3. 更新员工 ​

5.8.4. 删除员工 ​

5.9. 企业入驻项目 ​

5.9.1. 查询已入驻企业 ​

5.9.2. 新增企业入驻 ​

5.9.3. 删除企业入驻 ​

5.9.4. 查询已入驻企业员工 ​

5.9.5. 查询未入驻企业员工 ​

5.9.6. 新增员工入驻 ​

5.9.7. 取消员工入驻 ​

5.9.8. 查询企业已入驻空间 ​

5.9.9. 查询企业待入驻空间 ​

5.9.10. 企业入驻空间 ​

5.9.11. 企业移除已入驻空间 ​

6. 附录 ​

6.1. 签名生成（完整Java示例） ​

6.2. 状态码说明 ​

6.3. 枚举字典 ​

空间相关 ​

设备相关 ​

项目相关 ​

组织与岗位 ​

6.4. 隐私数据保护与加密存储说明 ​

7. Q&A ​

基础数据OpenAPI接口文档V1.1

1. 概述

2. 前置准备/步骤

2.1. 申请clientId，clientSecret

2.2. 统一认证机制

2.3. 签名机制

3. 数据结构

4. 名词解释

5. 接口文档

5.1. 空间位置模块

5.1.1. 查询楼栋列表

5.1.2. 查询单元列表

5.1.3. 查询围合列表

5.1.4. 查询楼层列表

5.1.5. 查询房屋列表

5.2. 设备模块

5.2.1. 查询设备列表

5.3. 设备品类模块

5.3.1. 查询设备产品列表

5.3.2. 查询产品品类列表

5.4. 组织模块

5.4.1. 查询组织列表

5.4.2. 新增组织部门

5.4.3. 编辑组织部门

5.4.4. 删除组织部门

5.5. 项目模块

5.5.1. 查询项目列表

5.6. 供应商模块

5.6.1. 查询供应商列表

5.7. 岗位模块

5.7.1. 查询岗位列表

5.8. 员工模块

5.8.1. 查询员工列表

5.8.2. 新增员工

5.8.3. 更新员工

5.8.4. 删除员工

5.9. 企业入驻项目

5.9.1. 查询已入驻企业

5.9.2. 新增企业入驻

5.9.3. 删除企业入驻

5.9.4. 查询已入驻企业员工

5.9.5. 查询未入驻企业员工

5.9.6. 新增员工入驻

5.9.7. 取消员工入驻

5.9.8. 查询企业已入驻空间

5.9.9. 查询企业待入驻空间

5.9.10. 企业入驻空间

5.9.11. 企业移除已入驻空间

6. 附录

6.1. 签名生成（完整Java示例）

6.2. 状态码说明

6.3. 枚举字典

空间相关

设备相关

项目相关

组织与岗位

6.4. 隐私数据保护与加密存储说明

7. Q&A