Blame for docs/external-api-examples.md

# External API 调用示例

本文档提供外部注册 API 的最常用调用示例，便于脚本、面板或第三方系统直接接入。

相关主说明见：

- [Temp Mail 域名池与外部注册 API 说明](temp-mail-external-api.md)

---

## 1. 基本约定

假设你的服务地址为：

```text
http://127.0.0.1:8000/api
```

假设外部 API Key 为：

```text
your_api_key
```

所有请求都需要带：

```http
X-API-Key: your_api_key
```

这个值的来源是项目管理员在系统配置里设置的 `external_api_key`。  
当前版本没有开放“申请/查询 API Key”接口，第三方只能由管理员直接发放。

---

## 2. 查询能力

### curl

```bash
curl -X GET "http://127.0.0.1:8000/api/external/capabilities" \
  -H "X-API-Key: your_api_key"
```

### Python

```python
import requests

resp = requests.get(
    "http://127.0.0.1:8000/api/external/capabilities",
    headers={"X-API-Key": "your_api_key"},
    timeout=30,
)
print(resp.status_code)
print(resp.json())
```

假设返回里有：

```json
{
  "email_types": [
    {
      "type": "temp_mail",
      "services": [
        {"id": 3, "name": "Worker temp mail A"},
        {"id": 7, "name": "Worker temp mail B"}
      ]
    }
  ],
  "upload_providers": [
    {
      "provider": "sub2api",
      "services": [
        {"id": 1, "name": "sub2-main"},
        {"id": 4, "name": "sub2-backup"}
      ]
    }
  ]
}
```

那么：

- `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`

不要自己猜数字含义，始终以 `capabilities` 返回结果为准。

---

## 3. 创建注册批次

### 3.1 使用 temp_mail，不上传

#### curl

```bash
curl -X POST "http://127.0.0.1:8000/api/external/registration/batches" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "count": 3,
    "email": {
      "type": "temp_mail"
    },
    "upload": {
      "enabled": false
    },
    "execution": {
      "mode": "pipeline",
      "concurrency": 1,
      "interval_min": 5,
      "interval_max": 10
    }
  }'
```

#### Python

```python
import requests

payload = {
    "count": 3,
    "email": {"type": "temp_mail"},
    "upload": {"enabled": False},
    "execution": {
        "mode": "pipeline",
        "concurrency": 1,
        "interval_min": 5,
        "interval_max": 10,
    },
}

resp = requests.post(
    "http://127.0.0.1:8000/api/external/registration/batches",
    headers={
        "X-API-Key": "your_api_key",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)

print(resp.status_code)
print(resp.json())
```

---

### 3.2 指定某个邮箱服务并自动上传到 sub2api

#### curl

```bash
curl -X POST "http://127.0.0.1:8000/api/external/registration/batches" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "count": 5,
    "idempotency_key": "batch-demo-001",
    "email": {
      "type": "temp_mail",
      "service_id": 1
    },
    "upload": {
      "enabled": true,
      "provider": "sub2api",
      "service_id": 1
    },
    "execution": {
      "mode": "parallel",
      "concurrency": 3,
      "interval_min": 0,
      "interval_max": 0
    }
  }'
```

#### Python

```python
import requests

payload = {
    "count": 5,
    "idempotency_key": "batch-demo-001",
    "email": {
        "type": "temp_mail",
        "service_id": 1,
    },
    "upload": {
        "enabled": True,
        "provider": "sub2api",
        "service_id": 1,
    },
    "execution": {
        "mode": "parallel",
        "concurrency": 3,
        "interval_min": 0,
        "interval_max": 0,
    },
}

resp = requests.post(
    "http://127.0.0.1:8000/api/external/registration/batches",
    headers={
        "X-API-Key": "your_api_key",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)

data = resp.json()
print(resp.status_code, data)
batch_uuid = data["batch_uuid"]
```

> 说明：
>
> - 首次创建一般返回 `202`
> - 如果 `idempotency_key` 命中历史批次，返回 `200`

---

### 3.3 不指定 service_id，交给系统自动选择

```python
import requests

payload = {
    "count": 2,
    "email": {
        "type": "temp_mail"
    },
    "upload": {
        "enabled": True,
        "provider": "sub2api"
    },
    "execution": {
        "mode": "pipeline",
        "concurrency": 1,
        "interval_min": 0,
        "interval_max": 0
    }
}

resp = requests.post(
    "http://127.0.0.1:8000/api/external/registration/batches",
    headers={
        "X-API-Key": "your_api_key",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)

print(resp.status_code)
print(resp.json())
```

适用场景：

- 你不关心固定某个邮箱服务
- 你不关心固定某个上传目标
- 只希望系统按当前可用配置自动兜底选择

---

## 附：`failure_category` 示例

