请求协助将配送公司RESTful API集成至WordPress WooCommerce站点

根据你的场景，我整理了一套完整的落地方案，涵盖REST服务搭建、订单流程集成、前端展示和测试环节，完全贴合WordPress/WooCommerce生态：

1. 搭建接受POST请求的自定义REST服务 #

咱们直接在WordPress环境内用WP REST API实现，不用额外搭建独立服务，更省心：

注册REST路由&处理请求 #

添加以下代码到主题的functions.php或者自定义插件里，注册一个专属的POST接口：

add_action('rest_api_init', function () {
    register_rest_route(
        'delivery/v1', // 自定义API命名空间，避免冲突
        '/generate-tracking', // 接口路径
        array(
            'methods' => 'POST',
            'callback' => 'generate_delivery_tracking',
            'permission_callback' => function () {
                // 验证权限，确保只有管理员/有权限的运营人员能调用
                return current_user_can('edit_shop_orders');
            },
        )
    );
});

function generate_delivery_tracking(WP_REST_Request $request) {
    // 获取请求参数
    $params = $request->get_params();
    $order_id = $params['order_id'] ?? null;
    
    // 参数校验
    if (!$order_id) {
        return new WP_REST_Response(['error' => '订单ID不能为空'], 400);
    }

    $order = wc_get_order($order_id);
    if (!$order) {
        return new WP_REST_Response(['error' => '无效的订单ID'], 404);
    }

    // 调用第三方配送API
    $delivery_api_url = '你的第三方测试服务器链接';
    $api_key = '你的API密钥';
    
    // 按照第三方要求组装请求体（这里是示例，需根据对方文档调整字段）
    $payload = [
        'order_number' => $order->get_order_number(),
        'recipient' => [
            'name' => $order->get_shipping_first_name() . ' ' . $order->get_shipping_last_name(),
            'address' => $order->get_shipping_address_1(),
            'phone' => $order->get_billing_phone()
        ],
        'weight' => $order->get_total_weight() // 如果第三方需要重量信息
    ];

    // 发起POST请求到配送API
    $response = wp_remote_post($delivery_api_url, [
        'headers' => [
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $api_key // 认证方式按对方要求调整，比如API-Key: xxx
        ],
        'body' => json_encode($payload),
        'timeout' => 30
    ]);

    // 处理API响应
    if (is_wp_error($response)) {
        return new WP_REST_Response(['error' => '调用配送API失败: ' . $response->get_error_message()], 500);
    }

    $api_response = json_decode(wp_remote_retrieve_body($response), true);
    if (isset($api_response['success']) && $api_response['success']) {
        // 把追踪信息和条形码保存到WooCommerce订单元数据
        $order->update_meta_data('_delivery_tracking_number', $api_response['tracking_number']);
        $order->update_meta_data('_delivery_barcode', $api_response['barcode_data']);
        $order->save();

        // 返回成功响应
        return new WP_REST_Response([
            'tracking_number' => $api_response['tracking_number'],
            'barcode' => $api_response['barcode_data'],
            'tracking_url' => $api_response['tracking_url'] ?? ''
        ], 200);
    } else {
        return new WP_REST_Response(['error' => '配送API返回错误: ' . ($api_response['message'] ?? '未知错误')], 400);
    }
}

2. 集成到WooCommerce订单流程 #

可以选择自动触发或手动触发两种方式：

方式一：订单完成后自动生成追踪信息 #

当订单状态变为“已完成”时，自动调用接口生成追踪信息，添加以下代码：

add_action('woocommerce_order_status_completed', 'auto_generate_tracking_on_completion', 10, 1);
function auto_generate_tracking_on_completion($order_id) {
    // 调用咱们的自定义REST接口
    $request = new WP_REST_Request('POST', '/wp-json/delivery/v1/generate-tracking');
    $request->set_param('order_id', $order_id);
    rest_do_request($request);
}

方式二：后台手动触发（适合特殊订单） #

在WooCommerce订单详情页添加一个按钮，管理员可以手动点击生成：

add_action('woocommerce_admin_order_data_after_shipping_address', 'add_generate_tracking_button');
function add_generate_tracking_button($order) {
    ?>
    <div class="button-container" style="margin-top:15px;">
        <button type="button" class="button button-primary generate-tracking" data-order-id="<?php echo $order->get_id(); ?>">生成配送追踪信息</button>
    </div>
    <script>
        jQuery(document).ready(function($) {
            $('.generate-tracking').on('click', function() {
                var orderId = $(this).data('order-id');
                $.ajax({
                    url: '/wp-json/delivery/v1/generate-tracking',
                    method: 'POST',
                    data: {order_id: orderId},
                    beforeSend: function(xhr) {
                        // 验证WP REST API权限
                        xhr.setRequestHeader('X-WP-Nonce', '<?php echo wp_create_nonce('wp_rest'); ?>');
                    },
                    success: function(response) {
                        alert('追踪信息生成成功！追踪号: ' + response.tracking_number);
                        location.reload(); // 刷新页面显示新数据
                    },
                    error: function(xhr) {
                        alert('生成失败: ' + xhr.responseJSON.error);
                    }
                });
            });
        });
    </script>
    <?php
}

3. 前端展示追踪信息&条形码 #

在用户的“我的账户-订单详情”页面展示追踪号和条形码，添加以下代码：

add_action('woocommerce_view_order', 'display_tracking_info_on_order_page', 20, 1);
function display_tracking_info_on_order_page($order_id) {
    $order = wc_get_order($order_id);
    $tracking_number = $order->get_meta('_delivery_tracking_number');
    $barcode = $order->get_meta('_delivery_barcode');
    
    if ($tracking_number) {
        echo '<div class="delivery-tracking" style="margin:20px 0; padding:15px; border:1px solid #eee; border-radius:4px;">';
        echo '<h3 style="margin-top:0;">配送追踪信息</h3>';
        echo '<p><strong>追踪号:</strong> ' . esc_html($tracking_number) . '</p>';
        
        if ($barcode) {
            echo '<div class="barcode" style="margin-top:10px;">';
            // 如果第三方返回的是条形码图片URL，直接显示
            if (filter_var($barcode, FILTER_VALIDATE_URL)) {
                echo '<img src="' . esc_url($barcode) . '" alt="配送条形码">';
            } else {
                // 如果是条形码文本（比如CODE128编码），可以用JsBarcode库生成
                echo '<svg class="barcode-svg"></svg>';
                echo '<script src="https://cdn.jsdelivr.net/npm/jsbarcode@3.11.6/dist/JsBarcode.all.min.js"></script>';
                echo '<script>JsBarcode(".barcode-svg", "' . esc_js($barcode) . '", {format: "CODE128"});</script>';
            }
            echo '</div>';
        }
        echo '</div>';
    }
}

4. 测试要点 #

1. API连通性测试：用Postman或curl调用你的自定义REST接口，传入测试订单ID，检查是否能正确调用第三方测试服务器并返回数据。
2. 权限验证：尝试用非管理员账号调用接口，确保会返回权限错误。
3. 订单流程测试：模拟订单完成，检查追踪信息是否自动保存到订单元数据；在后台手动点击按钮，验证功能正常。
4. 错误场景测试：传入无效订单ID、错误API密钥，检查返回的错误信息是否清晰易懂。

内容的提问来源于stack exchange，提问作者zyz82