信息对比

# e签宝身份信息比对接口文档

## 1. 文档说明

本文档描述 `esign` 插件提供的 e签宝身份信息比对转发接口，以及本地 Redis 缓存清理接口。

- 插件路由前缀：`/esign`
- 请求方式：`POST`
- 请求格式：`application/json`
- 比对接口均为透传接口：请求 body 原样转发至 e签宝上游接口，响应字符串原样返回给调用方。
- 本地不做字段必填、格式、业务语义校验，参数错误以 e签宝响应为准。
- 比对结果会写入 Redis 缓存，有效期 3 天。

## 2. 公共返回说明

身份比对接口的返回内容为 e签宝原始响应。常见结构如下：

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| code | int | 是 | e签宝响应结果码，`0` 通常表示比对通过 |
| message | string | 是 | e签宝响应结果描述 |
| data | object | 否 | 响应数据 |
| data.verifyId | string | 否 | 信息比对业务 ID |

企业 3/4 要素接口在开通对应能力后，`data` 中可能额外返回 `errCode`、`errMsg`、`compareDetails` 等字段，具体以 e签宝实际响应为准。

## 3. 缓存说明

身份比对接口启用 Redis 缓存：

| 项目 | 说明 |
| --- | --- |
| 缓存类型 | Redis |
| 缓存有效期 | 3 天 |
| 缓存命中 | 直接返回已缓存的 e签宝响应字符串 |
| 缓存 key 前缀 | `esign:identity:` |
| 缓存 key 组成 | `esign:identity:<本地接口路径>:<按字段名排序后的请求字段>` |

缓存 key 示例：

```text
esign:identity:/identity/individual/bank3Factors:cardNo=6222000000000000:idNo=320000000000000000:name=张三
```

> 注意：为了支持按姓名、身份证号、银行卡号等关键字清理缓存，缓存 key 会包含请求字段值。

## 4. 接口列表

| 接口名称 | 本地路径 | e签宝上游路径 |
| --- | --- | --- |
| 个人 2 要素信息比对 | `/esign/identity/individual/base` | `/v2/identity/verify/individual/base` |
| 个人运营商 2 要素信息比对 | `/esign/identity/individual/telecom2Factors` | `/v2/identity/verify/individual/telecom2Factors` |
| 个人运营商 3 要素信息比对 | `/esign/identity/individual/telecom3Factors` | `/v2/identity/verify/individual/telecom3Factors` |
| 个人运营商 3 要素信息比对（详情版） | `/esign/identity/individual/telecom3Factors/detail` | `/v2/identity/verify/individual/telecom3Factors/detail` |
| 个人银行卡 3 要素信息比对 | `/esign/identity/individual/bank3Factors` | `/v2/identity/verify/individual/bank3Factors` |
| 个人银行卡 3 要素信息比对（详情版） | `/esign/identity/individual/bank3Factors/detail` | `/v2/identity/verify/individual/bank3Factors/detail` |
| 个人银行卡 4 要素信息比对 | `/esign/identity/individual/bank4Factors` | `/v2/identity/verify/individual/bank4Factors` |
| 个人银行卡 4 要素信息比对（详情版） | `/esign/identity/individual/bank4Factors/detail` | `/v2/identity/verify/individual/bank4Factors/detail` |
| 个人银行卡 4 要素信息比对（国际版） | `/esign/identity/individual/bank4Factors/international` | `/v2/identity/verify/individual/bank4Factors/international` |
| 企业 3 要素信息比对 | `/esign/identity/organization/enterprise/bureau3Factors` | `/v2/identity/verify/organization/enterprise/bureau3Factors` |
| 企业 4 要素信息比对 | `/esign/identity/organization/enterprise/bureau4Factors` | `/v2/identity/verify/organization/enterprise/bureau4Factors` |
| 身份比对缓存清理 | `/esign/identity/cache/clear` | 本地接口，不转发 e签宝 |

## 5. 个人 2 要素信息比对

### 5.1 接口地址

```http
POST /esign/identity/individual/base
```

### 5.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| idNo | string | 是 | 身份证件号码，支持大陆二代身份证、港澳台居民居住证 |

### 5.3 请求示例

```json
{
  "name": "张三",
  "idNo": "320000000000000000"
}
```

### 5.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 6. 个人运营商 2 要素信息比对

### 6.1 接口地址

```http
POST /esign/identity/individual/telecom2Factors
```

### 6.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| mobileNo | string | 是 | 手机号（中国大陆 3 大运营商） |

### 6.3 请求示例

```json
{
  "name": "张三",
  "mobileNo": "18800000000"
}
```

### 6.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 7. 个人运营商 3 要素信息比对

### 7.1 接口地址

```http
POST /esign/identity/individual/telecom3Factors
```

### 7.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| idNo | string | 是 | 大陆二代身份证号 |
| mobileNo | string | 是 | 中国大陆手机号 |

### 7.3 请求示例

```json
{
  "name": "张三",
  "idNo": "320000000000000000",
  "mobileNo": "18800000000"
}
```

### 7.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 8. 个人运营商 3 要素信息比对（详情版）

### 8.1 接口地址

