ccdi/assets/api-docs/api/中介黑名单管理API文档-v2.0.md

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

概述

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

基础路径: /ccdi/intermediary

权限标识前缀: ccdi:intermediary

文档版本: v2.0

更新日期: 2026-02-04

---

API 接口列表

1. 查询中介列表

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

权限要求: ccdi:intermediary:list

请求参数 (Query Params):

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

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "bizId": "I202602040001",
      "name": "张三",
      "certificateNo": "110101199001011234",
      "intermediaryType": "1",
      "intermediaryTypeName": "个人",
      "status": "0",
      "statusName": "正常",
      "remark": "测试数据",
      "createBy": "admin",
      "createTime": "2026-02-04 10:00:00"
    }
  ],
  "total": 1
}

响应字段说明:

字段名	类型	说明
bizId	String	业务ID
name	String	姓名/机构名称
certificateNo	String	证件号/统一社会信用代码
intermediaryType	String	中介类型(1=个人, 2=实体)
intermediaryTypeName	String	中介类型名称
status	String	状态(0=正常, 1=停用)
statusName	String	状态名称
remark	String	备注
createBy	String	创建人
createTime	String	创建时间

---

2. 查询个人中介详情

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

权限要求: ccdi:intermediary:query

路径参数:

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

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "bizId": "I202602040001",
    "name": "张三",
    "certificateNo": "110101199001011234",
    "intermediaryType": "1",
    "intermediaryTypeName": "个人",
    "status": "0",
    "statusName": "正常",
    "personType": "中介",
    "personSubType": "本人",
    "relationType": "正常",
    "gender": "M",
    "genderName": "男",
    "idType": "身份证",
    "personId": "110101199001011234",
    "mobile": "13800138000",
    "wechatNo": "zhangsan",
    "contactAddress": "北京市朝阳区",
    "company": "XX公司",
    "socialCreditCode": "91110000123456789X",
    "position": "经纪人",
    "relatedNumId": "",
    "relation": "",
    "remark": "测试数据",
    "createBy": "admin",
    "createTime": "2026-02-04 10:00:00"
  }
}

---

3. 查询实体中介详情

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

权限要求: ccdi:intermediary:query

路径参数:

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

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "bizId": "I202602040002",
    "name": "XX中介公司",
    "certificateNo": "91110000123456789X",
    "intermediaryType": "2",
    "intermediaryTypeName": "实体",
    "status": "0",
    "statusName": "正常",
    "enterpriseName": "XX中介公司",
    "socialCreditCode": "91110000123456789X",
    "enterpriseType": "有限责任公司",
    "enterpriseNature": "民企",
    "industryClass": "房地产",
    "industryName": "房地产业",
    "establishDate": "2020-01-01",
    "registerAddress": "北京市朝阳区",
    "legalRepresentative": "张三",
    "legalCertType": "身份证",
    "legalCertNo": "110101199001011234",
    "shareholder1": "李四",
    "shareholder2": "王五",
    "shareholder3": "",
    "shareholder4": "",
    "shareholder5": "",
    "remark": "测试数据",
    "createBy": "admin",
    "createTime": "2026-02-04 10:00:00"
  }
}

---

4. 新增个人中介

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

权限要求: ccdi:intermediary:add

请求体 (application/json):

{
  "name": "张三",
  "personType": "中介",
  "personSubType": "本人",
  "relationType": "正常",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan",
  "contactAddress": "北京市朝阳区",
  "company": "XX公司",
  "socialCreditCode": "91110000123456789X",
  "position": "经纪人",
  "relatedNumId": "",
  "relation": "",
  "remark": "测试数据"
}

字段说明:

字段名	类型	必填	说明
name	String	是	姓名(最大100字符)
personId	String	是	证件号码(最大50字符)
personType	String	否	人员类型
personSubType	String	否	人员子类型
relationType	String	否	关系类型
gender	String	否	性别(M=男, F=女, O=其他)
idType	String	否	证件类型
mobile	String	否	手机号码(最大20字符)
wechatNo	String	否	微信号(最大50字符)
contactAddress	String	否	联系地址(最大200字符)
company	String	否	所在公司(最大200字符)
socialCreditCode	String	否	企业统一信用码(最大50字符)
position	String	否	职位(最大100字符)
relatedNumId	String	否	关联人员ID(最大50字符)
relation	String	否	关联关系(最大50字符)
remark	String	否	备注(最大500字符)

响应示例:

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

---

5. 新增实体中介

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

权限要求: ccdi:intermediary:add

请求体 (application/json):

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

字段说明:

字段名	类型	必填	说明
enterpriseName	String	是	机构名称(最大200字符)
socialCreditCode	String	否	统一社会信用代码(最大50字符)
enterpriseType	String	否	主体类型(最大50字符)
enterpriseNature	String	否	企业性质(最大50字符)
industryClass	String	否	行业分类(最大100字符)
industryName	String	否	所属行业(最大100字符)
establishDate	Date	否	成立日期
registerAddress	String	否	注册地址(最大500字符)
legalRepresentative	String	否	法定代表人(最大100字符)
legalCertType	String	否	法定代表人证件类型(最大50字符)
legalCertNo	String	否	法定代表人证件号码(最大50字符)
shareholder1-5	String	否	股东信息(每个最大100字符)
remark	String	否	备注(最大500字符)

响应示例:

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

---

6. 修改个人中介

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

权限要求: ccdi:intermediary:edit

请求体 (application/json):

