# 物流轨迹查询 API 接入文档

面向已开通账号的客户。接入后，你的系统可直接查询运单/转单号的物流轨迹与状态。

- **接口地址**：`https://track.monina.xyz/api/track`
- **数据格式**：JSON（UTF-8）
- **传输协议**：HTTPS

---

## 一、快速开始

三步即可完成接入。

**第 1 步**：拿到你的专属 API Key

API Key 由服务方提供，形如 `tk_xxxxxxxxxxxxxxxxxxxxxxxx`。请妥善保管，不要放在前端页面里。

**第 2 步**：发起一次查询

**Key 请放在 JSON 请求体的 `key` 字段**（推荐），或网址 `?key=` 参数。不要用 `X-API-Key` 请求头——部署平台的网关会删除自定义请求头，导致 Key 无法到达服务端、按匿名访问计费。

```bash
curl -s -X POST "https://track.monina.xyz/api/track" \
  -H "Content-Type: application/json" \
  -d '{"key":"tk_你的Key","numbers":["QYAL260907001"]}'
```

**第 3 步**：解析返回的 JSON

```json
{
  "ok": true,
  "auth": "key",
  "results": [
    {
      "number": "QYAL260907001",
      "status": "signed",
      "statusLabel": "已签收",
      "statusDesc": "货物已成功签收",
      "channel": "c2",
      "latestInfo": "【FR ANNECY】 已递送",
      "latestTime": "2026-09-18 13:00:34",
      "destination": "法国 74960",
      "carrier": "",
      "note": "",
      "traceCount": 19,
      "traces": [
        { "time": "2026-09-18 13:00:34", "info": "【FR ANNECY】 已递送" }
      ]
    }
  ],
  "summary": {
    "total": 1, "signed": 1, "inTransit": 0,
    "abnormal": 0, "offline": 0, "notFound": 0, "failed": 0
  },
  "cached": 0,
  "queried": 1,
  "elapsedMs": 1801
}
```

---

## 二、接口详情

### 查询轨迹

| 项目 | 说明 |
|---|---|
| 请求地址 | `https://track.monina.xyz/api/track` |
| 请求方法 | `GET` 或 `POST` |
| 编码 | UTF-8 |

#### 请求参数

| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| `numbers` | Query / Body | String / Array | 是 | 单号，多个用**换行、逗号、分号、空格或 Tab** 分隔 |
| `number` | Query / Body | String | 否 | `numbers` 的别名，二者用其一即可 |
| `key` | Query / Body | String | 是 | API Key。POST 放 JSON 体的 `key` 字段（推荐），GET 放 `?key=` 查询参数。**不要用 `X-API-Key` 请求头**（部署网关会删除自定义头，Key 将无法到达服务端） |

> **单号格式**：纯文本，不带空格，不区分大小写，服务端会统一转为大写。少于 6 位的会被视为无效单号并忽略。
> 去重后返回，因此重复提交同一单号不会得到重复结果。

> **传 Key 方式的安全提示**：`?key=` 参数会留在 URL 里（浏览器历史、访问日志可见），
> 对安全性有要求时请优先用 POST + 请求体方式。

#### GET 请求示例

```bash
curl "https://track.monina.xyz/api/track?numbers=QYAL260907001,QLAG260908002&key=tk_你的Key"
```

#### POST 请求示例（推荐用于生产）

单号较多、含特殊字符或需要传递 Key 时，都用 POST + JSON：既避开 URL 长度限制与转义问题，
Key 也不会出现在网址里。

```bash
curl -X POST "https://track.monina.xyz/api/track" \
  -H "Content-Type: application/json" \
  -d '{"key":"tk_你的Key","numbers":["QYAL260907001","QLAG260908002"]}'
```

### 请求签名（按需启用）

服务方为你的 Key 开启「强制请求签名」后，每个请求必须在 JSON 体里额外携带
`timestamp`、`nonce`、`sign` 三个字段，否则返回 `401`。未开启时无需携带
（带了且签名正确也会正常受理）。

**签名算法**（HMAC-SHA256）：