```http
POST /esign/identity/individual/telecom3Factors/detail
```

### 8.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| idNo | string | 是 | 大陆二代身份证号 |
| mobileNo | string | 是 | 中国大陆手机号 |

### 8.3 请求示例

```json
{
  "name": "张三",
  "idNo": "320000000000000000",
  "mobileNo": "18800000000"
}
```

### 8.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 9. 个人银行卡 3 要素信息比对

### 9.1 接口地址

```http
POST /esign/identity/individual/bank3Factors
```

### 9.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| idNo | string | 是 | 大陆二代身份证号 |
| cardNo | string | 是 | 银行卡号 |

### 9.3 请求示例

```json
{
  "name": "张三",
  "idNo": "320000000000000000",
  "cardNo": "6222000000000000"
}
```

### 9.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 10. 个人银行卡 3 要素信息比对（详情版）

### 10.1 接口地址

```http
POST /esign/identity/individual/bank3Factors/detail
```

### 10.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| idNo | string | 是 | 大陆二代身份证号 |
| cardNo | string | 是 | 银行卡号 |

### 10.3 请求示例

```json
{
  "name": "张三",
  "idNo": "320000000000000000",
  "cardNo": "6222000000000000"
}
```

### 10.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 11. 个人银行卡 4 要素信息比对

### 11.1 接口地址

```http
POST /esign/identity/individual/bank4Factors
```

### 11.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| idNo | string | 是 | 大陆二代身份证号 |
| cardNo | string | 是 | 银行卡号 |
| mobileNo | string | 是 | 银行预留手机号 |

### 11.3 请求示例

```json
{
  "name": "张三",
  "idNo": "320000000000000000",
  "cardNo": "6222000000000000",
  "mobileNo": "18800000000"
}
```

### 11.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 12. 个人银行卡 4 要素信息比对（详情版）

### 12.1 接口地址

```http
POST /esign/identity/individual/bank4Factors/detail
```

### 12.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| idNo | string | 是 | 大陆二代身份证号 |
| cardNo | string | 是 | 银行卡号 |
| mobileNo | string | 是 | 银行预留手机号 |

### 12.3 请求示例

```json
{
  "name": "张三",
  "idNo": "320000000000000000",
  "cardNo": "6222000000000000",
  "mobileNo": "18800000000"
}
```

### 12.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 13. 个人银行卡 4 要素信息比对（国际版）

### 13.1 接口地址

```http
POST /esign/identity/individual/bank4Factors/international
```

### 13.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 姓名 |
| certType | string | 是 | 证件类型 |
| certNo | string | 是 | 证件号码 |
| cardNo | string | 是 | 大陆银行卡号 |
| mobileNo | string | 是 | 大陆银行预留手机号 |

`certType` 可选值：

| 值 | 说明 |
| --- | --- |
| INDIVIDUAL_PASSPORT | 护照 |
| INDIVIDUAL_CH_HONGKONG_MACAO | 港澳居民来往内地通行证 |
| INDIVIDUAL_CH_TWCARD | 台湾居民来往大陆通行证 |
| INDIVIDUAL_CH_RESIDENCE_PERMIT_HK_MO_TW | 港澳台居民居住证 |

### 13.3 请求示例

```json
{
  "name": "SAN ZHANG",
  "certType": "INDIVIDUAL_PASSPORT",
  "certNo": "E00000000",
  "cardNo": "6222000000000000",
  "mobileNo": "18800000000"
}
```

### 13.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "536ab48c-e374-4b3a-ac62-fbe4791cce1a"
  }
}
```

## 14. 企业 3 要素信息比对

### 14.1 接口地址

```http
POST /esign/identity/organization/enterprise/bureau3Factors
```

### 14.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 企业名称 |
| orgCode | string | 是 | 企业证件号，支持工商注册号或统一社会信用代码 |
| legalRepName | string | 是 | 企业法定代表人姓名 |

### 14.3 请求示例

```json
{
  "name": "杭州某某信息科技有限公司",
  "orgCode": "913300000000000000",
  "legalRepName": "张三"
}
```

### 14.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "c64d1b26-2222-47bb-aeba-53cfed1977ba",
    "errCode": null,
    "errMsg": null,
    "compareDetails": {
      "sameOrgName": 1,
      "sameOrgCode": 1,
      "sameLegalRepresentative": 1,
      "legalOrgState": 1
    }
  }
}
```

### 14.5 compareDetails 说明

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| sameOrgName | string | 企业名称是否与工商信息一致，`1` 一致，`0` 不一致 |
| sameOrgCode | string | 企业证件号是否与工商信息一致，`1` 一致，`0` 不一致 |
| sameLegalRepresentative | string | 法定代表人姓名是否与工商信息一致，`1` 一致，`0` 不一致 |
| legalOrgState | string | 企业经营状态，具体枚举以 e签宝返回为准 |

## 15. 企业 4 要素信息比对

### 15.1 接口地址

```http
POST /esign/identity/organization/enterprise/bureau4Factors
```

### 15.2 请求参数

