快递查询V3-三方xc

接口说明

快递查询V3-三方xc用于根据快递单号查询物流轨迹与当前状态，覆盖全球 400+ 快递公司，适合需要在订单跟踪、售后跟进等场景中展示物流进度的业务使用。接口需携带调用密钥，按次计费。

调用地址

/apis/xckuaidi

本接口用于快递物流查询，支持覆盖全球 400+ 快递公司。

请求方式

支持 GET 与 POST 两种方式发起请求，均以普通表单或查询字符串形式提交参数，返回格式为 JSON。

该接口为收费接口，调用将按次计费，请在调用前确认账户余额充足。

鉴权说明

调用本接口必须携带密钥，密钥通过 Query 参数传递，参数名为 key：

/apis/xckuaidi?key=你的接口调用密钥

密钥为必填项，缺失或无效时请求将无法通过校验。请妥善保管密钥，避免在客户端或公开代码中泄露。

请求参数

调用地址：/apis/xckuaidi，请求方式：GET、POST。密钥通过 Query 传入，参数名为 key。

参数取值说明：

• id：需查询的快递运单号，支持覆盖全球 400+ 快递公司的单号。
• phone：运单对应的收件人手机号，用于需要手机号校验的快递公司；无需校验时可不传。
• mode：不传时按默认 json 返回；如需显式指定，填写 json 即可。

调用频率限制为每分钟约 60 次，超出可能被限流。本接口为收费接口，调用将按次计费。

成功响应示例

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "单号": "JDVD10390250857",
    "快递公司": "京东物流",
    "快递公司官网": "www.jdwl.com",
    "快递公司电话": "400-603-3600",
    "快递公司logo": "https://img3.fegine.com/express/jd.jpg",
    "物流状态": "已签收",
    "快递员电话": "17781030996",
    "派送耗时": "1天0小时28分",
    "更新时间": "2026-07-17 10:44:22",
    "最新状态": "您的快件已送达至【公司前台】，快递员：王俊然，联系电话：17781030996，营业部电话：18090178520，感谢您使用京东物流，期待再次为您服务。",
    "物流轨迹": [
      {
        "时间": "2026-07-17 10:44:22",
        "状态": "您的快件已送达至【公司前台】，快递员：王俊然，联系电话：17781030996，营业部电话：18090178520，感谢您使用京东物流，期待再次为您服务。"
      },
      {
        "时间": "2026-07-17 08:21:37",
        "状态": "您的快件正在派送中，请您准备签收（快递员：王俊然，联系电话：17781030996，营业部电话：18090178520）。"
      },
      {
        "时间": "2026-07-17 07:55:14",
        "状态": "您的快件已到达【泸州龙马潭城北站】，电话：18090178520"
      },
      {
        "时间": "2026-07-17 01:17:42",
        "状态": "您的快件已离开【泸州集散分拣中心】，正在发往下一站【泸州龙马潭城北站】的路上"
      },
      {
        "时间": "2026-07-16 11:56:11",
        "状态": "京东快递 已收取快件"
      }
    ]
  }
}

响应字段说明

说明：不同快递公司的返回字段内容存在差异，部分字段可能为空字符串；物流轨迹 条目数量取决于该单号的实际流转节点。

错误响应示例

当调用未通过校验或发生业务异常时，接口返回的 JSON 结构固定为 code、msg、errcode 三个字段。其中 code 为 0 表示本次请求未成功返回业务数据，msg 为可读的错误描述，errcode 为业务错误码。示例：

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

密钥错误时：

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

积分余额不足时：

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

请求过于频繁（超过每分钟约 60 次的限制）时：

{
  "code": 0,
  "msg": "请求过于频繁",
  "errcode": 11005
}

接口不存在时：

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

请以 errcode 作为判断依据，msg 仅作提示参考，不要依赖其文案做程序分支。

业务错误码说明

补充说明：

• 11001、11002、11003、11023 属于密钥本身的问题，需检查密钥是否已传入、是否拼写正确、是否仍处于可用与有效期内。
• 11004、11024 属于积分问题，前者为当前密钥可用积分不足，后者为令牌分配到的积分不足。
• 11005 为频率限制，本接口限制为每分钟约 60 次，请降低调用频率后重试。
• 11006、11007、11008、11017 属于接口状态类问题，分别为维护中、已禁用、不可用、服务暂不可用，建议稍后重试。
• 11009、11010 为校验与积分系统临时不可用，通常为短时故障，可稍后重试。
• 11011 表示该接口为收费接口，必须携带有效密钥才能调用。
• 11012 表示鉴权方式不正确，本接口应通过 Query 传入密钥。
• 11013 表示所请求的接口路径不存在，请核对调用地址是否为本接口。
• 11014、11015、11016 为地址相关的错误，分别表示地址无效、地址不被允许、请求失败；代理类接口同样可能出现上述 11014～11016 以及 11017。
• 11018 表示请求方式不被允许，本接口仅支持 GET 与 POST。
• 11019 表示当前请求来源 IP 不在白名单内，需在密钥配置中补充该 IP 或联系管理员处理。
• 11020、11021、11022 为出口代理相关错误，分别表示启用出口代理时未提供有效密钥、未配置可用出口代理、出口代理不可用。

