#实名认证 API 文档

#概述

实名认证功能支持多种认证方式，用于验证用户的真实身份。系统支持以下认证类型：

#业务流程图

#认证状态流转

#证件图片认证流程

#用户端接口

#1. 身份证认证 POST /user/identity_verification/id_card

#功能说明

提交身份证认证申请。根据 cert_type 参数选择认证方式：

• API 自动认证：IDENTITY_CARD、RESIDENCE_HK_MC、RESIDENCE_TAIWAN
• 人工审核：ID_CARD_MANUAL

#请求参数

upload_image_ids 说明：

• 仅当 cert_type=ID_CARD_MANUAL 时必填
• 数组长度：1-5 个
• 图片必须是当前用户通过 /upload_image 接口上传的

#请求示例

API 自动认证：

{
  "real_name": "张三",
  "id_card_number": "110101199001011234",
  "cert_type": "IDENTITY_CARD"
}

人工审核认证：

{
  "real_name": "张三",
  "id_card_number": "110101199001011234",
  "cert_type": "ID_CARD_MANUAL",
  "upload_image_ids": [123, 124, 125]
}

#响应示例

API 认证成功：

{
  "success": true,
  "message": "认证成功",
  "data": {
    "verification_type": "id_card_2",
    "status": "verified"
  }
}

人工审核已提交：

{
  "success": true,
  "message": "证件图片认证已提交，请等待审核",
  "data": {
    "verification_type": "id_card_image",
    "status": "pending"
  }
}

#错误响应

#2. 取消认证申请 POST /user/identity_verification/cancel

#功能说明

取消当前用户待审核的证件图片认证申请。仅支持取消 ID_CARD_MANUAL 类型且状态为 pending 的认证。

#请求参数

无需参数。

#响应示例

取消成功：

{
  "success": true,
  "message": "认证申请已取消"
}

#错误响应

#3. 获取认证信息 POST /user/identity_verification/info

#功能说明

获取当前用户的实名认证信息（脱敏显示）。

#请求参数

无需参数。

#响应示例

{
  "data": {
    "id": 1,
    "user_id": 100,
    "verification_type": "id_card_2",
    "status": "verified",
    "real_name": "张*",
    "id_card_number": "110101********1234",
    "verified_at": "2024-01-15T10:30:00.000000Z"
  }
}

#4. 获取认证历史 POST /user/identity_verification/history

#功能说明

获取当前用户的所有认证历史记录。

#请求参数

无需参数。

#响应示例

{
  "data": [
    {
      "id": 2,
      "verification_type": "id_card_image",
      "status": "verified",
      "created_at": "2024-01-15T10:00:00.000000Z",
      "verified_at": "2024-01-15T12:00:00.000000Z"
    },
    {
      "id": 1,
      "verification_type": "id_card_2",
      "status": "failed",
      "failure_reason": "MISMATCH",
      "created_at": "2024-01-14T10:00:00.000000Z"
    }
  ]
}

#关联接口

以下接口在创建/更新时也支持 ID_CARD_MANUAL 认证方式：

#提现账户接口

#POST /user/withdraw_account/create

创建提现账户时，如果用户未完成实名认证，可以使用 ID_CARD_MANUAL 方式提交认证。

#POST /user/withdraw_account/update

更新提现账户时，如果用户未完成实名认证，可以使用 ID_CARD_MANUAL 方式提交认证。

请求参数（认证相关）：

注意：当 cert_type=ID_CARD_MANUAL 时，接口会返回 ok: false 并提示等待审核，不会立即创建/更新提现账户。用户需要等待审核通过后再次操作。

#后台管理接口

注意：以下接口位于 /internal 路由组，使用内部 API 认证。

#1. 审核通过 POST /internal/identity_verification/approve

#功能说明

管理员审核通过证件图片认证申请。审核通过后：

1. 认证记录状态更新为 verified
2. 用户 is_identity_verified 更新为 true
3. 用户 identity_verification_status 变为 verified

#请求参数

#请求示例

{
  "id": 123
}

#响应示例

{
  "success": true,
  "message": "审核通过成功"
}

#错误响应

#2. 审核拒绝 POST /internal/identity_verification/reject

#功能说明

管理员审核拒绝证件图片认证申请。

#请求参数

#请求示例

{
  "id": 123,
  "reason": "证件图片不清晰，请重新上传"
}

#响应示例

{
  "success": true,
  "message": "审核拒绝成功"
}

#用户信息中的认证状态

#identity_verification_status 字段

在用户信息接口 (/user/info) 返回中，新增 identity_verification_status 字段，前端只需判断此字段即可：

#响应示例

{
  "data": {
    "id": 100,
    "name": "用户名",
    "email": "user@example.com",
    "is_identity_verified": false,
    "identity_verification_status": "pending"
  }
}

#数据模型

#认证类型 (verification_type)

#认证状态 (status)

#证件类型 (cert_type)

#完整调用流程示例

#场景1：API 自动认证

1. POST /user/identity_verification/id_card
   Body: { "real_name": "张三", "id_card_number": "110101199001011234", "cert_type": "IDENTITY_CARD" }

2. 响应: { "success": true, "message": "认证成功", "data": { "status": "verified" } }

3. GET /user/info
   响应: { "data": { "identity_verification_status": "verified" } }

#场景2：证件图片认证（人工审核）

1. POST /upload_image (上传证件正面)
   响应: { "data": { "id": 123 } }

2. POST /upload_image (上传证件反面)
   响应: { "data": { "id": 124 } }

3. POST /user/identity_verification/id_card
   Body: {
     "real_name": "张三",
     "id_card_number": "110101199001011234",
     "cert_type": "ID_CARD_MANUAL",
     "upload_image_ids": [123, 124]
   }
   响应: { "success": true, "message": "证件图片认证已提交，请等待审核", "data": { "status": "pending" } }

4. GET /user/info
   响应: { "data": { "identity_verification_status": "pending" } }

5. [后台] POST /admin_center/identity_verification/approve
   Body: { "id": 1 }

6. GET /user/info
   响应: { "data": { "identity_verification_status": "verified" } }

#场景3：取消认证申请

1. (已提交人工审核认证，状态为 pending)

2. POST /user/identity_verification/cancel
   响应: { "success": true, "message": "认证申请已取消" }

3. GET /user/info
   响应: { "data": { "identity_verification_status": "none" } }

4. (可重新提交认证申请)

#注意事项

1. 图片上传：使用 /upload_image 接口上传证件图片，不会压缩原图
2. 图片归属验证：系统会验证 upload_image_ids 中的图片是否属于当前用户
3. 重复提交限制：用户有待审核的认证时，无法提交新的认证申请
4. 取消后可重新提交：取消认证后，用户可以重新提交认证申请
5. 审核拒绝后可重新提交：认证被拒绝后，用户可以重新提交认证申请

#错误码

错误响应格式：

{
  "code": 30020,
  "message": "具体错误信息"
}