# TrackFlow API 接入文档

本文档描述 TrackFlow 网页正在使用的物流查询 API，适合开发者或 AI Agent 集成。

Markdown 地址：

```text
https://tracking.rw2.cc/api-integration.md
```

## 基本信息

- API Base URL：`https://tracking.rw2.cc/api`
- 数据格式：JSON
- 字符编码：UTF-8
- 查询接口为异步接口：提交后立即返回批次，随后轮询批次状态
- 单次请求最多提交 `10000` 个有效运单号，重复运单号会自动去重
- 生产环境建议显式传入自己的 `apikey`，不要把 API key 暴露在公开前端代码中

除特别说明外，请求头建议设置：

```http
Accept: application/json
Content-Type: application/json
```

## 快速开始

### 1. 提交查询

```bash
curl -X POST 'https://tracking.rw2.cc/api/track' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "YOUR_API_KEY",
    "tracking_numbers": [
      "9400111899223856928498",
      "1Z999AA10123456784"
    ],
    "carrier": "auto",
    "mode": "manual"
  }'
```

成功返回 HTTP `202`：

```json
{
  "batch": {
    "id": "7f4a1f42-7a5a-4dfb-9e7a-4f48d9e6d3f0",
    "carrier": "mixed",
    "mode": "manual",
    "status": "processing",
    "is_submitting": false,
    "total_count": 2,
    "cached_count": 0,
    "pending_count": 2,
    "running_count": 0,
    "completed_count": 0,
    "failed_count": 0,
    "category_counts": {},
    "items": [],
    "items_pagination": {
      "limit": 80,
      "offset": 0,
      "count": 0,
      "total": 2,
      "has_more": true,
      "category": "all"
    }
  }
}
```

保存返回的 `batch.id`，用于后续查询结果。

### 2. 轮询批次结果

```bash
curl 'https://tracking.rw2.cc/api/batches/BATCH_ID?include_items=1&items_limit=80&items_offset=0&category=all' \
  -H 'Accept: application/json'
```

当 `batch.status` 为 `pending` 或 `processing` 时继续轮询。建议间隔 `1-3` 秒；当状态为 `completed` 或 `failed` 时停止轮询。

如果需要一次返回批次中的全部运单号，可使用：

```text
GET /api/batches/{batch_id}?include_items=0&include_tracking_numbers=1
```

## 提交接口

### `POST /api/track`

提交一批物流查询任务。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tracking_numbers` | array/string | 是 | 运单号数组，或以换行、逗号、分号分隔的字符串。只保留 8-40 位字母数字组合。 |
| `apikey` | string | 否 | API key。省略或为空时使用服务端默认 key；公开集成建议传入自己的 key。 |
| `carrier` | string | 否 | `auto`、`usps`、`ups`、`fedex`、`dhl`、`auspost`，默认 `auto`。 |
| `mode` | string | 否 | 查询模式标识，网页使用 `manual` 或 `realtime`。 |
| `bypass_cache` | boolean | 否 | 是否跳过缓存并重新查询，网页实时查询使用 `true`。 |
| `batch_id` | UUID | 否 | 追加提交到一个仍在提交中的批次。需与创建该批次的 key 匹配。 |
| `submission_complete` | boolean | 否 | 是否完成当前批次提交，默认 `true`。分批提交时前面的请求传 `false`，最后一个请求传 `true`。 |

### 超过 10000 条时分批提交到同一个批次

网页对大文件采用以下方式：

1. 第一次提交最多 10000 条，传 `submission_complete=false`。
2. 从第一次响应中取得 `batch.id`。
3. 后续请求传相同的 `batch_id`，每次最多 10000 条，并继续传 `submission_complete=false`。
4. 最后一次传 `submission_complete=true`。

示例：

```bash
curl -X POST 'https://tracking.rw2.cc/api/track' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "YOUR_API_KEY",
    "tracking_numbers": ["NUMBER_00000001", "NUMBER_00000002"],
    "carrier": "auto",
    "mode": "manual",
    "submission_complete": false
  }'