{
  "bizId": "I202602040001",
  "name": "张三",
  "personType": "中介",
  "personSubType": "本人",
  "relationType": "正常",
  "gender": "M",
  "idType": "身份证",
  "personId": "110101199001011234",
  "mobile": "13800138000",
  "wechatNo": "zhangsan",
  "contactAddress": "北京市朝阳区",
  "company": "XX公司",
  "socialCreditCode": "91110000123456789X",
  "position": "经纪人",
  "relatedNumId": "",
  "relation": "",
  "remark": "测试数据"
}

字段说明: 与新增个人中介相同,bizId为必填项

响应示例:

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

---

7. 修改实体中介

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

权限要求: ccdi:intermediary:edit

请求体 (application/json):

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

字段说明: 与新增实体中介相同,socialCreditCode为必填项

响应示例:

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

---

8. 删除中介

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

权限要求: ccdi:intermediary:remove

路径参数:

参数名	类型	必填	说明
ids	String[]	是	业务ID数组(逗号分隔)

响应示例:

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

---

9. 校验人员ID唯一性

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

权限要求: 无

请求参数:

参数名	类型	必填	说明
personId	String	是	证件号码
bizId	String	否	排除的业务ID(修改时使用)

响应示例:

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

data字段说明: true=唯一可用, false=已存在

---

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

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

权限要求: 无

请求参数:

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

响应示例:

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

data字段说明: true=唯一可用, false=已存在

---

11. 下载个人中介导入模板

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

权限要求: 无

响应: Excel模板文件下载

Excel格式说明:

Sheet1: 个人中介信息 | 姓名 | 人员类型 | 人员子类型 | 关系类型 | 性别▼ | 证件类型▼ | 证件号码 | 手机号码 | 微信号 | 联系地址 | 所在公司 |

企业统一信用码	职位	关联人员ID	关联关系	备注
张三	中介	本人	正常	男	身份证	110101199001011234	13800138000	zhangsan	北京市朝阳区	XX公司
91110000XXXXXXXXXX	经纪人	-	-	测试

注: 带▼标记的列包含下拉框,选项来自字典

---

12. 下载实体中介导入模板

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

权限要求: 无

响应: Excel模板文件下载

Excel格式说明:

Sheet1: 实体中介信息 | 机构名称 | 统一社会信用代码 | 主体类型▼ | 企业性质▼ | 行业分类 | 所属行业 | 成立日期 | 注册地址 | 法定代表人 |

法定代表人证件类型	法定代表人证件号码	股东1	股东2	股东3	股东4	股东5	备注
XX公司	91110000XXXXXXXXXX	有限责任公司	民企	房地产	房地产业	2020-01-01	北京市朝阳区	张三	身份证
110101199001011234	李四	王五	-	-	-	-

---

13. 导入个人中介数据

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

权限要求: ccdi:intermediary:import

请求参数 (multipart/form-data):

参数名	类型	必填	说明
file	File	是	Excel文件
updateSupport	Boolean	否	是否更新已存在数据(默认false)

响应示例:

{
  "code": 200,
  "msg": "恭喜您,数据已全部导入成功!共10条"
}

---

14. 导入实体中介数据

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

权限要求: ccdi:intermediary:import

请求参数 (multipart/form-data):

参数名	类型	必填	说明
file	File	是	Excel文件
updateSupport	Boolean	否	是否更新已存在数据(默认false)

响应示例:

{
  "code": 200,
  "msg": "恭喜您,数据已全部导入成功!共10条"
}

---

字典数据说明

导入模板中的下拉框选项来自系统字典管理,相关字典类型:

字典类型	字典名称	用途
ccdi_indiv_gender	个人中介性别	个人中介模板性别下拉框
ccdi_certificate_type	证件类型	个人中介模板证件类型下拉框
ccdi_entity_type	主体类型	机构中介模板主体类型下拉框
ccdi_enterprise_nature	企业性质	机构中介模板企业性质下拉框
ccdi_data_source	数据来源	数据来源字段映射

---

错误码说明

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

---

业务错误信息

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

---

测试账号

• 用户名: admin
• 密码: admin123

测试前请先调用 /login/test 接口获取Token。

---

更新日志

版本	日期	说明
1.0.0	2026-01-29	初始版本,支持个人和机构分类管理
1.1.0	2026-01-29	添加字典下拉框功能,分离个人/机构模板
1.2.0	2026-01-29	修改接口分离:新增个人/机构专用修改接口,修复中介类型修改问题
1.3.0	2026-01-29	新增接口分离:新增个人/机构专用新增接口,统一接口设计
2.0.0	2026-02-04	重构版本:使用MyBatis Plus,分离DTO/VO,统一业务ID(bizId),优化查询接口

---

主要变更说明 (v2.0)

架构变更

• 使用MyBatis Plus替代原生MyBatis
• 分离DTO(请求)和VO(响应)对象
• 统一使用业务ID(bizId)作为主键

接口变更

• 查询详情接口分离为个人和实体两个接口
• 新增接口分离为个人和实体两个接口
• 修改接口分离为个人和实体两个接口
• 新增唯一性校验接口

数据模型变更

• 个人中介使用personId作为证件号字段
• 实体中介使用socialCreditCode作为统一社会信用代码字段
• 删除了intermediaryId,统一使用bizId

查询功能增强

• 支持按中介类型查询
• 支持按姓名/机构名称模糊查询
• 支持按证件号/统一社会信用代码精确查询