276 lines
6.9 KiB
Markdown
276 lines
6.9 KiB
Markdown
# 认证流程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
|
||
```
|
||
获取当前用户的认证状态信息。
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"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
|
||
```
|
||
获取当前用户的详细认证信息，包括企业信息。
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"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
|
||
```
|
||
获取当前用户的认证进度信息。
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"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
|
||
```
|
||
提交企业信息。如果用户没有认证申请，系统会自动创建。
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"company_name": "示例企业有限公司",
|
||
"unified_social_code": "91110000123456789X",
|
||
"legal_person_name": "张三",
|
||
"legal_person_id": "110101199001011234"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"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
|
||
```
|
||
执行企业认证流程。
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"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签宝生成合同文件。
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"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
|
||
```
|
||
完成合同签署。系统会自动判断是否完成认证。
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"contract_url": "https://esign.example.com/contract/123"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "合同签署完成",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 流程说明
|
||
|
||
### 自动处理逻辑
|
||
|
||
1. **自动创建认证申请**：当用户首次提交企业信息时，如果用户没有认证申请，系统会自动创建一个认证申请。
|
||
|
||
2. **自动完成认证**：当合同签署完成后，系统会自动将认证状态更新为"认证完成"。
|
||
|
||
3. **企业信息创建**：企业信息在企业认证成功时自动创建，用户无需手动创建。
|
||
|
||
### 状态转换规则
|
||
|
||
- **待认证** → **已提交企业信息**：提交企业信息
|
||
- **已提交企业信息** → **已企业认证**：企业认证成功
|
||
- **已企业认证** → **已申请合同**：申请合同
|
||
- **已申请合同** → **已签署合同**：合同签署完成
|
||
- **已签署合同** → **认证完成**：自动完成
|
||
|
||
### 进度百分比
|
||
|
||
- 待认证：0%
|
||
- 已提交企业信息：33%
|
||
- 已企业认证：66%
|
||
- 已申请合同：83%
|
||
- 已签署合同：100%
|
||
- 认证完成：100%
|
||
|
||
## 错误处理
|
||
|
||
所有接口都会返回统一的错误格式：
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "错误描述信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
常见错误：
|
||
- `用户未登录`：JWT token无效或过期
|
||
- `用户已有企业信息`：用户已存在企业信息
|
||
- `统一社会信用代码已存在`：该企业已被其他用户认证
|
||
- `当前状态不允许企业认证`：状态转换不合法
|
||
- `用户尚未创建认证申请`：用户没有认证申请（通常不会出现，因为会自动创建） |