接口信息

GET / POST api.xunjinlu.fun/apis/wxkuaidi

Method

GET / POST

分类

快递查询

Calls

310

KEY

KEY 必填

计费

4 积分 / 次

QPM

60/MIN

鉴权方式

Query 参数、Header(X-API-Key)、Bearer Token

作者

尋鯨錄

当前接口维护中，暂时无法调用。

请求参数

参数名	类型	必填	说明	示例
key	string	是	接口调用密钥
action	string	是	操作方法	query
num	string	是	单号	9831719725623

[
    {
        "name": "key",
        "type": "string",
        "required": true,
        "description": "接口调用密钥",
        "example": ""
    },
    {
        "name": "action",
        "type": "string",
        "required": true,
        "description": "操作方法",
        "example": "query"
    },
    {
        "name": "num",
        "type": "string",
        "required": true,
        "description": "单号",
        "example": "9831719725623"
    }
]

{"openapi":"3.1.1","info":{"title":"WX快递查询v4","description":"一站式查快递、寄快递信息服务平台。 支持全球3000+快递公司单号查询","version":"1.0.0"},"paths":{"/apis/wxkuaidi":{"get":{"summary":"WX快递查询v4","description":"一站式查快递、寄快递信息服务平台。 支持全球3000+快递公司单号查询","parameters":[{"name":"key","in":"query","required":true,"schema":{"type":"string"},"description":"接口调用密钥"},{"name":"action","in":"query","required":true,"schema":{"type":"string","example":"query"},"description":"操作方法"},{"name":"num","in":"query","required":true,"schema":{"type":"string","example":"9831719725623"},"description":"单号"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"summary":"WX快递查询v4","description":"一站式查快递、寄快递信息服务平台。 支持全球3000+快递公司单号查询","parameters":[{"name":"key","in":"query","required":true,"schema":{"type":"string"},"description":"接口调用密钥"},{"name":"action","in":"query","required":true,"schema":{"type":"string","example":"query"},"description":"操作方法"},{"name":"num","in":"query","required":true,"schema":{"type":"string","example":"9831719725623"},"description":"单号"}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"servers":[{"url":"https://api.xunjinlu.fun","description":"当前访问入口（https）"}]}

返回示例

{
  "code": 1,
  "message": "success",
  "data": {
    "hit": 1,
    "status": "200",
    "lastResult": {
      "message": "ok",
      "nu": "9831719725623",
      "routeInfo": {
        "to": {
          "name": "广东,深圳市",
          "number": "CN440300000000"
        },
        "cur": {
          "name": "广东,深圳市",
          "number": "CN440300000000"
        },
        "from": {
          "name": "浙江,金华市",
          "number": "CN330700000000"
        }
      },
      "num": "youzhengguonei",
      "ischeck": "1",
      "com": "youzhengguonei",
      "status": "200",
      "condition": "H100",
      "subStatus": "303",
      "data": [
        {
          "statusCode": "3",
          "time": "2026-05-08 12:02:17",
          "areaName": "广东,深圳市",
          "areaCode": "CN440300000000",
          "status": "签收",
          "location": "广东省,深圳市",
          "areaCenter": "114.057868,22.543099",
          "context": "您的快件已代收【物业代收，家门口】，如有疑问请电联快递员【钟欢，电话:13823191550】，投诉电话【电话:13728675481】。有事呼叫我，少一次投诉，多一份感恩。中国邮政将全心呵护您的所托，服务热线11183。",
          "ftime": "2026-05-08 12:02:17",
          "areaPinYin": "shen zhen shi"
        },
        {
          "statusCode": "5",
          "time": "2026-05-08 08:19:40",
          "areaName": "广东,深圳市",
          "areaCode": "CN440300000000",
          "status": "派件",
          "location": "广东省,深圳市",
          "areaCenter": "114.057868,22.543099",
          "context": "快件正在派送中，请耐心等待，保持电话畅通，准备签收，如有疑问请电联快递员【钟欢，电话:13823191550】或揽投部【电话:0755-84208081】，服务热线11183。",
          "ftime": "2026-05-08 08:19:40",
          "areaPinYin": "shen zhen shi"
        },
        {
          "statusCode": "0",
          "time": "2026-05-08 08:00:10",
          "areaName": "广东,深圳市,坪山区",
          "areaCode": "CN440310000000",
          "status": "在途",
          "location": "广东省,深圳市",
          "areaCenter": "114.361828,22.688309",
          "context": "快件到达【深圳市坪山葵涌揽投部】",
          "ftime": "2026-05-08 08:00:10",
          "areaPinYin": "ping shan qu"
        },
        {
          "statusCode": "0",
          "time": "2026-05-08 04:10:18",
          "areaName": null,
          "areaCode": null,
          "status": "",
          "location": "广东省,深圳市",
          "areaCenter": null,
          "context": "快件离开【深圳邮区中心快件处理中心】，正在发往下一站",
          "ftime": "2026-05-08 04:10:18",
          "areaPinYin": null
        },
        {
          "statusCode": "0",
          "time": "2026-05-08 00:14:34",
          "areaName": null,
          "areaCode": null,
          "status": "",
          "location": "广东省,深圳市",
          "areaCenter": null,
          "context": "快件到达【深圳邮区中心快件处理中心】",
          "ftime": "2026-05-08 00:14:34",
          "areaPinYin": null
        },
        {
          "statusCode": "0",
          "time": "2026-05-07 05:33:06",
          "areaName": "浙江,金华市",
          "areaCode": "CN330700000000",
          "status": "",
          "location": "浙江省,金华市",
          "areaCenter": "119.647444,29.079059",
          "context": "预计【5月8日】到达【深圳市】，两地距离1201km，将在【5月8日上午】更新快件状态，请您放心。",
          "ftime": "2026-05-07 05:33:06",
          "areaPinYin": "jin hua shi"
        },
        {
          "statusCode": "0",
          "time": "2026-05-07 03:23:22",
          "areaName": "浙江,金华市",
          "areaCode": "CN330700000000",
          "status": "",
          "location": "浙江省,金华市",
          "areaCenter": "119.647444,29.079059",
          "context": "快件离开【金华市华东包件车间】，正在发往下一站",
          "ftime": "2026-05-07 03:23:22",
          "areaPinYin": "jin hua shi"
        },
        {
          "statusCode": "0",
          "time": "2026-05-07 03:17:19",
          "areaName": "浙江,金华市",
          "areaCode": "CN330700000000",
          "status": "",
          "location": "浙江省,金华市",
          "areaCenter": "119.647444,29.079059",
          "context": "快件到达【金华市华东包件车间】",
          "ftime": "2026-05-07 03:17:19",
          "areaPinYin": "jin hua shi"
        },
        {
          "statusCode": "0",
          "time": "2026-05-07 01:47:16",
          "areaName": "浙江,金华市,义乌市",
          "areaCode": "CN330782000000",
          "status": "",
          "location": "浙江省,金华市",
          "areaCenter": "120.075058,29.306841",
          "context": "快件离开【义乌市城东集包集散点】，正在发往下一站",
          "ftime": "2026-05-07 01:47:16",
          "areaPinYin": "yi wu shi"
        },
        {
          "statusCode": "0",
          "time": "2026-05-07 01:09:10",
          "areaName": "浙江,金华市,义乌市",
          "areaCode": "CN330782000000",
          "status": "",
          "location": "浙江省,金华市",
          "areaCenter": "120.075058,29.306841",
          "context": "快件到达【义乌市城东集包集散点】",
          "ftime": "2026-05-07 01:09:10",
          "areaPinYin": "yi wu shi"
        },
        {
          "statusCode": "0",
          "time": "2026-05-07 01:09:08",
          "areaName": "浙江,金华市,义乌市",
          "areaCode": "CN330782000000",
          "status": "",
          "location": "浙江省,金华市",
          "areaCenter": "120.075058,29.306841",
          "context": "快件离开【义乌市城东片区揽收部】，正在发往【义乌市城东集包集散点】",
          "ftime": "2026-05-07 01:09:08",
          "areaPinYin": "yi wu shi"
        },
        {
          "statusCode": "1",
          "time": "2026-05-06 14:57:56",
          "areaName": "浙江,金华市",
          "areaCode": "CN330700000000",
          "status": "揽收",
          "location": "浙江省,金华市",
          "areaCenter": "119.647444,29.079059",
          "context": "揽收员来航(18857916066)已取件(物流问题可先联系专属服务热线11183，快速响应、一站式解决)",
          "ftime": "2026-05-06 14:57:56",
          "areaPinYin": "jin hua shi"
        }
      ],
      "state": "3",
      "isLoop": false
    },
    "courierMobile": "13823191550",
    "company": {
      "code": "youzhengguonei",
      "name": "邮政快递包裹"
    }
  }
}

接口反馈

快递查询v4

接口说明

快递查询v4 提供全球 3000+ 快递公司的运单轨迹查询服务，输入快递单号即可获取签收、派件、在途等物流节点信息。适用于电商平台、订单系统、客服工具等需要向用户展示包裹最新物流进度的业务场景。调用需使用有效密钥，按次计费。

调用地址

/apis/wxkuaidi

完整请求地址为本站域名拼接该路径，例如 https:///apis/wxkuaidi。请以本站实际提供的域名为准，路径部分保持不变。

请求方式

支持 GET 与 POST 两种方式。参数可使用查询字符串传递，也可在 POST 请求中以表单形式提交；两种方式下的参数名称与含义完全一致。

本接口覆盖全球 3000+ 快递公司的单号查询，调用时通过 action 指定操作方法，通过 num 指定待查询单号。

鉴权说明

本接口必须携带密钥，采用 Query 方式传递：在请求地址的查询字符串中加入 key 参数，其值为你的接口调用密钥。

例如：

/apis/wxkuaidi?key=你的密钥&action=query&num=9831719725623

key 为必填项，缺失或无效将无法获得查询结果。请在每次调用时通过上述方式附带密钥，并妥善保管，避免在客户端代码或公开页面中泄露。

本接口为收费接口，调用会计入计费；频率限制约为每分钟 60 次，请合理安排请求节奏。

请求参数

调用地址：/apis/wxkuaidi，请求方式：GET、POST。密钥通过 Query 传递，即 key=…。

参数名	类型	必填	说明
key	string	是	接口调用密钥，通过 Query 传入
action	string	是	操作方法，查询固定传 `query`
num	string	是	快递单号，如 `9831719725623`

参数取值说明：

action：当前仅用于快递单号查询，传 query 即返回该单号的物流轨迹与承运公司信息。
num：需填写完整的快递单号字符串，不区分大小写，请勿包含空格或其它符号。支持全球 3000+ 快递公司的单号。

请求频率限制：每分钟约 60 次。

成功响应示例

{
  "code": 1,
  "message": "success",
  "data": {
    "hit": 1,
    "status": "200",
    "lastResult": {
      "message": "ok",
      "nu": "9831719725623",
      "num": "youzhengguonei",
      "com": "youzhengguonei",
      "ischeck": "1",
      "status": "200",
      "condition": "H100",
      "subStatus": "303",
      "state": "3",
      "isLoop": false,
      "routeInfo": {
        "from": { "name": "浙江,金华市", "number": "CN330700000000" },
        "cur": { "name": "广东,深圳市", "number": "CN440300000000" },
        "to": { "name": "广东,深圳市", "number": "CN440300000000" }
      },
      "data": [
        {
          "statusCode": "3",
          "time": "2026-05-08 12:02:17",
          "ftime": "2026-05-08 12:02:17",
          "status": "签收",
          "context":

## 错误响应示例

接口在参数缺失、密钥无效、余额不足或频次超限等情况下，均以 JSON 结构返回错误信息，HTTP 状态码保持正常响应通道，业务结果由 `code` 与 `errcode` 表达。

鉴权失败（未提供调用密钥）：

```json
{"code":0,"msg":"未提供调用密钥","errcode":11001}

鉴权失败（密钥错误）：

{"code":0,"msg":"密钥错误","errcode":11002}

余额不足：

{"code":0,"msg":"积分余额不足","errcode":11004}

请求频率超限：

{"code":0,"msg":"请求过于频繁，请稍后重试","errcode":11005}

接口维护中：

{"code":0,"msg":"接口维护中","errcode":11006}

接口不存在：

{"code":0,"msg":"接口不存在","errcode":11013}

请求方式不允许：

{"code":0,"msg":"请求方式不允许","errcode":11018}

当前 IP 不在白名单内：

{"code":0,"msg":"当前IP不在白名单内","errcode":11019}

上述示例中 code 为 0 表示本次调用未成功，msg 为可读的提示文本，errcode 为业务错误码，调用方应以 errcode 作为判断与重试依据，msg 仅用于展示与日志记录。

业务错误码说明

下表列出本接口可能返回的全部业务错误码及其含义。

errcode	含义	说明
11001	未提供调用密钥	请求中未携带 `key` 参数，无法通过鉴权。
11002	密钥错误	`key` 值无效，与本站签发的调用密钥不匹配。
11003	密钥已禁用	该密钥已被停用，无法继续调用。
11004	积分余额不足	本接口为收费接口，账户剩余积分不足以支付本次调用。
11005	请求过于频繁（QPM 限制）	超出频率上限，本接口每分钟约 60 次，请降低调用速度后重试。
11006	接口维护中	接口处于维护状态，暂时无法提供服务。
11007	接口已禁用	接口已被关闭，不再对外提供调用。
11008	接口不可用	接口当前状态异常，无法正常处理请求。
11009	密钥校验暂不可用	鉴权校验环节暂时不可用，请稍后重试。
11010	积分系统暂不可用	计费与积分扣减环节暂时不可用，请稍后重试。
11011	收费接口须提供有效密钥	本接口为收费接口，必须携带有效密钥方可调用。
11012	鉴权方式错误	密钥的传递方式不符合要求，本接口须使用 Query 方式传递 `key`。
11013	接口不存在	请求的接口路径不存在或已调整。
11014	***地址无效	查询目标地址格式无效，无法完成处理。
11015	***地址不允许	查询目标地址不在允许范围内。
11016	***请求失败	本次查询请求未能成功完成，可稍后重试。
11017	服务暂不可用	服务整体暂时不可用，请稍后重试。
11018	请求方式不允许	使用了不受支持的请求方式，本接口支持 GET、POST。
11019	当前IP不在白名单内	调用来源 IP 未在白名单中，无法访问。
11020	启用出口代理须提供有效密钥	启用出口代理能力时，必须携带有效密钥。
11021	未配置可用出口代理	未配置可用的出口代理资源，无法完成请求。
11022	出口代理不可用	出口代理当前不可用，请稍后重试。
11023	密钥已过期	该密钥已超出有效期，请更换有效密钥。
11024	令牌分配积分不足	令牌可用积分额度不足，无法支付本次调用。

补充说明：

业务错误码均在 code 为 0 的响应中返回，与成功响应（code 为 1）区分。
11001、11002、11003、11012、11023 属于密钥与鉴权类错误，需修正密钥或鉴权参数后重试。
11004、11010、11024 属于积分与计费类错误，需补充积分或额度后重试。
11005 属于频次类错误，建议按每分钟约 60 次的节奏调用，并在出现该码时退避重试。
11006、11007、11008、11009、11017 属于服务状态类错误，通常为暂时性，可稍后重试。
11013、11018 属于请求本身不符合接口约定，需核对调用地址与请求方式。
11014、11015、11016 会在查询链路处理失败时返回，可结合 msg 排查后重试。
11019、11020、11021、11022 与访问来源及出口相关，需确认来源与出口配置的可用性。

调用示例

终端 curl（bash）

GET 方式，密钥以 Query 参数 key 传递：

curl -G "https://你的调用域名/apis/wxkuaidi" \
  --data-urlencode "key=你的密钥" \
  --data-urlencode "action=query" \
  --data-urlencode "num=9831719725623"

POST 方式同样将参数放在表单中提交：

curl -X POST "https://你的调用域名/apis/wxkuaidi" \
  -d "key=你的密钥" \
  -d "action=query" \
  -d "num=9831719725623"

PHP

// PHP 示例：以表单方式提交快递单号查询请求
$url = "https://你的调用域名/apis/wxkuaidi";

$params = array(
    "key"    => "你的密钥",
    "action" => "query",
    "num"    => "9831719725623"
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);

$response = curl_exec($ch);
if ($response === false) {
    echo "请求失败：" . curl_error($ch);
} else {
    $result = json_decode($response, true);
    echo $response;
}

curl_close($ch);

注意事项

密钥仅通过 Query 传递：调用时请将密钥作为 key 参数拼接到请求地址中，例如 /apis/wxkuaidi?key=您的密钥&action=query&num=单号。请勿将密钥写入前端页面、客户端代码、公开仓库或日志中，避免被他人抓取后造成额度消耗。建议在服务端调用，并对密钥做定期轮换。
必须使用 HTTPS：密钥以明文形式出现在 URL 中，若使用 HTTP 明文传输极易在链路中被截获。请始终通过 HTTPS 访问接口，并避免在浏览器地址栏、分享链接、*** 中暴露带 key 的完整 URL。
频率限制：本接口限制约每分钟 60 次。同一单号短时间内的重复查询不会带来更多有效信息，建议对查询结果做本地缓存（如缓存数分钟至数十分钟），并在业务高峰期对请求做排队或退避重试，避免触发限流导致失败。
action 取值要求：action 为必填项，查询物流轨迹时固定传 query，不要传入空值或其他自造值，否则接口无法返回预期结果。
num 为快递单号，注意格式：单号需去除前后空格，区分大小写，不要包含中文、连字符或说明文字。若单号填写错误，通常表现为查询不到轨迹而非报错，请在业务侧对结果为空的情况给出明确提示。
data.lastResult.data 为轨迹数组，需按时间倒序/正序自行处理：数组中各条记录的 areaName、areaCode、areaPinYin、areaCenter 等字段可能为 null，时间字段为字符串格式，业务展示前请做好空值判断与格式化，不要直接假定字段非空。
区分接口状态与轨迹状态：响应中的 code、data.status 表示本次请求的处理结果，而 data.lastResult.ischeck、state、以及轨迹条目中的 statusCode、status、subStatus 表示包裹本身的物流状态，二者含义不同，请勿混用判断逻辑。ischeck 为 1 一般表示已签收，但具体业务判断建议结合 status 文本与最新一条轨迹综合判断。
本接口为收费接口：每次成功调用都会产生计费，请勿在测试、压测或轮询场景中无意义地反复调用；正式上线前先确认账户余额与套餐余量，避免因欠费导致服务中断。
查询失败的处理：若返回的 code、data.hit 或 lastResult.message 表明未命中或异常，请先核对单号与 action 参数，确认无误后再做重试。重试建议采用指数退避，避免连续高频请求。
结果仅供参考：物流轨迹由各快递公司提供，存在更新延迟，签收时间、派件员电话等信息请以快递公司官方渠道为准；涉及用户手机号、地址等敏感信息的轨迹内容，请在展示与存储时遵守相关隐私合规要求。
返回数据较大时注意解析：完整的物流轨迹可能包含数十条记录，建议只解析业务需要的字段，避免将整个响应体长期缓存或写入日志。

快速上手

curl -G 'https://api.xunjinlu.fun/apis/wxkuaidi' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'action=query' \
  --data-urlencode 'num=9831719725623'

# 成功返回 code=1 且 message=success，失败时 code 不等于 1
# 频率限制约 60 次/分钟

免责声明

使用本平台接口即表示同意本声明。

数据来源：接口数据来自第三方公开网络或用户上传，本平台不保证准确性、完整性、实时性，请以官方信息为准。
合法性与安全性：本平台无法核实每个接口的安全性、合法性，使用者自行承担相关风险。
用途限制：所有的接口禁止商用；严禁用于违法违规行为（如诈骗、赌博、侵权等）。违规后果由使用者自行承担。
损害免责：使用本接口产生的任何直接或间接损失，本平台不承担责任。
第三方上传：用户/商户上传的接口若侵权或违法，由上传者承担全部责任。
监督配合：本平台依法记录访问日志，如发现违法活动将配合执法部门处理，并有权随时限制或封禁服务。
注:本平台保留最终解释权，并可能随时更新本声明。

在线测试

维护中，暂不可测试。

接口信息

接口反馈

快递查询v4

接口说明

调用地址

请求方式

鉴权说明

请求参数

成功响应示例

业务错误码说明

调用示例

终端 curl（bash）

PHP

注意事项

快速上手

免责声明

在线测试

推荐接口

天气查询API V3(正在优化街道级天气)