API接口文档：查询房屋信息
一、接口名称
查询房屋信息接口
二、接口描述
该接口用于查询小区内的房屋信息，支持分页查询，并可根据房屋ID、楼栋ID、单元ID等条件进行筛选。返回结果包含房屋基本信息、业主信息及统计数据。
三、接口路径
http://{ip}:{port}/app/room.queryRooms
四、请求方法
GET
五、请求头
| 参数名称 | 必填 | 类型 | 描述 |
|---|---|---|---|
Authorization |
是 | String | 用户认证Token（Base Token） |
app-id |
是 | String | 应用ID（系统分配） |
transaction-id |
是 | String | 请求流水号（格式：1000000000+YYYYMMDDhhmmss+6位序列） |
sign |
是 | String | 签名 |
req-time |
是 | String | 请求时间（格式：YYYYMMDDhhmmss） |
user-id |
是 | String | 当前用户ID（用于数据权限校验） |
六、请求参数
6.1 查询参数（Query Params）
| 参数名称 | 必填 | 类型 | 长度 | 描述 | 示例值 |
|---|---|---|---|---|---|
communityId |
是 | String | 30 | 小区ID | 2022081539020475 |
page |
否 | int | 11 | 当前页数（默认1） | 1 |
row |
否 | int | 11 | 每页行数（默认10，最大50） | 10 |
roomId |
否 | String | 30 | 房屋ID（精确匹配） | 752022082030880010 |
floorId |
否 | String | 30 | 楼栋ID（精确匹配） | 732022081690440002 |
unitId |
否 | String | 30 | 单元ID（精确匹配） | 742022082058950007 |
roomNum |
否 | String | - | 房屋编号（支持模糊查询） | 1001 |
roomType |
否 | String | - | 房屋类型（如商铺1010301） |
1010301 |
roomState |
否 | String | - | 房屋状态（多值用逗号分隔） | 2001,2002 |
flag |
否 | String | - | 查询模式（0：标准模式；1：楼栋-单元-房间号拆分模式） |
0 |
七、返回值
7.1 响应格式
{
"code": 0,
"msg": "成功",
"data": {
"page": 1,
"records": 1,
"total": 2,
"rooms": [
{
"roomId": "752022082030880010",
"roomName": "D-1-1001",
"roomNum": "1001",
"floorId": "732022081690440002",
"floorNum": "D",
"unitId": "742022082058950007",
"unitNum": "1",
"ownerId": "772022082070860017",
"ownerName": "张杰",
"idCard": "110***1234",
"link": "189****1447",
"startTime": "2022-09-03 18:50:53",
"endTime": "2037-01-01 00:00:00",
"state": "2001",
"stateName": "已入住",
"roomType": "1010301",
"roomSubType": "110",
"roomSubTypeName": "住宅",
"builtUpArea": "11.00",
"roomArea": "11.00",
"feeCoefficient": "1.00",
"roomRent": "0.00",
"remark": "11",
"roomAttrDto": [
{
"specName": "精装修",
"value": "20"
}
]
}
]
}
}
7.2 字段说明
| 字段名称 | 类型 | 描述 |
|---|---|---|
code |
int | 返回码（0成功，其他失败） |
msg |
String | 返回信息 |
data.page |
int | 当前页数 |
data.records |
int | 总页数 |
data.total |
int | 总数据量 |
data.rooms |
Array | 房屋列表 |
rooms.roomId |
String | 房屋ID |
rooms.roomName |
String | 房屋名称（如D-1-1001） |
rooms.ownerName |
String | 业主姓名（脱敏处理） |
rooms.link |
String | 业主电话（脱敏处理） |
rooms.stateName |
String | 房屋状态（如已入住） |
rooms.roomAttrDto |
Array | 房屋扩展属性（如装修类型） |
八、示例请求
GET /app/room.queryRooms?communityId=2022081539020475&page=1&row=10&roomType=1010301
Headers:
Authorization: Bearer xxxxxx
app-id: micro-community
transaction-id: 100000000020220801120000000001
sign: xxxxxx
req-time: 20220801120000
user-id: 123456
九、示例响应
{
"code": 0,
"msg": "成功",
"data": {
"page": 1,
"records": 1,
"total": 2,
"rooms": [
{
"roomId": "752022082030880010",
"roomName": "D-1-1001",
"ownerName": "张*",
"link": "189****1447",
"stateName": "已入住"
}
]
}
}
十、注意事项
- 数据权限：接口会根据
user-id校验用户是否有权限查询目标小区数据。 - 脱敏规则：业主身份证和手机号默认脱敏，需特定权限才能查看完整信息。
- 分页限制：单次查询最大行数为50，超过将报错。
- 商铺查询：若
roomType=1010301（商铺），需用flag=1模式拆分楼栋-房间号（如A-101）。
十一、业务逻辑
- 校验小区ID和分页参数。
- 根据用户权限过滤可访问的单元数据。
- 支持通过楼栋、单元、房间号组合查询（需
flag=1）。 - 关联查询业主信息并脱敏处理。
- 返回分页结果及房屋统计信息（如面积、租金等）。
文档版本：v1.0
最后更新：2023-10-10
作者：吴学文