wkc/ccdi

Fork 0

Files

wkc d08782ae9e 文件夹整理

2026-02-09 14:34:27 +08:00

18 KiB

Raw Blame History

中介黑名单管理 API 文档 v2.0

概述

中介黑名单管理模块提供个人和机构两类中介信息的增删改查、类型化模板下载和批量导入导出功能。

基础路径: /ccdi/intermediary

权限标识前缀: ccdi:intermediary

技术栈: Spring Boot 3 + MyBatis Plus + MySQL

API 接口列表

1. 查询中介黑名单列表

接口地址: GET /ccdi/intermediary/list

权限要求: ccdi:intermediary:list

请求参数:

参数名	类型	必填	说明
name	String	否	姓名/机构名称（模糊查询）
certificateNo	String	否	证件号/统一社会信用代码（精确查询）
intermediaryType	String	否	中介类型（1=个人, 2=机构）
pageNum	Integer	否	页码（默认1）
pageSize	Integer	否	每页数量（默认10）

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "id": "abc123",
      "name": "张三",
      "certificateNo": "110101199001011234",
      "intermediaryType": "1",
      "personType": "中介",
      "company": "XX公司",
      "dataSource": "MANUAL",
      "createTime": "2026-02-04 10:00:00",
      "updateTime": "2026-02-05 14:30:00"
    }
  ],
  "total": 1
}

响应字段说明:

字段名	类型	说明
id	String	ID（个人为bizId，实体为socialCreditCode）
name	String	姓名/机构名称
certificateNo	String	证件号/统一社会信用代码
intermediaryType	String	中介类型（1=个人, 2=实体）
personType	String	人员类型/实体
company	String	公司/机构名称
dataSource	String	数据来源（MANUAL=手动, IMPORT=导入, API=接口）
createTime	Date	创建时间
updateTime	Date	修改时间

2. 查询个人中介详情

接口地址: GET /ccdi/intermediary/person/{bizId}

权限要求: ccdi:intermediary:query

路径参数:

参数名	类型	必填	说明
bizId	String	是	人员业务ID

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "bizId": "abc123xyz456",
    "intermediaryType": "1",
    "name": "张三",
    "personType": "房产中介",
    "personSubType": "本人",
    "gender": "M",
    "idType": "身份证",
    "personId": "110101199001011234",
    "mobile": "13800138000",
    "wechatNo": "zhangsan_wx",
    "contactAddress": "北京市朝阳区XX路XX号",
    "company": "XX房产中介公司",
    "position": "经纪人",
    "socialCreditCode": "91110000XXXXXXXXXX",
    "relatedNumId": "rel123",
    "relationType": "配偶",
    "dataSource": "MANUAL",
    "remark": "测试数据",
    "createTime": "2026-02-04 10:00:00"
  }
}

响应字段说明:

字段名	类型	说明
bizId	String	人员业务ID
intermediaryType	String	中介类型（固定为"1"）
name	String	姓名
personType	String	人员类型（房产中介、贷款中介等）
personSubType	String	人员子类型（本人、配偶、父亲等）
gender	String	性别（M=男, F=女, O=其他）
idType	String	证件类型（身份证、护照等）
personId	String	证件号码
mobile	String	手机号码
wechatNo	String	微信号
contactAddress	String	联系地址
company	String	所在公司
position	String	职位
socialCreditCode	String	企业统一信用码
relatedNumId	String	关联人员ID
relationType	String	关联关系（配偶、父子、母女等）
dataSource	String	数据来源
remark	String	备注
createTime	Date	创建时间

3. 查询实体中介详情

接口地址: GET /ccdi/intermediary/entity/{socialCreditCode}

权限要求: ccdi:intermediary:query

路径参数:

