feat(realname): 实名核验切换到数脉二要素新接口
服务商旧接口 sinocheck2 已下线，改走 eid.shumaidata.com/eid/check： - 身份证入参 id_number 改为 idcard - 响应改为先判业务 code、再读 result.res 的两级结构， code/res 兼容字符串与数字两种返回形式 - 按服务商错误码表分流：400/20010/20310 归入参错误， 404/604 归服务未配置，其余归服务不可用 - 驳回原因优先取服务商 description - 新接口不返回流水号，provider_order_no 对该渠道留空 - 同步更新默认 URL 与 docs/实名认证.md Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
yml2213
+98
-73
@@ -1,91 +1,116 @@
|
||||
接口信息
|
||||
调用地址：
|
||||
https://sinocheck2.market.alicloudapi.com/fortest/ttttt
|
||||
# 实名认证接口（身份证二要素核验）
|
||||
|
||||
请求方式：
|
||||
POST
|
||||
返回类型：
|
||||
JSON
|
||||
API 调用：
|
||||
API 简单身份认证调用方法（APPCODE）
|
||||
API 签名认证调用方法（AppKey & AppSecret）
|
||||
服务商：阿里云市场 - 天眼数聚「身份证实名核验优质版」。
|
||||
传入姓名、身份证号，校验二要素是否一致，同时返回生日、性别、籍贯等信息。
|
||||
|
||||
获取认证：
|
||||
AppKey & AppCode
|
||||
接口参数
|
||||
请求参数（Header）
|
||||
请求参数（Query）
|
||||
字段名称
|
||||
必填
|
||||
字段名称 必填 字段详情
|
||||
name string
|
||||
Y
|
||||
姓名
|
||||
> 旧接口 `https://sinocheck2.market.alicloudapi.com/fortest/ttttt` 已下线，参数名为 `id_number`、
|
||||
> 响应为顶层 `status`/`result` 的那一版不再使用，全部改走下面的新接口。
|
||||
|
||||
id_number string
|
||||
Y
|
||||
身份证号
|
||||
## 接口信息
|
||||
|
||||
| 项 | 值 |
|
||||
| --- | --- |
|
||||
| 调用地址 | `https://eid.shumaidata.com/eid/check` |
|
||||
| 请求方式 | POST |
|
||||
| 返回类型 | JSON |
|
||||
| 鉴权方式 | 请求头 `Authorization: APPCODE <AppCode>`（阿里云市场简单身份认证） |
|
||||
|
||||
成功响应
|
||||
## 请求参数（Query）
|
||||
|
||||
| 字段名称 | 类型 | 必填 | 字段详情 |
|
||||
| --- | --- | --- | --- |
|
||||
| name | string | Y | 姓名 |
|
||||
| idcard | string | Y | 身份证号 |
|
||||
|
||||
Body 无参数。
|
||||
|
||||
## 成功响应
|
||||
|
||||
解析结果时，先判断 `code`：`code=0` 时再判断 `result.res`；`code!=0` 表示调用已失败，无需再继续。
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "TIDxxxxxxx", //请求ID，联系提供给客服，有助于问题排查
|
||||
"status": "OK", //状态参数，OK为完成查询请求。
|
||||
"result": 1 //身份核验结果，"result": 1（验证一致）；2（不一致）； 3 （库无）；110 请求次数过多：同一身份证号一天内最多请求【10】次；
|
||||
"code": "0",
|
||||
"message": "成功",
|
||||
"result": {
|
||||
"name": "冯**",
|
||||
"idcard": "350*********9422",
|
||||
"res": "1",
|
||||
"description": "一致",
|
||||
"sex": "男",
|
||||
"birthday": "19*****0",
|
||||
"address": "江西省****区"
|
||||
}
|
||||
}
|
||||
温馨提示：
|
||||
1.当 "status": "OK"时，仅代表接口请求成功，"result"的返回值为身份核验结果
|
||||
```
|
||||
|
||||
2.当 "result": 3 ，核验结果为'库无'，有以下几种原因
|
||||
(1)现役军人、武警官兵、特殊部门人员及特殊级别官员；
|
||||
(2)退役不到2年的军人和士兵（根据军衔、兵种不同，时间会有所不同，一般为2年）；
|
||||
(3)户口迁出，且没有在新的迁入地迁入；
|
||||
(4)户口迁入新迁入地，当地公安系统未将迁移信息上报到公安部（上报时间地域不同而有所差异）；
|
||||
(5)更改姓名，当地公安系统未将更改信息上报到公安部（上报时间因地域不同而有所差异）；
|
||||
(6)移民；
|
||||
(7)未更换二代身份证；
|
||||
(8)死亡。
|
||||
(9)身份证号确实不存在
|
||||
`result.res` 核验结果状态码：
|
||||
|
||||
| res | 含义 |
|
||||
| --- | --- |
|
||||
| 1 | 一致 |
|
||||
| 2 | 不一致 |
|
||||
| 3 | 无记录（预留） |
|
||||
|
||||
失败响应
|
||||
`res=3`（库无）的常见原因：
|
||||
|
||||
1. 现役军人、武警官兵、特殊部门人员及特殊级别官员；
|
||||
2. 退役不到 2 年的军人和士兵（根据军衔、兵种不同，一般为 2 年）；
|
||||
3. 户口迁出，且没有在新的迁入地迁入；
|
||||
4. 户口迁入新迁入地，当地公安系统未将迁移信息上报到公安部；
|
||||
5. 更改姓名，当地公安系统未将更改信息上报到公安部；
|
||||
6. 移民；
|
||||
7. 未更换二代身份证；
|
||||
8. 死亡；
|
||||
9. 身份证号确实不存在。
|
||||
|
||||
## 失败响应
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "INVALID_ARGUMENT",
|
||||
"reason": "Invalid id_number",
|
||||
"request_id": "TID2af751b4bff24be781d60af10bf84101"
|
||||
"code": "20310",
|
||||
"message": "请求姓名不标准：姓名为空或者包含特殊字符",
|
||||
"result": {}
|
||||
}
|
||||
```
|
||||
|
||||
注意 `code` 是业务返回码，并非 HTTP 状态码。
|
||||
|
||||
====
|
||||
错误码
|
||||
错误码
|
||||
错误信息
|
||||
描述
|
||||
200
|
||||
请求次数过多：同一身份证号一天内最多请求【4】次
|
||||
请求次数过多：同一身份证号一天内最多请求【10】次
|
||||
400
|
||||
请求参数错误，原因：未输入姓名
|
||||
请求参数错误，原因：未输入姓名
|
||||
401
|
||||
账号或密钥错误
|
||||
账号或密钥错误
|
||||
403
|
||||
调用频率过高
|
||||
调用频率过高
|
||||
404
|
||||
请求路径错误
|
||||
请求路径错误
|
||||
500
|
||||
数据服务异常
|
||||
数据服务异常
|
||||
400
|
||||
参数非UTF-8编码
|
||||
参数非UTF-8编码
|
||||
400
|
||||
请求参数错误，原因：姓名为空
|
||||
请求参数错误，原因：姓名为空
|
||||
## 错误码
|
||||
|
||||
| 错误码 | 错误信息 | 描述 |
|
||||
| --- | --- | --- |
|
||||
| 0 | 成功 | 成功 |
|
||||
| 400 | 参数错误 | 参数错误 |
|
||||
| 20010 | 身份证号为空或非法 | 身份证号为空或非法 |
|
||||
| 20310 | 姓名为空或非法 | 姓名为空或非法 |
|
||||
| 404 | 请求资源不存在 | 请求资源不存在 |
|
||||
| 500 | 系统内部错误，请联系服务商 | 系统内部错误，请联系服务商 |
|
||||
| 501 | 第三方服务异常 | 第三方服务异常 |
|
||||
| 604 | 接口停用 | 接口停用 |
|
||||
| 1001 | 其他，以实际返回为准 | 其他，以实际返回为准 |
|
||||
|
||||
## 本项目的接入
|
||||
|
||||
实现位于 `backend/internal/modules/realname/cloudmarket_provider.go`，配置项：
|
||||
|
||||
```
|
||||
REALNAME_PROVIDER=cloudmarket
|
||||
REALNAME_CLOUDMARKET_URL=https://eid.shumaidata.com/eid/check
|
||||
REALNAME_CLOUDMARKET_APPCODE=<阿里云市场 AppCode>
|
||||
```
|
||||
|
||||
响应与内部状态、错误的映射关系：
|
||||
|
||||
| 服务商返回 | 内部结果 |
|
||||
| --- | --- |
|
||||
| `code=0` 且 `res=1` | 认证通过（`verified`），记录通过时间 |
|
||||
| `code=0` 且 `res=2` 或 `3` | 认证驳回（`rejected`），失败原因取 `description` |
|
||||
| `code` 为 400 / 20010 / 20310 | `ErrInvalidRealnameInput`，接口返回 400 |
|
||||
| `code` 为 404 / 604 | `ErrProviderConfigInvalid`，接口返回 503 |
|
||||
| `code` 为 500 / 501 / 1001 等其他值 | `ErrProviderUnavailable`，接口返回 502 |
|
||||
| HTTP 403 / 429（网关限流） | `ErrProviderRateLimited`，接口返回 429 |
|
||||
| HTTP 401 / 404（AppCode 或路径错误） | `ErrProviderConfigInvalid`，接口返回 503 |
|
||||
|
||||
该接口不返回服务商流水号，因此 `user_realname.provider_order_no` 对 cloudmarket 渠道为空。
|
||||
姓名与身份证号由本项目自行脱敏入库，并用 `pkg/crypto` 加密保存完整值。
|
||||
|
||||
Reference in New Issue
Block a user