WooCommerce快递查询接口？

学完这一篇，你能在自己的 WooCommerce 店里给客户显示物流轨迹，并且清楚该接哪个接口、密钥去哪拿、代码挂在哪。

第一步：先分清你要的是哪种「接口」

很多人问「WooCommerce 快递查询接口」，其实混着三件事：一是把快递单号录进订单（这是插件干的活），二是调第三方 API 拿到物流轨迹（这是快递100、快递鸟这类服务干的活），三是把轨迹显示给客户。这三件事是三套东西，先想清楚缺哪一块，不然会白折腾。

第二步：装 WooCommerce Shipment Tracking 插件

这一步做完，订单编辑页会多出一个填单号的入口。后台点「插件 → 安装插件」，右上角搜索框输入 Shipment Tracking，找到作者是 WooCommerce 的那个（当前版本 1.9.5），点「立即安装」，装好后点「启用」。打开任意一个订单的编辑页，右侧栏会出现 Shipment Tracking 面板，里面有 Date shipped、Tracking provider（下拉选快递公司）、Tracking number 三个字段。

注意：如果你的店开了 HPOS（高性能订单存储），插件版本必须 ≥ 1.9.0，更低版本在「WooCommerce → 设置 → 高级 → 功能」里把 HPOS 关掉才能正常显示。

第三步：去快递100申请 key

这一步做完你手里会有三样东西：customer、key、以及一个能返回 JSON 的地址。打开 https://www.kuaidi100.com/openapi/，用企业身份注册并申请「实时快递查询」接口（免费版每日有查询次数上限，商用要买套餐）。申请通过后在控制台拿到 customer（授权码）和 key（密钥）。

查询地址是 https://poll.kuaidi100.com/poll/query.do，POST 提交三个参数：customer、sign、param。其中 sign = MD5(param + key + customer)，取 32 位大写。param 是 JSON，形如 {"com":"yuantong","num":"YT1234567890"}。常见 com 代码：圆通 yuantong、中通 zhongtong、韵达 yunda、顺丰 shunfeng。

注意：老的 https://api.kuaidi100.com 接口已停用，网上抄到的旧代码会直接报错。另外顺丰、京东、EMS 属于「需单独申请」的快递公司，没开通就查不到，返回的是空轨迹而不是报错。

第四步：把查询结果挂到订单页

这一步做完，客户在「我的账户 → 订单」页面就能看到自己的包裹走到哪了。把下面这段放进主题的 functions.php（建议用子主题）：

add_action( 'woocommerce_order_details_after_order_table', function ( $order ) {
    $items = function_exists( 'wc_get_shipment_tracking_items' )
        ? wc_get_shipment_tracking_items( $order->get_id() ) : array();
    if ( ! $items ) return;

    $num = $items[0]['tracking_number'];
    $com = $items[0]['tracking_provider'];
    $cache = get_transient( 'kd_' . $num );
    if ( false === $cache ) {
        $key = '你的key'; $customer = '你的customer';
        $param = json_encode( compact( 'com', 'num' ) );
        $res = wp_remote_post( 'https://poll.kuaidi100.com/poll/query.do', array(
            'timeout' => 10,
            'body'    => array(
                'customer' => $customer,
                'sign'     => strtoupper( md5( $param . $key . $customer ) ),
                'param'    => $param,
            ),
        ) );
        $cache = json_decode( wp_remote_retrieve_body( $res ), true );
        set_transient( 'kd_' . $num, $cache, 1800 ); // 缓存 30 分钟
    }
    if ( empty( $cache['data'] ) ) return;
    echo '<h3>物流轨迹</h3><ul>';
    foreach ( $cache['data'] as $row ) {
        echo '<li>' . esc_html( $row['ftime'] . ' ' . $row['context'] ) . '</li>';
    }
    echo '</ul>';
} );

注意：set_transient 那行千万别删。快递100 按次计费，用户每刷新一次页面就查一次，额度半天就烧光。返回里的 state 字段表示状态：0 在途、3 签收、5 派件、6 退回。

第五步：自测和排错

先用一个真实单号在订单里填一遍，然后退出登录，用客户账号打开该订单页，看轨迹是否出现。常见报错：返回 {"result":false,"returnCode":"408"} 是查询频率超限；returnCode":"400" 是 sign 算错，重点检查拼接顺序是不是 param+key+customer，别调换；返回空数组而单号明明有效，基本是快递公司代码填错或该公司需要单独开通。

小结

• 三件事分开：录单号用 WooCommerce Shipment Tracking 插件，查轨迹用快递100 API，显示用 woocommerce_order_details_after_order_table 钩子。
• 接口地址是 https://poll.kuaidi100.com/poll/query.do，sign 必须大写 MD5，拼接顺序 param + key + customer。
• 必须加 transient 缓存，否则按次计费的额度会被页面刷新吃光。
• 顺丰、京东、EMS 要单独申请，没开通时返回的是空轨迹，不会报错。