参数名	类型	必填	说明
socialCreditCode	String	是	统一社会信用代码

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "socialCreditCode": "91110000XXXXXXXXXX",
    "intermediaryType": "2",
    "enterpriseName": "XX中介公司",
    "enterpriseType": "有限责任公司",
    "enterpriseNature": "民企",
    "industryClass": "房地产",
    "industryName": "房地产业",
    "establishDate": "2020-01-01",
    "registerAddress": "北京市朝阳区XX路XX号",
    "legalRepresentative": "张三",
    "legalCertType": "身份证",
    "legalCertNo": "110101199001011234",
    "shareholder1": "李四",
    "shareholder2": "王五",
    "shareholder3": "赵六",
    "shareholder4": null,
    "shareholder5": null,
    "dataSource": "MANUAL",
    "remark": "测试数据",
    "createTime": "2026-02-04 10:00:00"
  }
}

响应字段说明:

字段名	类型	说明
socialCreditCode	String	统一社会信用代码
intermediaryType	String	中介类型（固定为"2"）
enterpriseName	String	机构名称
enterpriseType	String	主体类型
enterpriseNature	String	企业性质
industryClass	String	行业分类
industryName	String	所属行业
establishDate	Date	成立日期
registerAddress	String	注册地址
legalRepresentative	String	法定代表人
legalCertType	String	法定代表人证件类型
legalCertNo	String	法定代表人证件号码
shareholder1-5	String	股东信息
dataSource	String	数据来源
remark	String	备注
createTime	Date	创建时间

4. 新增个人中介

接口地址: POST /ccdi/intermediary/person

权限要求: ccdi:intermediary:add

请求体:

{
  "name": "张三",
  "personType": "房产中介",
  "personSubType": "本人",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan_wx",
  "contactAddress": "北京市朝阳区XX路XX号",
  "company": "XX房产中介公司",
  "position": "经纪人",
  "socialCreditCode": "91110000XXXXXXXXXX",
  "relatedNumId": "rel123",
  "relationType": "配偶",
  "remark": "测试数据"
}

字段说明:

字段名	类型	必填	说明
name	String	是	姓名（1-100字符）
personId	String	是	证件号码（不超过50字符）
personType	String	否	人员类型（枚举值，见下文）
personSubType	String	否	人员子类型（枚举值，见下文）
gender	String	否	性别（M=男, F=女, O=其他）
idType	String	否	证件类型（枚举值，见下文）
mobile	String	否	手机号码（不超过20字符）
wechatNo	String	否	微信号（不超过50字符）
contactAddress	String	否	联系地址（不超过200字符）
company	String	否	所在公司（不超过200字符）
position	String	否	职位（不超过100字符）
socialCreditCode	String	否	企业统一信用码（不超过50字符）
relatedNumId	String	否	关联人员ID（不超过50字符）
relationType	String	否	关联关系（枚举值，见下文）
remark	String	否	备注（不超过500字符）

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

5. 新增实体中介

接口地址: POST /ccdi/intermediary/entity

权限要求: ccdi:intermediary:add

请求体:

{
  "enterpriseName": "XX中介公司",
  "socialCreditCode": "91110000XXXXXXXXXX",
  "enterpriseType": "有限责任公司",
  "enterpriseNature": "民企",
  "industryClass": "房地产",
  "industryName": "房地产业",
  "establishDate": "2020-01-01",
  "registerAddress": "北京市朝阳区XX路XX号",
  "legalRepresentative": "张三",
  "legalCertType": "身份证",
  "legalCertNo": "110101199001011234",
  "shareholder1": "李四",
  "shareholder2": "王五",
  "shareholder3": "赵六",
  "shareholder4": null,
  "shareholder5": null,
  "remark": "测试数据"
}

字段说明:

字段名	类型	必填	说明
enterpriseName	String	是	机构名称（1-200字符）
socialCreditCode	String	是	统一社会信用代码（不超过50字符）
enterpriseType	String	否	主体类型（枚举值，见下文）
enterpriseNature	String	否	企业性质（枚举值，见下文）
industryClass	String	否	行业分类（不超过100字符）
industryName	String	否	所属行业（不超过100字符）
establishDate	Date	否	成立日期（yyyy-MM-dd）
registerAddress	String	否	注册地址（不超过500字符）
legalRepresentative	String	否	法定代表人（不超过100字符）
legalCertType	String	否	法定代表人证件类型（枚举值）
legalCertNo	String	否	法定代表人证件号码（不超过50字符）
shareholder1-5	String	否	股东信息（每个不超过100字符）
remark	String	否	备注（不超过500字符）

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