调用示例

终端 curl（bash）

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

curl -G "https://api.example.com/apis/xckuaidi" \
  --data-urlencode "key=你的接口调用密钥" \
  --data-urlencode "id=JDVD10390250857"

需要补充收件手机号时，增加 phone 参数（部分快递公司需校验手机号后四位才能返回完整轨迹）：

curl -G "https://api.example.com/apis/xckuaidi" \
  --data-urlencode "key=你的接口调用密钥" \
  --data-urlencode "id=JDVD10390250857" \
  --data-urlencode "phone=13800000000"

POST 方式调用，参数同样以表单形式提交：

curl -X POST "https://api.example.com/apis/xckuaidi" \
  -d "key=你的接口调用密钥" \
  -d "id=JDVD10390250857" \
  -d "mode=json"

PHP

// 语言：PHP，GET 方式调用快递查询接口
$baseUrl = 'https://api.example.com/apis/xckuaidi';

$params = [
    'key'   => '你的接口调用密钥',
    'id'    => 'JDVD10390250857',
    'phone' => '13800000000',
    'mode'  => 'json',
];

$url = $baseUrl . '?' . http_build_query($params);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);

$response = curl_exec($ch);
$errno    = curl_errno($ch);
curl_close($ch);

if ($errno) {
    exit('请求失败，错误码：' . $errno);
}

$result = json_decode($response, true);

if (isset($result['code']) && $result['code'] == 200) {
    $data = $result['data'];
    echo '单号：' . $data['单号'] . PHP_EOL;
    echo '快递公司：' . $data['快递公司'] . PHP_EOL;
    echo '物流状态：' . $data['物流状态'] . PHP_EOL;
    echo '最新状态：' . $data['最新状态'] . PHP_EOL;

    foreach ($data['物流轨迹'] as $node) {
        echo $node['时间'] . ' ' . $node['状态'] . PHP_EOL;
    }
} else {
    echo '查询失败：' . ($result['msg'] ?? '未知原因');
}

注意事项

• 密钥仅可通过 Query 传递：调用时请将密钥以 key=… 的形式拼接在 URL 查询参数中，例如 /apis/xckuaidi?key=你的密钥&id=快递单号。除该方式外，本接口不接受其它形式的密钥传递，请勿自行改造。
• 密钥务必妥善保管：密钥与你的账户计费直接绑定，一旦泄露可能被他人盗用并产生费用。请勿写入前端页面、小程序包、公开仓库或客户端可见的代码中，建议仅在服务端保存与调用。
• 本接口为收费接口：每次成功调用都会计费，请在开发调试阶段注意控制调用次数，避免使用循环对同一单号高频重试。
• 频率限制：默认限制为每分钟约 60 次。超出后请求会被限流，请做好失败重试与退避处理，切勿并发压测。若业务量较大，请提前评估并申请调整。
• 建议使用 HTTPS：通过 HTTP 明文传输时，URL 中的密钥可能被中间环节记录，请始终使用 HTTPS 调用。
• id 为必填项：快递单号请原样传入，不要添加空格、换行或多余的 #、字母大小写混用等修饰；单号错误会直接导致查询失败。
• phone 按需传入：部分快递公司（如顺丰、京东等）对收件人手机号有校验要求，若返回查不到结果或需要验证，请补充该参数；不需要校验的快递公司可不传。
• mode 目前默认返回 JSON：如无特殊需求，保持默认即可，不建议传入其它值。
• 返回结果解读：请以 code 判断请求是否成功，code 为 200 时再从 data 中取「物流状态」「最新状态」「物流轨迹」等字段。物流轨迹 为数组，按时间倒序排列（最新在上方），请勿假设其长度固定。
• 字段可能缺失：快递员电话、派送耗时、快递公司电话、快递公司logo 等字段取决于快递公司的回传数据，可能为空或不返回，业务代码需做空值兼容。
• 时间字段为字符串：更新时间 及轨迹中的 时间 均为 YYYY-MM-DD HH:mm:ss 格式的文本，请按字符串处理或自行解析，不要当作时间戳。
• 无轨迹不等于单号无效：刚揽收或快递公司数据尚未同步时，可能只返回单号与快递公司而无轨迹，建议间隔一段时间后重试，而非立即判定失败。
• 错误重试：遇到限流或临时异常时，请使用指数退避重试（如 1s、2s、4s），避免密集请求造成额外计费与限流叠加。
• 合规使用：查询他人快递信息需确保已获得相应授权，请勿将本接口用于批量爬取或数据倒卖等违规用途。