```javascript
const crypto = require('crypto');

const SIGN_SECRET = 'ss_你的签名密钥'; // 由服务方提供，与 API Key 相互独立

const timestamp = Math.floor(Date.now() / 1000);          // 秒级 Unix 时间戳
const nonce = crypto.randomBytes(8).toString('hex');      // 每次请求都不同的随机串
const numbersStr = numbers.join(',');                     // numbers 为数组时用逗号连接；为字符串时用原文

const sign = crypto.createHmac('sha256', SIGN_SECRET)
  .update(`${timestamp}|${nonce}|${numbersStr}`, 'utf8')
  .digest('hex');

// 请求体：
// { "key": "tk_你的Key", "numbers": [...], "timestamp": timestamp, "nonce": nonce, "sign": sign }
```

完整示例：

```bash
TS=$(date +%s)
NONCE=$(openssl rand -hex 8)
NUMBERS='QYAL260907001'
SIGN=$(printf '%s|%s|%s' "$TS" "$NONCE" "$NUMBERS" \
  | openssl dgst -sha256 -hmac 'ss_你的签名密钥' -hex | sed 's/^.*= //')

curl -s -X POST "https://track.monina.xyz/api/track" \
  -H "Content-Type: application/json" \
  -d "{\"key\":\"tk_你的Key\",\"numbers\":[\"$NUMBERS\"],\"timestamp\":$TS,\"nonce\":\"$NONCE\",\"sign\":\"$SIGN\"}"
```

**校验规则**（服务端）：

| 规则 | 说明 |
|---|---|
| 时间窗 | `timestamp` 与服务器时间相差不超过 ±90 秒。**请确保你的服务器时钟准确**（建议启用 NTP 校时） |
| 一次性 | 同一 `nonce` 在 5 分钟内只能使用一次，重复提交会被拒绝 —— **不要为重试复用同一个 nonce**，每次请求（包括重试）都要重新生成 |
| 绑定单号 | 签名串里的单号必须与请求中的 `numbers` **原文完全一致**（数组按顺序逗号连接） |

> 常见失败原因：时钟偏差超过时间窗（最常见）、复用了 nonce、单号大小写或顺序与签名时不一致。

---

## 三、响应字段说明

### 顶层字段

| 字段 | 类型 | 说明 |
|---|---|---|
| `ok` | Boolean | 请求是否成功。`true` 表示查询完成 |
| `auth` | String | 本次计费身份：`key`＝按你的 Key 计费；`anonymous`＝未识别到 Key，按匿名计费（请检查传 Key 方式） |
| `results` | Array | 轨迹结果数组，见下方详情 |
| `summary` | Object | 本次批量查询的状态统计 |
| `cached` | Number | 命中缓存的单号数（未向上游发起请求） |
| `queried` | Number | 本次实际向上游查询的单号数 |
| `elapsedMs` | Number | 本次查询耗时（毫秒） |

> `cached + queried` 等于你提交的单号总数（去重后）。

### `summary` 状态统计

| 字段 | 说明 |
|---|---|
| `total` | 本次提交的单号总数 |
| `signed` | 已签收 |
| `inTransit` | 运输中 |
| `abnormal` | 运输异常（货物有状况，需联系承运方） |
| `offline` | 待揽收（承运系统尚未收到扫描，非异常） |
| `notFound` | 查不到（所有渠道均未收录） |
| `failed` | 查询失败（接口异常，可重试） |

### `results[]` 单条轨迹

| 字段 | 类型 | 说明 |
|---|---|---|
| `number` | String | 单号 |
| `status` | String | 状态代码，取值见下节 |
| `statusLabel` | String | 状态中文名，如「已签收」 |
| `statusDesc` | String | 状态说明，可直接展示给终端用户 |
| `statusLabelEn` | String | 状态英文名，如 `Delivered`。**英文界面用这个** |
| `statusDescEn` | String | 状态英文说明 |
| `channel` | String / null | 查询来源代号。**该字段仅供你判断「数据是否可信」，建议不要展示给终端用户** |
| `latestInfo` | String | 最新一条轨迹描述 |
| `latestTime` | String | 最新轨迹时间，`YYYY-MM-DD HH:mm:ss` |
| `destination` | String | 目的地，如「法国 74960」 |
| `carrier` | String | 末端承运商单号，无则为空字符串 |
| `note` | String | 补充提示。**非空时建议展示给用户**，详见第五节 |
| `traceCount` | Number | 轨迹条数 |
| `traces` | Array | 轨迹明细，**按时间倒序**（第一条为最新） |

### `traces[]` 轨迹明细

| 字段 | 类型 | 说明 |
|---|---|---|
| `time` | String | 时间，`YYYY-MM-DD HH:mm:ss` |
| `info` | String | 轨迹描述 |

