| # 第三方技术对接文档 |
|
|
| 这份文档是给第三方技术人员直接对接用的。 |
| 按本文档接入即可完成： |
|
|
| - 查询当前可用邮箱/上传服务 |
| - 创建注册批次 |
| - 查询批次状态 |
| - 取消批次 |
|
|
| 如需更详细字段说明，可再参考： |
|
|
| - [Temp Mail 域名池与外部注册 API 说明](temp-mail-external-api.md) |
| - [External API 调用示例](external-api-examples.md) |
| - [External API 网站内管理与 API Key 生成方案](external-api-webui-management-plan.md) |
|
|
| --- |
|
|
| ## 1. 对接方会拿到什么 |
|
|
| 项目方需要提供给第三方以下信息： |
|
|
| ### 1.1 Base URL |
|
|
| 例如： |
|
|
| ```text |
| http://your-domain:8000/api |
| ``` |
|
|
| ### 1.2 鉴权请求头 |
|
|
| ```http |
| X-API-Key: your_api_key |
| ``` |
|
|
| ### 1.3 API Key 从哪里来 |
|
|
| 这个 `your_api_key` 不是第三方自己申请的，也不是通过接口获取的。 |
|
|
| 它来自项目管理员在系统中配置的： |
|
|
| - `external_api_enabled` |
| - `external_api_key` |
|
|
| 然后由项目方把这个 Key 发给第三方使用。 |
|
|
| > 当前版本没有开放“获取 API Key / 轮换 API Key”接口。 |
| > 如果更换了 Key，项目方需要重新通知第三方同步更新。 |
|
|
| --- |
|
|
| ## 2. 对接流程总览 |
|
|
| 第三方只需要实现这 4 个接口： |
|
|
| 1. `GET /external/capabilities` |
| 2. `POST /external/registration/batches` |
| 3. `GET /external/registration/batches/{batch_uuid}` |
| 4. `POST /external/registration/batches/{batch_uuid}/cancel` |
|
|
| 推荐接入顺序： |
|
|
| 1. 先接 `capabilities` |
| 2. 再接 `create batch` |
| 3. 再接 `get batch status` |
| 4. 最后接 `cancel batch` |
|
|
| --- |
|
|
| ## 3. 查询当前可用能力 |
|
|
| ### 3.1 请求 |
|
|
| ```http |
| GET /api/external/capabilities |
| X-API-Key: your_api_key |
| ``` |
|
|
| ### 3.2 作用 |
|
|
| 这个接口用于告诉第三方当前环境里： |
|
|
| - 支持哪些邮箱类型 |
| - 各邮箱类型下有哪些具体服务 |
| - 支持哪些上传 provider |
| - 每个 provider 下有哪些具体服务 |
|
|
| ### 3.3 典型返回示例 |
|
|
| ```json |
| { |
| "email_types": [ |
| { |
| "type": "temp_mail", |
| "available": true, |
| "count": 2, |
| "services": [ |
| { |
| "id": 3, |
| "name": "Worker temp mail A", |
| "type": "temp_mail", |
| "priority": 0, |
| "domain_count": 2, |
| "domains_preview": ["a.example.com", "b.example.com"], |
| "domain_source": "worker_api" |
| }, |
| { |
| "id": 7, |
| "name": "Worker temp mail B", |
| "type": "temp_mail", |
| "priority": 0, |
| "domain_count": 1, |
| "domains_preview": ["c.example.com"], |
| "domain_source": "config_domains" |
| } |
| ] |
| } |
| ], |
| "upload_providers": [ |
| { |
| "provider": "sub2api", |
| "available": true, |
| "count": 2, |
| "services": [ |
| {"id": 1, "name": "sub2-main", "priority": 0}, |
| {"id": 4, "name": "sub2-backup", "priority": 10} |
| ] |
| }, |
| { |
| "provider": "cpa", |
| "available": true, |
| "count": 1, |
| "services": [ |
| {"id": 2, "name": "cpa-main", "priority": 0} |
| ] |
| } |
| ], |
| "settings": { |
| "external_api_enabled": true |
| } |
| } |
| ``` |
|
|
| --- |
|
|
| ## 4. `service_id` 怎么识别 |
| |
| 这是第三方最容易误解的地方。 |
| |
| ### 4.1 不是靠猜 0 / 1 / 2 |
| |
| `service_id` 不是固定编号，也不是文档里写死的顺序编号。 |
| 它必须以当前环境里 `capabilities` 返回的实际 `id` 为准。 |
|
|
| 例如上面的返回里： |
|
|
| - `email.service_id = 3` 表示 `Worker temp mail A` |
| - `email.service_id = 7` 表示 `Worker temp mail B` |
| - `upload.service_id = 1` 表示 `sub2-main` |
| - `upload.service_id = 4` 表示 `sub2-backup` |
|
|
| ### 4.2 正确使用方式 |
|
|
| 第三方应始终： |
|
|
| 1. 先请求 `GET /external/capabilities` |
| 2. 按 `type/provider + name` 找到目标服务 |
| 3. 读取对应的 `id` |
| 4. 创建批次时把该 `id` 传给 `service_id` |
|
|
| ### 4.3 不传 `service_id` 会怎样 |
| |
| 如果不传 `service_id`： |
|
|
| - `email.service_id` 不传：系统自动选该邮箱类型当前可用服务 |
| - `upload.service_id` 不传：系统自动选该上传 provider 当前启用且优先级最高的服务 |
|
|
| 如果第三方不需要固定某个具体服务，建议直接不传。 |
|
|
| --- |
|
|
| ## 5. 创建注册批次 |
|
|
| ### 5.1 请求 |
|
|
| ```http |
| POST /api/external/registration/batches |
| Content-Type: application/json |
| X-API-Key: your_api_key |
| ``` |
|
|
| ### 5.2 请求体示例：最简版本 |
|
|
| ```json |
| { |
| "count": 10, |
| "email": { |
| "type": "temp_mail" |
| }, |
| "upload": { |
| "enabled": false |
| }, |
| "execution": { |
| "mode": "pipeline", |
| "concurrency": 1, |
| "interval_min": 0, |
| "interval_max": 0 |
| } |
| } |
| ``` |
|
|
| ### 5.3 请求体示例：指定邮箱服务并上传 |
|
|
| ```json |
| { |
| "count": 20, |
| "idempotency_key": "batch-20260327-001", |
| "email": { |
| "type": "temp_mail", |
| "service_id": 3 |
| }, |
| "upload": { |
| "enabled": true, |
| "provider": "sub2api", |
| "service_id": 1 |
| }, |
| "execution": { |
| "mode": "parallel", |
| "concurrency": 5, |
| "interval_min": 0, |
| "interval_max": 0 |
| } |
| } |
| ``` |
|
|
| ### 5.4 字段说明 |
|
|
| | 字段 | 必填 | 说明 | |
| | --- | --- | --- | |
| | `count` | 是 | 注册数量，范围 `1 ~ 100` | |
| | `idempotency_key` | 否 | 幂等键，建议传 | |
| | `email.type` | 是 | 邮箱类型，如 `temp_mail` / `outlook` | |
| | `email.service_id` | 否 | 指定某个邮箱服务，来源于 `capabilities` | |
| | `upload.enabled` | 是 | 是否上传 | |
| | `upload.provider` | 条件必填 | `upload.enabled=true` 时必填，支持 `sub2api` / `cpa` / `tm` | |
| | `upload.service_id` | 否 | 指定某个上传服务，来源于 `capabilities` | |
| | `execution.mode` | 否 | `pipeline` 或 `parallel` | |
| | `execution.concurrency` | 否 | 并发数，范围 `1 ~ 50` | |
| | `execution.interval_min` | 否 | 最小间隔秒数 | |
| | `execution.interval_max` | 否 | 最大间隔秒数，必须 `>= interval_min` | |
|
|
| ### 5.5 返回说明 |
|
|
| - 首次成功创建：HTTP `202` |
| - 如果 `idempotency_key` 命中已有批次：HTTP `200` |
|
|
| 返回里会带： |
|
|
| ```json |
| { |
| "batch_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", |
| "status": "pending", |
| "requested_count": 20, |
| "completed_count": 0, |
| "success_count": 0, |
| "failed_count": 0, |
| "upload_success_count": 0, |
| "upload_failed_count": 0, |
| "failure_reason": null, |
| "created_at": "2026-03-27T12:00:00", |
| "started_at": null, |
| "completed_at": null, |
| "recent_errors": [], |
| "idempotent_replay": false |
| } |
| ``` |
|
|
| 第三方需要保存： |
|
|
| - `batch_uuid` |
|
|
| 后续查询和取消都要用它。 |
|
|
| --- |
|
|
| ## 6. 查询批次状态 |
|
|
| ### 6.1 请求 |
|
|
| ```http |
| GET /api/external/registration/batches/{batch_uuid} |
| X-API-Key: your_api_key |
| ``` |
|
|
| ### 6.2 第三方重点关注字段 |
|
|
| - `status` |
| - `requested_count` |
| - `completed_count` |
| - `success_count` |
| - `failed_count` |
| - `upload_success_count` |
| - `upload_failed_count` |
| - `failure_reason` |
| - `recent_errors` |
|
|
| ### 6.3 终态定义 |
|
|
| 以下状态视为任务结束： |
|
|
| - `completed` |
| - `completed_partial` |
| - `failed` |
| - `cancelled` |
|
|
| 建议第三方以这几个状态作为轮询终止条件。 |
|
|
| ### 6.4 推荐理解方式 |
|
|
| 如果请求注册 20 个账号： |
|
|
| - `success_count=20`：全部成功 |
| - `success_count=17, failed_count=3`：部分成功 |
| - `success_count=0, failed_count=20`：全部失败 |
|
|
| 不要要求系统必须 100% 成功；应根据成功数和失败数做业务判断。 |
|
|
| --- |
|
|
| ## 7. 取消批次 |
|
|
| ### 7.1 请求 |
|
|
| ```http |
| POST /api/external/registration/batches/{batch_uuid}/cancel |
| X-API-Key: your_api_key |
| ``` |
|
|
| ### 7.2 规则 |
|
|
| - `pending` / `running` 可取消 |
| - 已结束批次再次取消会返回 `400` |
| - 批次不存在返回 `404` |
|
|
| --- |
|
|
| ## 8. 错误码说明 |
|
|
| | 状态码 | 含义 | 建议处理 | |
| | --- | --- | --- | |
| | `401` | API Key 错误 | 检查 `X-API-Key` | |
| | `403` | 外部 API 未启用 / Key 未配置 | 联系项目方 | |
| | `404` | 批次不存在 | 检查 `batch_uuid` | |
| | `422` | 请求体校验失败 | 修正 JSON 结构 | |
| | `400` | 业务参数错误 | 检查 `service_id` / provider / 状态 | |
| | `503` | 服务暂时不可用 | 稍后重试 | |
|
|
| --- |
|
|
| ## 9. 第三方最小实现建议 |
|
|
| 第三方系统至少实现以下逻辑： |
|
|
| ### 9.1 初始化 |
|
|
| - 保存 `Base URL` |
| - 保存 `X-API-Key` |
|
|
| ### 9.2 下发任务前 |
|
|
| - 调一次 `GET /external/capabilities` |
| - 读取当前可用邮箱类型 |
| - 如需固定服务，读取对应 `service_id` |
|
|
| ### 9.3 创建任务 |
|
|
| - 调 `POST /external/registration/batches` |
| - 保存返回的 `batch_uuid` |
|
|
| ### 9.4 查询任务 |
|
|
| - 周期轮询 `GET /external/registration/batches/{batch_uuid}` |
| - 直到进入终态 |
|
|
| ### 9.5 终态处理 |
|
|
| - `completed`：当作成功 |
| - `completed_partial`：按成功数/失败数决定业务处理 |
| - `failed`：整体失败 |
| - `cancelled`：任务已取消 |
|
|
| --- |
|
|
| ## 10. 推荐对接原则 |
|
|
| ### 原则 1：永远先读 `capabilities` |
|
|
| 不要在第三方代码里写死： |
|
|
| - 邮箱类型 |
| - 上传 provider |
| - `service_id` |
|
|
| ### 原则 2：建议总是传 `idempotency_key` |
| |
| 这样上游超时重试时，不会重复创建同一批次。 |
| |
| ### 原则 3：如果不关心具体服务，就不要传 `service_id` |
|
|
| 直接让系统自动选，能减少耦合。 |
|
|
| ### 原则 4：把结果当作“批次结果”处理 |
|
|
| 第三方调用的是批次任务，不是单账号实时接口。 |
| 请以批次维度读取： |
|
|
| - 请求数量 |
| - 成功数量 |
| - 失败数量 |
| - 上传成功/失败数量 |
|
|
| --- |
|
|
| ## 11. 一段可以直接发给技术对接方的话 |
|
|
| 你可以直接把下面这段发给对方： |
|
|
| ```text |
| 对接地址： |
| http://your-domain:8000/api |
| |
| 认证方式： |
| 请求头增加： |
| X-API-Key: your_api_key |
| |
| 先调用： |
| GET /external/capabilities |
| 用来获取当前可用邮箱类型、上传 provider，以及每个服务对应的 service_id 和 name。 |
| |
| 再调用： |
| POST /external/registration/batches |
| 创建注册批次。 |
| |
| 查询状态： |
| GET /external/registration/batches/{batch_uuid} |
| |
| 取消任务： |
| POST /external/registration/batches/{batch_uuid}/cancel |
| |
| 注意： |
| 1. service_id 不要猜，必须来自 capabilities 返回 |
| 2. 如果不指定 service_id，系统会自动选择可用服务 |
| 3. API Key 由项目方提供，不是通过接口申请 |
| ``` |
|
|
