HC小区接口文档

基础接口

登陆接口 接口签名 员工接口

资产接口

小区接口 物业接口 楼栋接口 单元接口 房屋接口 交房 退房 车位接口 车辆接口

业主接口

业主接口 家庭成员 查询房屋认证 认证审核 账户接口 撤销账户明细

费用接口

费用项接口 创建费 查询费用 缴费接口 结束费用 缴费记录 水电抄表

工单接口

报修接口 投诉接口

保存房屋

添加房屋
修改房屋
删除房屋
查询房屋

1. 接口名称

添加房屋

2. 接口描述

用于在物业管理系统中新增房屋信息，包括房屋基本信息、房屋状态、房屋类型等。

3. 接口路径

POST http://{ip}:{port}/app/room.saveRoom

4. 请求方法

POST

5. 请求头

参数名称 必填 类型 描述
Authorization 是 String 用户认证 token，通过登录接口获取
app-id 是 String 应用 ID，系统 dev 账户分配
transaction-id 是 String 请求流水号，格式：1000000000+YYYYMMDDhhmmss+6位序列
sign 是 String 签名
req-time 是 String 请求时间，格式：YYYYMMDDhhmmss

6. 请求参数

6.1 请求体参数（JSON 格式）
参数名称 必填 类型 描述 示例值
communityId 是 String 小区 ID 2022121921870161
unitId 是 String 单元 ID 123123123
roomNum 是 String 房号 88488
layer 是 String 层数 1
section 是 String 房屋个数（需为整数） 0
apartment 是 String 户型（固定 10102） 10102
builtUpArea 是 String 建筑面积（需为金额格式） 110
feeCoefficient 是 String 算费系数（固定 1.00） 1.00
state 是 String 房屋状态（2001-已售，2002-未销售，2003-已出租，2004-未出租，2005-已退租，2009-其他） 2002
roomSubType 否 String 房屋类型（默认 110）：
110-住宅
120-办公室
119-宿舍		 110
roomArea 否 String 室内面积（默认同 builtUpArea） 110
roomRent 否 String 租金（办公室/宿舍时使用，默认 0） 0
remark 否 String 备注 测试房屋
ownerId 条件必填 String 业主 ID（当 state 不是 2002 时必填） owner123
startTime 否 String 绑定开始时间（默认当前时间） 2023-01-01 00:00:00
endTime 否 String 绑定结束时间（默认 2037-01-01 00:00:00） 2037-01-01 00:00:00
attrs 否 Array<Object> 房屋扩展属性（可选） 见示例
6.2 attrs 参数说明（可选）
参数名称 必填 类型 描述
attrId 否 String 属性 ID（新增时可不填或传 - 开头）
specCd 是 String 规格编码
value 是 String 属性值

7. 返回值

参数名称 类型 描述
code int 返回码：0 成功，其他失败
msg String 返回信息

8. 示例请求

{
  "roomNum": "88488",
  "layer": "1",
  "unitId": "123123123",
  "section": "0",
  "apartment": "10102",
  "builtUpArea": "110",
  "feeCoefficient": "1.00",
  "state": "2002",
  "remark": "测试房屋",
  "roomSubType": "110",
  "roomArea": "110",
  "roomRent": "0",
  "communityId": "2022121921870161"
}

9. 示例响应

{
  "code": 0,
  "msg": "成功"
}

10. 业务逻辑说明

  1. 参数校验：

    • 检查必填字段（如 communityId、unitId、roomNum 等）。
    • 校验 section 是否为整数，builtUpArea 和 feeCoefficient 是否为金额格式。
    • 校验 state 是否为有效状态（2001-2005 或 2009）。
    • 校验 unitId 是否属于该小区。

  2. 数据处理：

    • 生成 roomId（房屋 ID）。
    • 设置默认值（如 roomSubType 默认 110，roomRent 默认 0）。
    • 如果房屋状态不是 2002（未销售），则必须绑定业主（ownerId）。

  3. 数据库操作：

    • 保存房屋信息（room 表）。
    • 如果房屋已绑定业主，则保存业主房屋关系（owner_room_rel 表）。
    • 保存房屋扩展属性（room_attr 表）。

  4. 事务管理：

    • 使用 @Java110Transactional 确保数据一致性。

11. 错误码说明

错误码 描述
非 0 操作失败，具体原因见 msg
CmdException 参数校验失败或数据库操作异常