物流轨迹查询 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 无法到达服务端、按匿名访问计费。
curl -s -X POST "https://track.monina.xyz/api/track" \
-H "Content-Type: application/json" \
-d '{"key":"tk_你的Key","numbers":["QYAL260907001"]}'第 3 步:解析返回的 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 请求示例
curl "https://track.monina.xyz/api/track?numbers=QYAL260907001,QLAG260908002&key=tk_你的Key"POST 请求示例(推荐用于生产)
单号较多、含特殊字符或需要传递 Key 时,都用 POST + JSON:既避开 URL 长度限制与转义问题, Key 也不会出现在网址里。
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):
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 }完整示例:
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是查询动作失败,数据不可信。 这个区分对业务判断很关键,请按上表处理,不要统一当成「异常」。
若需程序化获取状态字典(避免在代码里硬编码中文),可调用:
curl "https://track.monina.xyz/api/status-meta"五、note 字段的特殊说明
在部分情况下,note 会有内容,需要你关注:
note 内容 | 含义 | 建议 |
|---|---|---|
本次查询未命中,显示上次结果(2026-09-18 13:00:34) | 本次未查到,但返回了历史有效轨迹 | 正常展示轨迹,并可提示「数据可能不是最新」 |
承运方提示清关异常 | 清关环节有状况 | 提示用户联系承运方 |
承运方提示派送异常 | 派送环节有状况 | 提示用户联系承运方 |
六、错误处理
出错时返回 HTTP 状态码 + 以下结构:
{
"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 分钟。
这意味着:
- 短时间内重复查询同一单号,返回的是缓存结果,
cached计数会增加,elapsedMs会显著变小; - 运输中的单号最多 30 分钟更新一次,无需高频轮询;
- 你无需自己再做一层缓存,直接透传即可。
关于耗时
单次查询会依次尝试多个渠道,命中后即停止。正常情况下:
- 缓存命中:几十毫秒内返回;
- 缓存未命中(需向上游查询):约 2~8 秒,取决于单号数量。
建议:
- 查询量较大时分批提交(每批 20~50 个单号),避免单次请求超时;
- 前端展示加载状态,不要让用户干等。
八、代码示例
以下示例统一使用 POST + JSON 请求体传 Key(key 字段),生产环境推荐写法。
cURL
curl -s -X POST "https://track.monina.xyz/api/track" \
-H "Content-Type: application/json" \
-d '{"key":"tk_你的Key","numbers":["QYAL260907001"]}'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
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)
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。
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
- 查询进度有加载提示,未让用户干等
十、常见问题
cached 数不一样?channel 字段是什么?traceCount 为实际总条数,可能大于返回的数组长度。X-API-Key 请求头——部署平台的网关会删除自定义请求头,Key 根本没到服务端。请改用 POST 请求体 key 字段(推荐)或 ?key= 参数。每个成功响应都带 auth 字段:"key" 表示已按你的 Key 计费,"anonymous" 表示 Key 没被识别。也可以用 GET /api/header-echo 检查你的请求头能否到达服务端(该端点只返回头名,不返回头值)。十一、技术支持
| 项目 | 内容 |
|---|---|
| 接口地址 | https://track.monina.xyz |
| 健康检查 | GET /api/health |
| 状态字典 | GET /api/status-meta |
| 请求头诊断 | GET /api/header-echo(查看哪些请求头能到达服务端) |
技术支持与额度调整,请联系你的服务对接人。
*文档版本:v1.0 更新日期:2026-10-16*