| 参数 | 类型 | 必选 | 说明 |
| --- | --- | --- | --- |
| name | string | 是 | 企业名称 |
| orgCode | string | 是 | 企业统一社会信用代码或工商注册号 |
| legalRepName | string | 是 | 企业法定代表人姓名 |
| legalRepCertNo | string | 是 | 企业法定代表人证件号 |

### 15.3 请求示例

```json
{
  "name": "杭州某某信息科技有限公司",
  "orgCode": "913300000000000000",
  "legalRepName": "张三",
  "legalRepCertNo": "320000000000000000"
}
```

### 15.4 响应示例

```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "verifyId": "4faf26cb-8be9-1111-9c19-69bd38c7344e",
    "errCode": null,
    "errMsg": null,
    "compareDetails": {
      "sameOrgName": 1,
      "sameOrgCode": 1,
      "sameLegalRepresentative": 1,
      "sameLegalRepresentativeCode": 1,
      "legalOrgState": 1
    }
  }
}
```

### 15.5 compareDetails 说明

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| sameOrgName | string | 企业名称是否与工商信息一致，`1` 一致，`0` 不一致 |
| sameOrgCode | string | 企业证件号是否与工商信息一致，`1` 一致，`0` 不一致 |
| sameLegalRepresentative | string | 法定代表人姓名是否与工商信息一致，`1` 一致，`0` 不一致 |
| sameLegalRepresentativeCode | string | 法定代表人证件号是否与工商信息一致，`1` 一致，`0` 不一致 |
| legalOrgState | string | 企业经营状态，具体枚举以 e签宝返回为准 |

## 16. 身份比对缓存清理

### 16.1 接口地址

```http
POST /esign/identity/cache/clear
```

### 16.2 接口说明

根据关键字清理身份比对 Redis 缓存。关键字会与缓存 key 做包含匹配，可用于按姓名、身份证号、手机号、银行卡号、企业名称、统一社会信用代码等内容清理。

### 16.3 请求参数

支持以下任一方式传入 `keyword`：

| 传参方式 | 示例 |
| --- | --- |
| Query 参数 | `/esign/identity/cache/clear?keyword=张三` |
| JSON body | `{"keyword":"张三"}` |
| 纯文本 body | `张三` |

### 16.4 请求示例

```json
{
  "keyword": "320000000000000000"
}
```

### 16.5 响应参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| code | int | 本地接口响应码，`0` 表示处理成功 |
| message | string | 响应描述 |
| data.keyword | string | 本次清理使用的关键字 |
| data.removed | int | 删除的缓存 key 数量 |
| data.remaining | int | 清理后剩余的身份比对缓存 key 数量 |

### 16.6 响应示例

```json
{
  "code": 0,
  "message": "清理成功",
  "data": {
    "keyword": "320000000000000000",
    "removed": 1,
    "remaining": 8
  }
}
```

### 16.7 异常示例

`keyword` 为空时返回：

```json
{
  "code": 400,
  "message": "keyword不能为空"
}
```

## 17. 调用示例

```bash
curl -X POST 'http://localhost:8080/esign/identity/individual/base' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "张三",
    "idNo": "320000000000000000"
  }'
```

```bash
curl -X POST 'http://localhost:8080/esign/identity/individual/bank4Factors' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "张三",
    "idNo": "320000000000000000",
    "cardNo": "6222000000000000",
    "mobileNo": "18800000000"
  }'
```

```bash
curl -X POST 'http://localhost:8080/esign/identity/cache/clear?keyword=张三'
```

## 18. 参考资料

- [MrDoc 接口文档示例](https://mrdoc.wwuche.com/doc/55/)
- [e签宝开放平台：个人 2 要素信息比对](https://open.esign.cn/doc/opendoc/identity_service/glz1it)
- [e签宝开放平台：个人运营商 2 要素信息比对](https://open.esign.cn/doc/opendoc/identity_service/tvpxgn1qmwnw0t4v)
- [e签宝开放平台：个人运营商 3 要素信息比对](https://open.esign.cn/doc/opendoc/identity_service/cgs6ee)
- [e签宝开放平台：个人运营商 3 要素信息比对（详情版）](https://open.esign.cn/doc/opendoc/identity_service/kyken6)
- [e签宝开放平台：个人银行卡 3 要素信息比对](https://open.esign.cn/doc/opendoc/identity_service/yp6dhb)
- [e签宝开放平台：个人银行卡 3 要素信息比对（详情版）](https://open.esign.cn/doc/opendoc/identity_service/vqoype)
- [e签宝开放平台：个人银行卡 4 要素信息比对](https://open.esign.cn/doc/opendoc/identity_service/ofppps)
- [e签宝开放平台：个人银行卡 4 要素信息比对（详情版）](https://open.esign.cn/doc/opendoc/identity_service/qqd8bs)
- [e签宝开放平台：个人银行卡 4 要素信息比对（国际版）](https://open.esign.cn/doc/opendoc/identity_service/dnism6)
- [e签宝开放平台：企业 3 要素信息比对](https://open.esign.cn/doc/opendoc/identity_service/ttoi4i)
- [e签宝开放平台：企业 4 要素信息比对](https://open.esign.cn/doc/opendoc/identity_service/xsafn3)