> **轨迹条数说明**：单次返回最多 100 条轨迹。`traceCount` 是实际轨迹总条数，可能大于 `traces` 数组长度。

---

## 四、状态字典

| `status` | `statusLabel` | `statusLabelEn` | 含义与建议动作 |
|---|---|---|---|
| `signed` | 已签收 | Delivered | 查询成功。货物已签收 |
| `inTransit` | 运输中 | In transit | 查询成功。运输途中，展示最新轨迹 |
| `abnormal` | 运输异常 | Abnormal | **查询成功**，但承运方提示清关或派送异常。需联系承运方处理 |
| `offline` | 待揽收 | Not yet picked up | 承运系统尚未收到扫描。通常是刚下单或刚揽收，隔天再查即可，**非异常** |
| `notFound` | 查不到 | Not found | 所有渠道均未收录。可能尚未录入承运系统 |
| `failed` | 查询失败 | Query failed | 上游接口异常，**可稍后重试** |

> **英文界面请用 `statusLabelEn` / `statusDescEn`**：状态标签由接口直接给出中英文两套，
> 你不需要自建翻译表 —— 翻译表一旦与实际状态脱节，就会显示错误文案。
>
> 但轨迹文本（`latestInfo`、`traces[].info`）来自各国承运系统，本接口只把英文短语中译成中文，
> 其他语言原样返回。若你的界面需要统一语言，请按 `status` 映射自己的文案，不要依赖轨迹原文。

> **`abnormal` 与 `failed` 请勿混淆**：
> - `abnormal` 是**货物本身**有状况（清关/派送异常），数据是可信的；
> - `failed` 是**查询动作**失败，数据不可信。
>
> 这个区分对业务判断很关键，请按上表处理，不要统一当成「异常」。

若需程序化获取状态字典（避免在代码里硬编码中文），可调用：

```bash
curl "https://track.monina.xyz/api/status-meta"
```

---

## 五、`note` 字段的特殊说明

在部分情况下，`note` 会有内容，需要你关注：

| `note` 内容 | 含义 | 建议 |
|---|---|---|
| `本次查询未命中，显示上次结果（2026-09-18 13:00:34）` | 本次未查到，但返回了历史有效轨迹 | 正常展示轨迹，并可提示「数据可能不是最新」 |
| `承运方提示清关异常` | 清关环节有状况 | 提示用户联系承运方 |
| `承运方提示派送异常` | 派送环节有状况 | 提示用户联系承运方 |

---

## 六、错误处理

出错时返回 **HTTP 状态码** + 以下结构：

```json
{
  "ok": false,
  "error": "错误描述（可直接展示给用户）",
  "code": "错误代码"
}
```

### 错误码对照

| HTTP | `code` | 含义 | 处理建议 |
|---|---|---|---|
| 400 | — | 参数错误（单号为空/不合法，或超出单次上限） | 检查请求参数 |
| 401 | `auth` | 认证失败：Key 未携带、无效、已停用，或请求签名校验未通过 | 依次核对：Key 是否正确携带、有无多余空格；签名三件套（`timestamp`/`nonce`/`sign`）是否齐全且在有效期内。仍无法解决请联系服务方 |
| 429 | `quota` | 当日调用额度已用尽 | 见响应头 `Retry-After`，次日 0 点（东八区）自动恢复 |
| 429 | `rate` | 请求过于频繁 | 按 `Retry-After` 退避后重试 |
| 502 | — | 上游查询异常 | 稍后重试 |
| 404 | — | 接口路径错误 | 检查请求地址 |

> **关于 `auth` 错误码**：服务端刻意不区分「Key 缺失」「Key 无效」「Key 停用」「签名错误」——
> 这几类失败返回完全相同的状态码、`code` 与文案，这是防撞库设计的一部分。
> 排查时请按上表建议逐项自检。

> **`error` 字段是面向用户的中文说明**，可直接展示给终端用户。

### 重试建议

- `rate` / `quota`：**必须**遵循 `Retry-After`，不要立即重试。
- `502`：可退避重试，建议间隔 2 秒、最多 2 次。
- `failed` 状态的轨迹单号：建议间隔 30 秒后重查。
- 建议对单次请求设置 **30 秒超时**，超时按失败处理并加入重试队列。

---

## 七、调用频率与配额

