wkc/ccdi

Fork 0

Files

wkc 02249c402e 文件夹整理

2026-02-09 14:28:25 +08:00

16 KiB

Raw Blame History

中介黑名单管理 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

查询功能增强

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

16 KiB Raw Blame History

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

概述

API 接口列表

1. 查询中介列表

2. 查询个人中介详情

3. 查询实体中介详情

4. 新增个人中介

5. 新增实体中介

6. 修改个人中介

7. 修改实体中介

8. 删除中介

9. 校验人员ID唯一性

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

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

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

13. 导入个人中介数据

14. 导入实体中介数据

字典数据说明

错误码说明

业务错误信息

测试账号

更新日志

主要变更说明 (v2.0)

架构变更

接口变更

数据模型变更

查询功能增强

16 KiB

Raw Blame History