快递查询V2

接口说明

本接口提供国内外 27000+ 物流公司的快递轨迹查询服务，覆盖顺丰、京东、圆通、中通、申通、韵达、极兔等主流快递公司。开发者传入运单号后即可获取完整物流轨迹，也可指定快递公司简称以提升识别效率；针对顺丰、京东、中通等隐私包裹，可附带收件人手机尾号完成查询。

调用地址

https://api.xunjinlu.fun/api/kuaidi/v2

请求方式

GET、POST

鉴权说明

本接口必须携带密钥调用。请在调用时通过 Query 参数 key 传入您的接口密钥，例如：?key=您的密钥。未提供有效密钥时将无法正常请求。

请求参数

密钥参数 key 通过 Query 方式传递。

成功响应示例

{
    "code": 12001,
    "status": "success",
    "message": "查询成功",
    "data": {
        "number": "YT1234567890123",
        "carrier_code": "YTO",
        "carrier_name": "中国圆通速递",
        "country": "中国",
        "delivery_status": {
            "code": "in_transit",
            "text": "运输中"
        },
        "signed": false,
        "last_event": {
            "time": "2026-07-18T14:32:10+08:00",
            "description": "【北京市】您的快件已到达【北京通州转运中心】，正在分拣中"
        },
        "events": [
            {
                "time": "2026-07-18T14:32:10+08:00",
                "description": "【北京市】您的快件已到达【北京通州转运中心】，正在分拣中"
            },
            {
                "time": "2026-07-18T08:05:47+08:00",
                "description": "【天津市】您的快件已从【天津西青转运中心】发出，下一站【北京通州转运中心】"
            },
            {
                "time": "2026-07-17T21:18:33+08:00",
                "description": "【天津市】您的快件已到达【天津西青转运中心】"
            },
            {
                "time": "2026-07-17T15:40:02+08:00",
                "description": "【上海市】您的快件已揽收，揽收网点：【上海青浦营业点】"
            }
        ]
    }
}

国内常见快递简称对照（8 家）

响应字段说明

错误响应示例

请求失败时，接口返回统一的错误响应 JSON 结构，code 固定为 0，errcode 标识具体错误类型，msg 为可读错误描述。示例：

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

业务错误码说明

调用示例

终端 curl（bash）

curl "https://api.xunjinlu.fun/api/kuaidi/v2?key=你的密钥&num=YT070011163&carrier=YTO&phone=5711"

PHP

// PHP 示例
$url = 'https://api.xunjinlu.fun/api/kuaidi/v2?key=你的密钥&num=YT070011163&carrier=YTO&phone=5711';

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

注意事项

• 请将 key 作为 Query 参数传递，例如 https://api.xunjinlu.fun/api/kuaidi/v2?key=你的密钥&num=YT070011163。密钥务必妥善保管，严禁暴露在前端页面、App 客户端或任何公开代码仓库中，以免被盗用。
• 本接口仅支持 HTTPS 调用，请勿使用明文 HTTP 请求。
• 接口免费使用，但存在频率限制：每分钟约 60 次。批量查询时请适当增加间隔，避免触发限流导致请求失败。
• num 为必填参数，最长 100 个字符。请确保单号准确，避免因误填其他字符串导致查询失败或结果异常。
• carrier 为可选参数，但建议在已知快递公司时尽量传入，以减少自动识别可能带来的延迟或误判；若不确定可先调用快递公司简称查询接口获取对应短码。
• 顺丰、京东、中通等隐私单通常需要提供收件人手机号后 4 位（phone 参数），否则可能返回需要手机尾号的错误。请确保所填尾号与收件人预留号码一致。
• 返回结果中可通过 delivery_status.code 判断当前物流状态，signed 字段表示是否已签收；若需展示轨迹，请以 events 数组中的 time 和 description 为准，注意时间为带时区的 ISO 8601 格式。
• 本接口覆盖国内外 27000+ 快递公司，部分公司轨迹可能不全，请以实际返回为准；已知已实测的快递公司包括邮政、圆通、中通、申通、韵达国际、极兔、顺丰、京东，其余需自测确认兼容性。