HC小区接口文档

基础接口

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

资产接口

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

业主接口

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

费用接口

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

工单接口

报修接口 投诉接口

API接口文档：结束费用

一、接口名称

结束费用接口

二、接口描述

用于将指定费用标记为“已结束”状态，并更新相关费用月报和欠费信息。

三、接口路径

http://{domain}/app/fee.finishFee

四、请求方法

POST

五、请求头

参数名称 必填 类型 描述
Authorization 是 String 用户认证 Token，通过登录接口获取 Base Token
app-id 是 String 应用 ID，由系统 dev 账户分配
transaction-id 是 String 请求流水号，格式：1000000000 + YYYYMMDDhhmmss + 6位序列（不可重复）
sign 是 String 签名，用于请求合法性校验
req-time 是 String 请求时间，格式：YYYYMMDDhhmmss

六、请求参数

6.1 请求体参数（JSON）
参数名称 必填 类型 描述 示例值
communityId 是 String 小区 ID "123456789"
feeId 是 String 费用 ID "fee001"

请求体示例： 

{
  "communityId": "123456789",
  "feeId": "fee001"
}

七、返回值

7.1 通用响应结构
参数名称 必填 类型 描述
code 是 String 返回码，0 表示成功，其他失败
msg 是 String 返回信息，如错误原因
data 否 Object 返回数据（本接口无返回数据）
7.2 状态码说明
状态码 描述
0 操作成功
1 参数校验失败（如缺少必填字段）
2 费用不存在或查询到多条记录
3 结束费用失败（数据库更新异常）

八、示例请求

请求头示例： 

Authorization: Bearer xxxxxx
app-id: hc_micro_community
transaction-id: 100000000020231015142359000001
sign: xxxxxx
req-time: 20231015142359

请求体示例： 

{
  "communityId": "123456789",
  "feeId": "fee001"
}

九、示例响应

成功响应： 

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

失败响应（费用不存在）： 

{
  "code": "2",
  "msg": "未查询到费用信息 或查询到多条",
  "data": null
}

十、业务逻辑说明

  1. 参数校验

    • 校验 communityId 和 feeId 是否为空。
    • 查询费用信息，确保费用存在且唯一。

  2. 数据库操作

    • 更新费用状态为 STATE_FINISH（标记为结束）。
    • 删除关联的月费用数据（payFeeMonthImpl.deleteFeeMonth）。
    • 重新生成月费用（payFeeMonthImpl.doGeneratorOrRefreshFeeMonth）。
    • 删除欠费记录（reportOweFeeInnerServiceSMOImpl.deleteReportOweFee）。

  3. 异常处理

    • 若费用不存在或数据库更新失败，抛出 CmdException 并返回对应错误码。

十一、注意事项

  • 该接口会触发费用状态的变更和关联数据的清理，需谨慎调用。
  • 调用前需确保 feeId 对应的费用未被其他操作锁定。