Blame for docs/third-party-integration-guide.md

# 第三方技术对接文档

这份文档是给第三方技术人员直接对接用的。  
按本文档接入即可完成：

- 查询当前可用邮箱/上传服务
- 创建注册批次
- 查询批次状态
- 取消批次

如需更详细字段说明，可再参考：

- [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 由项目方提供，不是通过接口申请
```