`failure_category` 是给程序消费的稳定字段，允许值只有：

- `config`
- `business`
- `transient`
- `null`

### 示例 1：未失败批次

```json
{
  "batch_uuid": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "pending",
  "requested_count": 3,
  "completed_count": 0,
  "success_count": 0,
  "failed_count": 0,
  "upload_success_count": 0,
  "upload_failed_count": 0,
  "failure_reason": null,
  "failure_category": null,
  "recent_errors": [],
  "idempotent_replay": false
}
```

### 示例 2：可重试失败

```json
{
  "batch_uuid": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "failed",
  "requested_count": 3,
  "completed_count": 1,
  "success_count": 0,
  "failed_count": 1,
  "upload_success_count": 0,
  "upload_failed_count": 0,
  "failure_reason": "upstream timeout",
  "failure_category": "transient",
  "recent_errors": [
    "provider timeout"
  ],
  "idempotent_replay": false
}
```

### 示例 3：配置问题失败

```json
{
  "batch_uuid": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "failed",
  "requested_count": 3,
  "completed_count": 0,
  "success_count": 0,
  "failed_count": 0,
  "upload_success_count": 0,
  "upload_failed_count": 0,
  "failure_reason": "upload service not configured",
  "failure_category": "config",
  "recent_errors": [
    "upload provider sub2api has no configured service"
  ],
  "idempotent_replay": false
}
```

### 示例 4：cancel 响应

`POST /api/external/registration/batches/{batch_uuid}/cancel` 也可能返回 `failure_category`，只是为了和其他批次响应保持一致：

```json
{
  "batch_uuid": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "cancelled",
  "failure_reason": null,
  "failure_category": null
}
```

---

## 4. 查询批次状态

### curl

```bash
curl -X GET "http://127.0.0.1:8000/api/external/registration/batches/<batch_uuid>" \
  -H "X-API-Key: your_api_key"
```

### Python

```python
import requests
import time

batch_uuid = "replace-with-real-batch-uuid"

while True:
    resp = requests.get(
        f"http://127.0.0.1:8000/api/external/registration/batches/{batch_uuid}",
        headers={"X-API-Key": "your_api_key"},
        timeout=30,
    )
    data = resp.json()
    print(data)

    if data["status"] in {"completed", "completed_partial", "failed", "cancelled"}:
        break

    time.sleep(5)
```

---

## 5. 取消批次

### curl

```bash
curl -X POST "http://127.0.0.1:8000/api/external/registration/batches/<batch_uuid>/cancel" \
  -H "X-API-Key: your_api_key"
```

### Python

```python
import requests

batch_uuid = "replace-with-real-batch-uuid"

resp = requests.post(
    f"http://127.0.0.1:8000/api/external/registration/batches/{batch_uuid}/cancel",
    headers={"X-API-Key": "your_api_key"},
    timeout=30,
)

print(resp.status_code)
print(resp.json())
```

---

## 6. 常见返回示例

### 6.1 创建成功

```json
{
  "batch_uuid": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "status": "pending",
  "requested_count": 3,
  "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
}
```

### 6.2 参数错误

```json
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body"],
      "msg": "Value error, upload.provider is required when upload.enabled is true",
      "input": {}
    }
  ]
}
```

### 6.3 批次不存在

```json
{
  "detail": "batch_not_found"
}
```

---

## 7. 最简 Python 封装示例

```python
import time
import requests


class ExternalRegisterClient:
    def __init__(self, base_url: str, api_key: str):
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({"X-API-Key": api_key})

    def capabilities(self):
        return self.session.get(f"{self.base_url}/external/capabilities", timeout=30).json()

    def create_batch(self, payload: dict):
        return self.session.post(
            f"{self.base_url}/external/registration/batches",
            json=payload,
            timeout=30,
        ).json()

    def get_batch(self, batch_uuid: str):
        return self.session.get(
            f"{self.base_url}/external/registration/batches/{batch_uuid}",
            timeout=30,
        ).json()

    def cancel_batch(self, batch_uuid: str):
        return self.session.post(
            f"{self.base_url}/external/registration/batches/{batch_uuid}/cancel",
            timeout=30,
        ).json()

    def wait_batch(self, batch_uuid: str, interval: int = 5):
        while True:
            data = self.get_batch(batch_uuid)
            if data["status"] in {"completed", "completed_partial", "failed", "cancelled"}:
                return data
            time.sleep(interval)


client = ExternalRegisterClient("http://127.0.0.1:8000/api", "your_api_key")

batch = client.create_batch({
    "count": 2,
    "email": {"type": "temp_mail"},
    "upload": {"enabled": False},
    "execution": {"mode": "pipeline", "concurrency": 1, "interval_min": 0, "interval_max": 0},
})

result = client.wait_batch(batch["batch_uuid"])
print(result)
```