6. 修改个人中介

接口地址: PUT /ccdi/intermediary/person

权限要求: ccdi:intermediary:edit

请求体:

{
  "bizId": "abc123xyz456",
  "name": "张三",
  "personType": "房产中介",
  "personSubType": "本人",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan_wx",
  "contactAddress": "北京市朝阳区XX路XX号",
  "company": "XX房产中介公司",
  "position": "经纪人",
  "socialCreditCode": "91110000XXXXXXXXXX",
  "relatedNumId": "rel123",
  "relationType": "配偶",
  "remark": "测试数据"
}

字段说明: 与新增接口相同，但 bizId 为必填项。

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

7. 修改实体中介

接口地址: PUT /ccdi/intermediary/entity

权限要求: ccdi:intermediary:edit

请求体:

{
  "socialCreditCode": "91110000XXXXXXXXXX",
  "enterpriseName": "XX中介公司",
  "enterpriseType": "有限责任公司",
  "enterpriseNature": "民企",
  "industryClass": "房地产",
  "industryName": "房地产业",
  "establishDate": "2020-01-01",
  "registerAddress": "北京市朝阳区XX路XX号",
  "legalRepresentative": "张三",
  "legalCertType": "身份证",
  "legalCertNo": "110101199001011234",
  "shareholder1": "李四",
  "shareholder2": "王五",
  "shareholder3": "赵六",
  "shareholder4": null,
  "shareholder5": null,
  "remark": "测试数据"
}

字段说明: 与新增接口相同。

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

8. 删除中介

接口地址: DELETE /ccdi/intermediary/{ids}

权限要求: ccdi:intermediary:remove

路径参数:

参数名	类型	必填	说明
ids	String[]	是	ID数组（个人为bizId，实体为socialCreditCode）

示例: /ccdi/intermediary/abc123,91110000XXXXXXXXXX

响应示例:

{
  "code": 200,
  "msg": "操作成功"
}

9. 校验人员ID唯一性

接口地址: GET /ccdi/intermediary/checkPersonIdUnique

权限要求: 无

请求参数:

参数名	类型	必填	说明
personId	String	是	证件号码
bizId	String	否	排除的人员ID（修改时使用）

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": true
}

响应说明: true 表示唯一，false 表示已存在。

10. 校验统一社会信用代码唯一性

接口地址: GET /ccdi/intermediary/checkSocialCreditCodeUnique

权限要求: 无

请求参数:

参数名	类型	必填	说明
socialCreditCode	String	是	统一社会信用代码
excludeId	String	否	排除的ID（修改时使用）

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": true
}

响应说明: true 表示唯一，false 表示已存在。

枚举接口

获取人员类型选项

接口地址: GET /ccdi/enum/indivType

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "房产中介", "label": "房产中介" },
    { "value": "贷款中介", "label": "贷款中介" },
    { "value": "职业背债人", "label": "职业背债人" },
    { "value": "担保中介", "label": "担保中介" },
    { "value": "评估中介", "label": "评估中介" }
  ]
}

获取人员子类型选项

接口地址: GET /ccdi/enum/indivSubType

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "本人", "label": "本人" },
    { "value": "配偶", "label": "配偶" },
    { "value": "父亲", "label": "父亲" },
    { "value": "母亲", "label": "母亲" },
    { "value": "兄弟", "label": "兄弟" },
    { "value": "姐妹", "label": "姐妹" },
    { "value": "子女", "label": "子女" }
  ]
}

获取性别选项

接口地址: GET /ccdi/enum/gender

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "M", "label": "男" },
    { "value": "F", "label": "女" },
    { "value": "O", "label": "其他" }
  ]
}

获取证件类型选项

接口地址: GET /ccdi/enum/certType

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "身份证", "label": "身份证" },
    { "value": "护照", "label": "护照" },
    { "value": "港澳通行证", "label": "港澳通行证" },
    { "value": "台湾通行证", "label": "台湾通行证" }
  ]
}

