物流轨迹查询 API 接入文档

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


一、快速开始

三步即可完成接入。

第 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

请求参数

参数位置类型必填说明
numbersQuery / BodyString / Array是单号,多个用换行、逗号、分号、空格或 Tab 分隔
numberQuery / BodyString否numbers 的别名,二者用其一即可
keyQuery / BodyString是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、单号大小写或顺序与签名时不一致。

三、响应字段说明

顶层字段

字段类型说明
okBoolean请求是否成功。true 表示查询完成
authString本次计费身份:key=按你的 Key 计费;anonymous=未识别到 Key,按匿名计费(请检查传 Key 方式)
resultsArray轨迹结果数组,见下方详情
summaryObject本次批量查询的状态统计
cachedNumber命中缓存的单号数(未向上游发起请求)
queriedNumber本次实际向上游查询的单号数
elapsedMsNumber本次查询耗时(毫秒)
cached + queried 等于你提交的单号总数(去重后)。

summary 状态统计

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

results[] 单条轨迹

字段类型说明
numberString单号
statusString状态代码,取值见下节
statusLabelString状态中文名,如「已签收」
statusDescString状态说明,可直接展示给终端用户
statusLabelEnString状态英文名,如 Delivered。英文界面用这个
statusDescEnString状态英文说明
channelString / null查询来源代号。该字段仅供你判断「数据是否可信」,建议不要展示给终端用户
latestInfoString最新一条轨迹描述
latestTimeString最新轨迹时间,YYYY-MM-DD HH:mm:ss
destinationString目的地,如「法国 74960」
carrierString末端承运商单号,无则为空字符串
noteString补充提示。非空时建议展示给用户,详见第五节
traceCountNumber轨迹条数
tracesArray轨迹明细,按时间倒序(第一条为最新)

traces[] 轨迹明细

字段类型说明
timeString时间,YYYY-MM-DD HH:mm:ss
infoString轨迹描述
轨迹条数说明:单次返回最多 100 条轨迹。traceCount 是实际轨迹总条数,可能大于 traces 数组长度。

四、状态字典

statusstatusLabelstatusLabelEn含义与建议动作
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": "错误代码"
}

错误码对照

HTTPcode含义处理建议
400—参数错误(单号为空/不合法,或超出单次上限)检查请求参数
401auth认证失败:Key 未携带、无效、已停用,或请求签名校验未通过依次核对:Key 是否正确携带、有无多余空格;签名三件套(timestamp/nonce/sign)是否齐全且在有效期内。仍无法解决请联系服务方
429quota当日调用额度已用尽见响应头 Retry-After,次日 0 点(东八区)自动恢复
429rate请求过于频繁按 Retry-After 退避后重试
502—上游查询异常稍后重试
404—接口路径错误检查请求地址
关于 auth 错误码:服务端刻意不区分「Key 缺失」「Key 无效」「Key 停用」「签名错误」—— 这几类失败返回完全相同的状态码、code 与文案,这是防撞库设计的一部分。 排查时请按上表建议逐项自检。
error 字段是面向用户的中文说明,可直接展示给终端用户。

重试建议


七、调用频率与配额

项目限制
单次最多单号数50 个(超出返回 400)
每 IP 请求频率30 次 / 分钟(超出返回 429)
每 Key 请求频率通常 60 次 / 分钟(超出返回 429;具体以服务方配置为准)
每日调用额度3000 次(超出返回 429,次日 0 点重置)
具体额度可按需调整,如需提高请联系服务方。

缓存机制(重要)

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

这意味着:

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

关于耗时

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

建议:


八、代码示例

以下示例统一使用 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));

九、接入检查清单

上线前请逐项确认:


十、常见问题

为什么有的单号返回「查不到」?
所有渠道均未收录该单号。常见原因是承运系统尚未录入(刚下单未揽收、或单号有误)。建议隔天重查;已签收的历史单号若查不到,请核对单号是否正确。
「待揽收」是异常吗?
不是。这表示承运系统还没收到扫描,通常是刚下单或刚揽收,属正常状态,隔天再查即可。
「运输异常」和「查询失败」有什么区别?
「运输异常」是货物有状况(清关或派送异常),数据可信,需联系承运方;「查询失败」是查询动作本身失败,数据不可信,稍后重试。请勿混淆。
为什么同一单号查两次,cached 数不一样?
服务端有缓存机制(已签收缓存 7 天,其余 30 分钟)。命中缓存时不会向上游发起请求,响应更快。属于正常现象。
支持哪些单号?运单号和转单号都可以吗?
都可以。单号会自动转为大写,不区分大小写。
channel 字段是什么?
查询来源代号,用于你判断数据可信度。建议不要展示给终端用户,也不要在界面上解释其含义。
轨迹条数被截断了?
单次最多返回 100 条轨迹。traceCount 为实际总条数,可能大于返回的数组长度。
接口能保证实时吗?
数据来自承运方系统同步,存在延迟。运输中的单号最多 30 分钟更新一次,不建议高频轮询。
我明确带了 Key,为什么调用被记为「匿名」、配额也不扣?
大概率你用了 X-API-Key 请求头——部署平台的网关会删除自定义请求头,Key 根本没到服务端。请改用 POST 请求体 key 字段(推荐)或 ?key= 参数。每个成功响应都带 auth 字段:"key" 表示已按你的 Key 计费,"anonymous" 表示 Key 没被识别。也可以用 GET /api/header-echo 检查你的请求头能否到达服务端(该端点只返回头名,不返回头值)。
API Key 泄露了怎么办?
立即联系服务方停用并重新生成。

十一、技术支持

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

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


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