HC小区接口文档

基础接口

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

资产接口

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

业主接口

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

费用接口

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

工单接口

报修接口 投诉接口

API接口文档：查询费用信息

1. 接口名称

查询费用信息接口

2. 接口描述

根据小区ID、房屋编号、业主ID等条件查询费用信息，支持分页查询。返回的费用信息包括费用明细、欠费金额、缴费周期等。

3. 接口路径

http://{ip}:{port}/app/fee.listFee（Java110Cmd 服务编码）

4. 请求方法

POST（基于Cmd框架，实际请求方法取决于调用方式）

5. 请求头参数

参数名称 必填 类型 描述
Authorization 是 String 用户认证Token（Base Token）
app-id 是 String 应用ID（系统分配）
transaction-id 是 String 请求流水号（唯一，格式：1000000000+YYYYMMDDhhmmss+6位序列）
sign 是 String 签名（防篡改校验）
req-time 是 String 请求时间（YYYYMMDDhhmmss）

6. 请求参数

6.1 查询参数（JSON Body）

参数名称 必填 类型 描述 示例值
communityId 是 String 小区ID "123456789"
roomNum 否 String 房屋编号（格式：楼栋号-单元号-房间号，如 1-2-101） "1-2-101"
payerObjId 否 String 付费对象ID（房屋ID或车辆ID） "room_001"
payerObjIds 否 String 多付费对象ID（逗号分隔） "room_001,room_002"
ownerId 否 String 业主ID "owner_001"
page 否 Integer 当前页码（默认1） 1
row 否 Integer 每页条数（默认10） 10

注：

  • roomNum 和 payerObjId 至少填一个，用于定位房屋。
  • 若传 payerObjIds，则忽略 payerObjId，支持批量查询多个房屋的费用。

7. 返回值

7.1 响应格式（JSON）

参数名称 类型 描述
code String 返回码（0成功，其他失败）
msg String 返回信息
fees Object 数据体（见下方 ApiFeeVo 结构）

7.2 数据体结构（ApiFeeVo）

字段名 类型 描述
total Integer 总记录数
records Integer 总页数
fees List 费用明细列表（见下表）

7.3 费用明细（ApiFeeDataVo）

字段名 类型 描述
feeId String 费用ID
feeName String 费用名称（如物业费、水费）
feeTypeCd String 费用类型编码
payerObjType String 付费对象类型（房屋/车辆）
feePrice Double 单价（元/㎡或元/月）
feeTotalPrice Double 总金额（含欠费）
amountOwed Double 欠费金额
deadlineTime Date 缴费截止时间（格式：yyyy-MM-dd）
state String 状态（未缴费/已缴费）
receivedAmountSwitch String 实收款输入框开关（1启用，0禁用）
offlinePayFeeSwitch String 线下支付开关（1启用，0禁用）

8. 示例请求

{
  "communityId": "123456789",
  "roomNum": "1-2-101",
  "page": 1,
  "row": 10
}

9. 示例响应

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

    "total": 2,
    "records": 1,
    "fees": [
      {
        "feeId": "fee_001",
        "feeName": "物业费",
        "feeTypeCd": "1001",
        "payerObjType": "ROOM",
        "feePrice": 2.5,
        "feeTotalPrice": 300.0,
        "amountOwed": 150.0,
        "deadlineTime": "2023-12-31",
        "state": "未缴费",
        "receivedAmountSwitch": "1",
        "offlinePayFeeSwitch": "0"
      },
      {
        "feeId": "fee_002",
        "feeName": "水费",
        "feeTypeCd": "2001",
        "payerObjType": "ROOM",
        "feePrice": 5.0,
        "feeTotalPrice": 60.0,
        "amountOwed": 0.0,
        "deadlineTime": "2023-11-30",
        "state": "已缴费",
        "receivedAmountSwitch": "1",
        "offlinePayFeeSwitch": "0"
      }
    ]
  
}

10. 业务逻辑说明

  1. 参数校验：

    • 校验小区ID必填，房屋编号格式为 楼栋-单元-房间（如 1-2-101）。
    • 校验当前用户是否有权限查询目标房屋的费用（通过 ownerGetDataCheckImpl 实现）。

  2. 数据查询：

    • 根据 payerObjId 或 roomNum 查询房屋信息，转换为房屋ID。
    • 调用 feeInnerServiceSMOImpl.queryFees 查询费用明细，支持分页。

  3. 费用计算：

    • 动态计算欠费金额（amountOwed）和截止时间（deadlineTime）。
    • 处理租金递增、账单模式等特殊场景。

  4. 开关控制：

    • 从小区配置或全局配置读取 线下支付开关 和 实收款输入框开关。

11. 注意事项

  • 房屋编号需严格按 楼栋-单元-房间 格式传递，否则报错。
  • 业主ID校验失败时返回空列表（无权限访问）。