diff --git a/docs/api_downapp.md b/docs/api_downapp.md index 0a27500..1c86d74 100644 --- a/docs/api_downapp.md +++ b/docs/api_downapp.md @@ -10,66 +10,23 @@ ## 业务流程 -1. **申请开通**:调用方提交申请 (`rl_apply`)。 -2. **人工审批**:营运人员审核申请,回填火山引擎 AK/SK,并激活账户 (`active`)。 -3. **真人认证**:调用方发起认证请求,获取 H5 链接供终端用户完成人脸识别 (`rl_verify`)。 -4. **上传素材**:认证成功后,使用获取到的 `Group ID` 上传图片/视频 (`rl_upload`)。 -5. **状态同步**:轮询检查素材处理状态,直到变为 `Active` 可用 (`rl_status`)。 +1. **人工配置**:营运人员在 `rl_vendor_config` 表中登记供应商的全局 AK/SK 并激活状态。 +2. **真人认证**:调用方发起认证请求 (`rl_verify`),获取 H5 链接供终端用户完成人脸识别。 +3. **自动映射**:认证成功后,系统自动登记该机构 (`org_id`) 与供应商组合 ID (`vendor_group_id`) 的映射关系到 `rl_org_group` 表。 +4. **上传素材**:使用已认证的组合 ID 上传图片/视频,系统验证组合归属关系 (`rl_upload`)。 +5. **状态同步**:轮询检查素材处理状态 (`rl_status`)。 --- -## 1. 申请开通服务 -**Endpoint**: `/reallife_asset/api/rl_apply.dspy` - -登记调用方信息,申请开通真人素材上传权限。 - -### 请求参数 -| 参数 | 必填 | 说明 | -|------|------|------| -| `downapp_id` | 是 | 下游应用唯一标识 | -| `vendor` | 是 | 供应商名称,如 `volcengine` | -| `callback_url` | 是 | 真人认证完成后的回调地址 | - -### 请求示例 -```http -POST /reallife_asset/api/rl_apply.dspy -Content-Type: application/json - -{ - "downapp_id": "app_123", - "vendor": "volcengine", - "callback_url": "https://example.com/callback" -} -``` - -### 返回示例 -**成功**: -```json -{ - "success": true, - "app_id": "record_id_xxx", - "status": "pending" -} -``` -**失败**(已存在记录): -```json -{ - "success": false, - "message": "已提交申请,请等待审批" -} -``` - ---- - -## 2. 获取真人认证链接 (H5) +## 1. 获取真人认证链接 (H5) **Endpoint**: `/reallife_asset/api/rl_verify.dspy` -检查审批状态通过后,调用供应商接口创建认证会话。 +检查供应商配置通过后,调用供应商接口创建认证会话。 ### 请求参数 | 参数 | 必填 | 说明 | |------|------|------| -| `downapp_id` | 是 | 下游应用唯一标识 | +| `downapp_id` | 是 | 下游应用唯一标识 (用于追踪记录) | | `project_name` | 否 | 项目名称,默认 `default` | ### 请求示例 @@ -93,19 +50,19 @@ Content-Type: application/json "byted_token": "..." } ``` -**失败**(未开通): +**失败**(未配置): ```json { "success": false, - "message": "申请状态: pending,未通过审批" + "message": "供应商配置不存在" } ``` -**注意**:终端用户在 H5 页面完成认证后,供应商将回调 `rl_apply` 中设置的 `callback_url`。 +**注意**:终端用户在 H5 页面完成认证后,系统将自动在 `rl_org_group` 表中登记该机构与组合 ID 的映射关系。 --- -## 3. 上传素材 +## 2. 上传素材 **Endpoint**: `/reallife_asset/api/rl_upload.dspy` 向已认证的素材组合上传图片或视频素材。 @@ -148,7 +105,7 @@ Content-Type: application/json --- -## 4. 查询素材状态 +## 3. 查询素材状态 **Endpoint**: `/reallife_asset/api/rl_status.dspy` 查询素材的处理状态(Processing / Active / Failed)。 @@ -186,7 +143,7 @@ Content-Type: application/json | 错误信息 | 原因 | 解决方案 | |----------|------|----------| -| `未申请或供应商不支持` | `downapp_id` 不存在 | 确认是否已调用申请接口 | -| `申请状态: xxx,未通过审批` | 状态非 `active` | 联系营运人员审核 | -| `素材组合不存在` | `group_id` 无效 | 确认是否已通过认证获取有效 ID | +| `供应商配置不存在` | 营运人员未配置 AK/SK | 联系管理员配置 `rl_vendor_config` | +| `无效的素材组合ID或无权访问` | `group_id` 不属于当前机构 | 确认是否已完成认证并使用正确的 ID | +| `素材不存在或无权访问` | `asset_id` 无效或归属错误 | 检查 ID 是否正确 | | `参数缺失` | 缺少必填参数 | 检查请求 Body |