| 项目 | 限制 |
|---|---|
| 单次最多单号数 | 50 个（超出返回 400） |
| 每 IP 请求频率 | 30 次 / 分钟（超出返回 429） |
| 每 Key 请求频率 | 通常 60 次 / 分钟（超出返回 429；具体以服务方配置为准） |
| 每日调用额度 | 3000 次（超出返回 429，次日 0 点重置） |

> 具体额度可按需调整，如需提高请联系服务方。

### 缓存机制（重要）

为保护上游系统、稳定响应速度，服务端内置缓存：

- **已签收**的单号缓存 **7 天**（状态不再变化）；
- **其他状态**的单号缓存 **30 分钟**。

这意味着：

1. 短时间内重复查询同一单号，返回的是缓存结果，`cached` 计数会增加，`elapsedMs` 会显著变小；
2. 运输中的单号**最多 30 分钟更新一次**，无需高频轮询；
3. 你无需自己再做一层缓存，直接透传即可。

### 关于耗时

单次查询会依次尝试多个渠道，命中后即停止。正常情况下：

- **缓存命中**：几十毫秒内返回；
- **缓存未命中（需向上游查询）**：约 2～8 秒，取决于单号数量。

建议：
- 查询量较大时**分批提交**（每批 20～50 个单号），避免单次请求超时；
- 前端展示加载状态，不要让用户干等。

---

## 八、代码示例

以下示例统一使用 **POST + JSON 请求体**传 Key（`key` 字段），生产环境推荐写法。

### cURL

```bash
curl -s -X POST "https://track.monina.xyz/api/track" \
  -H "Content-Type: application/json" \
  -d '{"key":"tk_你的Key","numbers":["QYAL260907001"]}'
```

### PHP

```php
<?php
function trackShipment(string $numbers, string $apiKey): array
{
    $ch = curl_init('https://track.monina.xyz/api/track');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode([
            'key'     => $apiKey,                              // Key 放请求体
            'numbers' => explode(',', $numbers),
        ]),
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
        ],
    ]);

    $body  = curl_exec($ch);
    $errno = curl_errno($ch);
    $err   = curl_error($ch);   // 必须在 curl_close 之前取
    curl_close($ch);

    if ($errno !== 0) {
        throw new RuntimeException('网络请求失败: ' . $err);
    }

    $data = json_decode((string)$body, true);
    if (!is_array($data)) {
        throw new RuntimeException('返回内容不是合法 JSON');
    }
    if (empty($data['ok'])) {
        // error 字段是可直接展示给用户的中文说明
        throw new RuntimeException($data['error'] ?? '查询失败');
    }

    return $data['results'];
}

// 使用
foreach (trackShipment('QYAL260907001', 'tk_你的Key') as $item) {
    echo $item['number'] . ' ' . $item['statusLabel'] . ' ' . $item['latestInfo'] . PHP_EOL;

    // note 非空时建议展示给用户（如「本次查询未命中，显示上次结果」）
    if (!empty($item['note'])) {
        echo '  提示: ' . $item['note'] . PHP_EOL;
    }
}
```

### Python

```python
import requests

API_URL = "https://track.monina.xyz/api/track"
API_KEY = "tk_你的Key"

def track(numbers, api_key=API_KEY, timeout=30):
    """查询轨迹，返回 results 列表。失败时抛出异常。"""
    try:
        resp = requests.post(
            API_URL,
            json={"key": api_key, "numbers": numbers},  # Key 放请求体
            timeout=timeout,
        )
        data = resp.json()
    except requests.Timeout:
        raise RuntimeError("查询超时，请稍后重试")
    except ValueError:
        raise RuntimeError("返回内容不是合法 JSON")

    if not data.get("ok"):
        # error 字段是可直接展示给用户的中文说明
        raise RuntimeError(data.get("error", "查询失败"))

    return data["results"]

# 使用
for item in track(["QYAL260907001", "QLAG260908002"]):
    print(item["number"], item["statusLabel"], item["latestInfo"])

    if item.get("note"):
        print("  提示:", item["note"])
```

### JavaScript (Node.js)