获取关联关系选项

接口地址: GET /ccdi/enum/relationType

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "配偶", "label": "配偶" },
    { "value": "父子", "label": "父子" },
    { "value": "母女", "label": "母女" },
    { "value": "兄弟", "label": "兄弟" },
    { "value": "姐妹", "label": "姐妹" },
    { "value": "亲属", "label": "亲属" },
    { "value": "朋友", "label": "朋友" },
    { "value": "同事", "label": "同事" }
  ]
}

获取主体类型选项

接口地址: GET /ccdi/enum/corpType

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "有限责任公司", "label": "有限责任公司" },
    { "value": "股份有限公司", "label": "股份有限公司" },
    { "value": "个体工商户", "label": "个体工商户" },
    { "value": "合伙企业", "label": "合伙企业" },
    { "value": "个人独资企业", "label": "个人独资企业" }
  ]
}

获取企业性质选项

接口地址: GET /ccdi/enum/corpNature

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "国企", "label": "国企" },
    { "value": "民企", "label": "民企" },
    { "value": "外企", "label": "外企" },
    { "value": "合资", "label": "合资" }
  ]
}

获取数据来源选项

接口地址: GET /ccdi/enum/dataSource

权限要求: 无

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "value": "MANUAL", "label": "手动录入" },
    { "value": "SYSTEM", "label": "系统同步" },
    { "value": "IMPORT", "label": "批量导入" },
    { "value": "API", "label": "接口获取" }
  ]
}

错误码说明

HTTP状态码	错误码	说明
200	200	操作成功
401	401	未授权，请先登录
403	403	无权限访问
500	500	服务器内部错误

业务错误信息

错误信息	说明
姓名不能为空	新增/修改时姓名为空
证件号码不能为空	新增时证件号码为空
该证件号已存在	新增/导入时证件号重复
该统一社会信用代码已存在	新增/导入时信用代码重复
姓名长度不能超过100个字符	姓名超长
证件号长度不能超过50个字符	证件号超长

测试账号

用户名: admin
密码: admin123

获取Token: 调用 POST /login/test 接口获取Token，后续请求在 Header 中添加：

Authorization: Bearer {token}

更新日志

版本	日期	说明
2.0.0	2026-02-05	统一字段命名，使用接口枚举，更新文档与实际代码一致
1.3.0	2026-01-29	新增接口分离：个人/机构专用新增接口
1.2.0	2026-01-29	修改接口分离：个人/机构专用修改接口
1.1.0	2026-01-29	添加字典下拉框功能
1.0.0	2026-01-29	初始版本

注意事项

中介类型字段:
- 个人中介：intermediaryType = "1"
- 实体中介：intermediaryType = "2"
枚举值使用:
- 所有下拉选项字段应使用枚举接口返回的 value 值
- 不要硬编码或使用字典表的 dictValue
数据来源字段:
- 手动录入：MANUAL
- 系统同步：SYSTEM
- 批量导入：IMPORT
- 接口获取：API
分页排序:
- 列表查询默认按 updateTime 降序排列
- 使用 MyBatis Plus 分页插件
ID字段:
- 个人中介使用 bizId 作为唯一标识
- 实体中介使用 socialCreditCode 作为唯一标识
批量操作:
- 删除接口支持同时删除个人和实体中介
- 根据ID长度自动判断类型（个人ID较长）

18 KiB Raw Blame History Unescape Escape

中介黑名单管理 API 文档 v2.0

概述

API 接口列表

1. 查询中介黑名单列表

2. 查询个人中介详情

3. 查询实体中介详情

4. 新增个人中介

5. 新增实体中介

6. 修改个人中介

7. 修改实体中介

8. 删除中介

9. 校验人员ID唯一性

10. 校验统一社会信用代码唯一性

枚举接口

获取人员类型选项

获取人员子类型选项

获取性别选项

获取证件类型选项

获取关联关系选项

获取主体类型选项

获取企业性质选项

获取数据来源选项

错误码说明

业务错误信息

测试账号

更新日志

注意事项

18 KiB

Raw Blame History