```

后续请求：

```bash
curl -X POST 'https://tracking.rw2.cc/api/track' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "YOUR_API_KEY",
    "batch_id": "BATCH_ID_FROM_FIRST_RESPONSE",
    "tracking_numbers": ["NUMBER_00000003", "NUMBER_00000004"],
    "carrier": "auto",
    "mode": "manual",
    "submission_complete": true
  }'
```

## 批次结果

### `GET /api/batches/{batch_id}`

查询批次状态和结果。

Query 参数：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `include_items` | `true` | 是否返回结果明细。 |
| `include_tracking_numbers` | `false` | 是否返回完整运单号数组。历史批次回填查询框时使用 `true`。 |
| `items_limit` | `80` | 本次返回的明细数量，最大 `500`。 |
| `items_offset` | `0` | 明细偏移量，用于分页。 |
| `category` | `all` | `all`、`delivered`、`in_transit`、`label_created`、`exception`、`stale`、`no_tracking`。 |

返回的 `batch.items[]` 中，每条明细包含：

- `tracking_number`：运单号
- `carrier`：承运商
- `status`：`pending`、`running`、`succeeded`、`cached` 或 `failed`
- `error`：失败原因，没有错误时为 `null`
- `snapshot.status_category`：状态分类
- `snapshot.status_text`：英文或原始状态
- `snapshot.status_text_zh`：中文状态
- `snapshot.latest_location`：最新位置
- `snapshot.latest_event_at`：最新轨迹时间，ISO 8601
- `snapshot.delivered`：是否签收
- `snapshot.alert`：警告信息
- `snapshot.events`：轨迹事件数组

## 其他接口

### `GET /api/health`

健康检查：

```json
{
  "status": "ok"
}
```

### `GET /api/auth/status`

查询 API key 剩余额度：

```text
GET /api/auth/status?apikey=YOUR_API_KEY
```

成功返回：

```json
{
  "status": "success",
  "remaining": 1234,
  "label": "YOUR..._KEY",
  "is_default": false
}
```

### `GET /api/history`

查询指定 API key 的历史批次，最多返回最近 100 个批次：

```text
GET /api/history?apikey=YOUR_API_KEY
```

### `PATCH /api/batches/{batch_id}/note`

修改批次名称：

```bash
curl -X PATCH 'https://tracking.rw2.cc/api/batches/BATCH_ID/note' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "apikey": "YOUR_API_KEY",
    "note": "供应商 A - 10 月 10 日"
  }'
```

### `GET /api/export`

导出 Excel。单批次：

```text
GET /api/export?batch_id=BATCH_ID
```

合并多个批次：

```text
GET /api/export?batch_ids[]=BATCH_ID_1&batch_ids[]=BATCH_ID_2
```

可选参数：
- `with_first_event=1`：导出首条物理轨迹（自动排除标签创建等预上网事件）。默认为不导出。

返回 `.xlsx` 文件。批次结果应在完成后导出。

## 错误处理

常见 HTTP 状态码：

| 状态码 | 含义 |
| --- | --- |
| `202` | 查询已接受，结果异步处理。 |
| `200` | 查询成功。 |
| `401` | 未认证或认证失败。 |
| `403` | API key 无权访问该批次。 |
| `409` | 批次已经结束，不能继续追加。 |
| `422` | 请求参数错误，或没有有效运单号。 |
| `429` | 访客额度或请求频率限制。 |
| `502` | 上游承运商接口暂时失败。 |

参数校验失败通常返回：

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "tracking_numbers": ["The tracking numbers field is required."]
  }
}
```

## AI Agent 集成建议

将以下地址作为 Markdown 文档源提供给 AI：

```text
https://tracking.rw2.cc/api-integration.md
```

推荐调用顺序：

1. `POST /api/track` 提交运单号。
2. 记录响应中的 `batch.id`。
3. 每隔 1-3 秒调用 `GET /api/batches/{batch_id}`。
4. 读取 `batch.items` 和 `batch.items_pagination`。
5. 当 `batch.status` 为 `completed` 或 `failed` 时结束轮询。

不要把 API key 写入日志、公开代码仓库或返回给不可信的客户端。