```javascript
const API_URL = 'https://track.monina.xyz/api/track';
const API_KEY = 'tk_你的Key';

async function track(numbers) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 30000);

  try {
    const res = await fetch(API_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ key: API_KEY, numbers }),  // Key 放请求体
      signal: controller.signal,
    });

    const data = await res.json();
    if (!data.ok) {
      // error 字段是可直接展示给用户的中文说明
      throw new Error(data.error || '查询失败');
    }
    return data.results;
  } finally {
    clearTimeout(timer);
  }
}

// 使用
(async () => {
  const results = await track(['QYAL260907001', 'QLAG260908002']);
  for (const r of results) {
    console.log(r.number, r.statusLabel, r.latestInfo);
    if (r.note) console.log('  提示:', r.note);
  }
})();
```

### 浏览器端调用（仅用于测试）

接口已开启 CORS，可在浏览器直接调用。**但请勿在生产环境这样做**——浏览器端无法隐藏 API Key。

```javascript
fetch('https://track.monina.xyz/api/track?numbers=QYAL260907001&key=tk_你的Key')
  .then(r => r.json())
  .then(data => console.log(data.results));
```

---

## 九、接入检查清单

上线前请逐项确认：

- [ ] API Key 保存在**服务端**，未出现在前端代码或页面中
- [ ] Key 通过 **JSON 请求体 `key` 字段**（POST，推荐）或 `?key=` 参数传递，未使用 `X-API-Key` 请求头
- [ ] 响应里 `auth` 为 `"key"`（若为 `"anonymous"`，说明 Key 没有到达服务端）
- [ ] 请求超时设置不低于 30 秒
- [ ] 对 `429` 状态码做了处理，且遵循 `Retry-After` 退避
- [ ] `note` 字段非空时有展示逻辑
- [ ] `abnormal`（运输异常）与 `failed`（查询失败）分别处理
- [ ] 单次提交单号数不超过 50
- [ ] 查询进度有加载提示，未让用户干等

---

## 十、常见问题

**Q · 为什么有的单号返回「查不到」？**
A · 所有渠道均未收录该单号。常见原因是承运系统尚未录入（刚下单未揽收、或单号有误）。建议隔天重查；已签收的历史单号若查不到，请核对单号是否正确。

**Q · 「待揽收」是异常吗？**
A · 不是。这表示承运系统还没收到扫描，通常是刚下单或刚揽收，属正常状态，隔天再查即可。

**Q · 「运输异常」和「查询失败」有什么区别？**
A · 「运输异常」是**货物有状况**（清关或派送异常），数据可信，需联系承运方；「查询失败」是**查询动作**本身失败，数据不可信，稍后重试。请勿混淆。

**Q · 为什么同一单号查两次，`cached` 数不一样？**
A · 服务端有缓存机制（已签收缓存 7 天，其余 30 分钟）。命中缓存时不会向上游发起请求，响应更快。属于正常现象。

**Q · 支持哪些单号？运单号和转单号都可以吗？**
A · 都可以。单号会自动转为大写，不区分大小写。

**Q · `channel` 字段是什么？**
A · 查询来源代号，用于你判断数据可信度。**建议不要展示给终端用户**，也不要在界面上解释其含义。

**Q · 轨迹条数被截断了？**
A · 单次最多返回 100 条轨迹。`traceCount` 为实际总条数，可能大于返回的数组长度。

**Q · 接口能保证实时吗？**
A · 数据来自承运方系统同步，存在延迟。运输中的单号最多 30 分钟更新一次，不建议高频轮询。

**Q · 我明确带了 Key，为什么调用被记为「匿名」、配额也不扣？**
A · 大概率你用了 `X-API-Key` 请求头——部署平台的网关会删除自定义请求头，Key 根本没到服务端。请改用 **POST 请求体 `key` 字段**（推荐）或 `?key=` 参数。每个成功响应都带 `auth` 字段：`"key"` 表示已按你的 Key 计费，`"anonymous"` 表示 Key 没被识别。也可以用 `GET /api/header-echo` 检查你的请求头能否到达服务端（该端点只返回头名，不返回头值）。

**Q · API Key 泄露了怎么办？**
A · 立即联系服务方停用并重新生成。

---

## 十一、技术支持

| 项目 | 内容 |
|---|---|
| 接口地址 | `https://track.monina.xyz` |
| 健康检查 | `GET /api/health` |
| 状态字典 | `GET /api/status-meta` |
| 请求头诊断 | `GET /api/header-echo`（查看哪些请求头能到达服务端） |

技术支持与额度调整，请联系你的服务对接人。

---

*文档版本：v1.0　更新日期：2026-10-16*
