tyapi-server/docs/认证流程API说明.md

认证流程API说明

概述

认证流程已简化为6个主要状态，系统会自动处理认证申请的创建和完成，用户无需手动调用相关接口。

认证状态

1. 待认证 (pending) - 用户尚未开始认证流程
2. 已提交企业信息 (info_submitted) - 用户已提交企业信息
3. 已企业认证 (enterprise_verified) - 企业信息已通过认证
4. 已申请合同 (contract_applied) - 已申请e签宝生成合同
5. 已签署合同 (contract_signed) - 合同已签署完成
6. 认证完成 (completed) - 认证流程全部完成

API接口

1. 获取认证状态

GET /api/certification/status

获取当前用户的认证状态信息。

响应示例：

{
  "code": 200,
  "message": "获取认证状态成功",
  "data": {
    "id": "cert_123",
    "user_id": "user_456",
    "status": "info_submitted",
    "status_name": "已提交企业信息",
    "progress": 33,
    "is_user_action_required": false,
    "info_submitted_at": "2024-01-01T10:00:00Z",
    "enterprise_verified_at": null,
    "contract_applied_at": null,
    "contract_signed_at": null,
    "completed_at": null,
    "contract_url": "",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}

2. 获取认证详情

GET /api/certification/details

获取当前用户的详细认证信息，包括企业信息。

响应示例：

{
  "code": 200,
  "message": "获取认证详情成功",
  "data": {
    "id": "cert_123",
    "user_id": "user_456",
    "status": "enterprise_verified",
    "status_name": "已企业认证",
    "progress": 66,
    "is_user_action_required": true,
    "info_submitted_at": "2024-01-01T10:00:00Z",
    "enterprise_verified_at": "2024-01-01T11:00:00Z",
    "contract_applied_at": null,
    "contract_signed_at": null,
    "completed_at": null,
    "contract_url": "",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T11:00:00Z",
    "enterprise": {
      "id": "ent_789",
      "company_name": "示例企业有限公司",
      "unified_social_code": "91110000123456789X",
      "legal_person_name": "张三",
      "legal_person_id": "110101199001011234",
      "is_ocr_verified": true,
      "is_face_verified": true,
      "created_at": "2024-01-01T10:00:00Z",
      "updated_at": "2024-01-01T10:00:00Z"
    }
  }
}

3. 获取认证进度

GET /api/certification/progress

获取当前用户的认证进度信息。

响应示例：

{
  "code": 200,
  "message": "获取认证进度成功",
  "data": {
    "certification_id": "cert_123",
    "user_id": "user_456",
    "current_status": "contract_signed",
    "status_name": "已签署合同",
    "progress_percentage": 100,
    "is_user_action_required": false,
    "next_valid_statuses": ["completed"],
    "message": "合同签署完成，认证流程结束",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

4. 提交企业信息

POST /api/certification/submit-enterprise-info

提交企业信息。如果用户没有认证申请，系统会自动创建。

请求参数：

{
  "company_name": "示例企业有限公司",
  "unified_social_code": "91110000123456789X",
  "legal_person_name": "张三",
  "legal_person_id": "110101199001011234"
}

响应示例：

{
  "code": 200,
  "message": "企业信息提交成功",
  "data": {
    "id": "ent_789",
    "company_name": "示例企业有限公司",
    "unified_social_code": "91110000123456789X",
    "legal_person_name": "张三",
    "legal_person_id": "110101199001011234",
    "is_ocr_verified": false,
    "is_face_verified": false,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}

5. 企业认证

POST /api/certification/enterprise-verify

执行企业认证流程。

响应示例：

{
  "code": 200,
  "message": "企业认证成功",
  "data": {
    "id": "cert_123",
    "user_id": "user_456",
    "status": "enterprise_verified",
    "status_name": "已企业认证",
    "progress": 66,
    "is_user_action_required": true,
    "info_submitted_at": "2024-01-01T10:00:00Z",
    "enterprise_verified_at": "2024-01-01T11:00:00Z",
    "contract_applied_at": null,
    "contract_signed_at": null,
    "completed_at": null,
    "contract_url": "",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T11:00:00Z"
  }
}

6. 申请合同

POST /api/certification/apply-contract

申请e签宝生成合同文件。

响应示例：

{
  "code": 200,
  "message": "合同申请成功",
  "data": {
    "id": "cert_123",
    "user_id": "user_456",
    "status": "contract_applied",
    "status_name": "已申请合同",
    "progress": 83,
    "is_user_action_required": true,
    "info_submitted_at": "2024-01-01T10:00:00Z",
    "enterprise_verified_at": "2024-01-01T11:00:00Z",
    "contract_applied_at": "2024-01-01T12:00:00Z",
    "contract_signed_at": null,
    "completed_at": null,
    "contract_url": "",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

7. 完成合同签署

POST /api/certification/complete-contract-sign

完成合同签署。系统会自动判断是否完成认证。

请求参数：

{
  "contract_url": "https://esign.example.com/contract/123"
}

响应示例：

{
  "code": 200,
  "message": "合同签署完成",
  "data": null
}

流程说明

自动处理逻辑

1. 自动创建认证申请：当用户首次提交企业信息时，如果用户没有认证申请，系统会自动创建一个认证申请。

2. 自动完成认证：当合同签署完成后，系统会自动将认证状态更新为"认证完成"。

3. 企业信息创建：企业信息在企业认证成功时自动创建，用户无需手动创建。

状态转换规则

• 待认证 → 已提交企业信息：提交企业信息
• 已提交企业信息 → 已企业认证：企业认证成功
• 已企业认证 → 已申请合同：申请合同
• 已申请合同 → 已签署合同：合同签署完成
• 已签署合同 → 认证完成：自动完成

进度百分比

• 待认证：0%
• 已提交企业信息：33%
• 已企业认证：66%
• 已申请合同：83%
• 已签署合同：100%
• 认证完成：100%

错误处理

所有接口都会返回统一的错误格式：

{
  "code": 400,
  "message": "错误描述信息",
  "data": null
}

常见错误：

• 用户未登录：JWT token无效或过期
• 用户已有企业信息：用户已存在企业信息
• 统一社会信用代码已存在：该企业已被其他用户认证
• 当前状态不允许企业认证：状态转换不合法
• 用户尚未创建认证申请：用户没有认证申请（通常不会出现，因为会自动创建）