如何在WooCommerce中为指定配送区域动态添加配送方式

云上老周

2026-7-13

如何为WooCommerce指定配送区域动态创建配送方式

我通过API调用获取配送信息，已在WooCommerce中设置名为"United_States"的配送区域。需要利用API返回的信息为该区域创建配送方式，希望得到具体实现指导。

以下是我当前使用的代码：

function handle_api_request() { 
...
...
...
 
if ($response_code === 200) {

    $response_data = json_decode($response, true);

    echo '<script>console.log("response in 200")</script>';

    if (is_array($response_data) && array_key_exists('shipments', $response_data)) {

        foreach ($response_data['shipments'] as $shipment) {

            $quotes = $shipment['quotes'];

            foreach ($quotes as $quote) {

                $shippingOption = $quote['shipping_option'];

                $price = (float) $quote['price'];
        
                // 我需要在这里用 $shippingOption 和 $price 为 "United_states" 配送区域创建配送方式

            }
        }
    } else {
        echo 'Error processing response data';
    }
} else {
    echo 'Request failed with status code: ' . $response_code;
}

add_action('woocommerce_after_checkout_billing_form', 'custom_handle_api_request_on_checkout');
function custom_handle_api_request_on_checkout() {
... 
...
...
handle_api_request();
}

从API响应中解析出的配送选项及价格如下：

配送选项：USPS - PO Box，价格：4.7064
配送选项：UPS - Mail Innovations，价格：4.7064
配送选项：USPS Postal - BPM Parcels，价格：4.7064
配送选项：UPS - US Ground，价格：17.3941
配送选项：UPS - US 2nd Day Air，价格：21.8532
配送选项：UPS - US Next Day Air，价格：45.769

API原始响应：

{
    "subtotals": {
        "items": "6.6351",
        "fee": "1.8698",
        "app_fee": "0.0000"
    },
    "price": "8.5049",
    "vat": "0.0000",
    "currency": "USD",
    "expire_date": "2023-08-09T22:45:02+00:00",
    "shipments": [
        {
            "total_weight": "241",
            "items": [
                {
                    "reference": "1"
                }
            ],
            "quotes": [
                {
                    "quote": "92f14b53c493a41578b3fc55522243cee77320a2d5b72a898efccb564246cc69",
                    "service": "Ground - Tracked",
                    "shipping_level": "cp_ground",
                    "shipping_option": "USPS Postal - BPM Parcels",
                    "price": "4.7064",
                    "vat": "0.0000",
                    "currency": "USD"
                },
                {
                    "quote": "3ed6ac6c6257817f15be87634f622c2e5426a26b3de915572fe8764c340f1f2d",
                    "service": "Ground - Tracked",
                    "shipping_level": "cp_ground",
                    "shipping_option": "USPS - PO Box ",
                    "price": "4.7064",
                    "vat": "0.0000",
                    "currency": "USD"
                }
            ]
        }
    ],
    "invoice_currency": "EUR",
    "invoice_exchange_rate": "0.8825"
}

实现方案

WooCommerce的配送方式需要通过特定钩子和类来注册，不能直接在表单钩子中创建。以下是完整实现步骤：

1. 存储API获取的配送报价

先把API返回的配送数据存入WooCommerce会话，确保后续计算配送费率时能读取到：

function handle_api_request() { 
    // ... 你的API请求逻辑 ...
 
    if ($response_code === 200) {
        $response_data = json_decode($response, true);

        if (is_array($response_data) && array_key_exists('shipments', $response_data)) {
            $shipping_quotes = [];
            foreach ($response_data['shipments'] as $shipment) {
                foreach ($shipment['quotes'] as $quote) {
                    $shipping_quotes[] = [
                        'name' => $quote['shipping_option'],
                        'price' => (float) $quote['price']
                    ];
                }
            }
            // 将报价存入WC会话
            WC()->session->set('custom_shipping_quotes', $shipping_quotes);
        } else {
            echo '处理响应数据出错';
        }
    } else {
        echo '请求失败，状态码: ' . $response_code;
    }
}

// 调整API请求时机，确保在计算配送费率前完成
add_action('woocommerce_checkout_init', 'custom_handle_api_request_on_checkout');
function custom_handle_api_request_on_checkout() {
    // ... 你的API请求前置逻辑 ...
    handle_api_request();
}

2. 注册自定义配送方式类

创建一个继承自WC_Shipping_Method的自定义类，用于承载动态配送选项：

// 注册自定义配送方式
add_action('woocommerce_shipping_methods', 'register_custom_shipping_method');
function register_custom_shipping_method($methods) {
    $methods['custom_dynamic_shipping'] = 'WC_Custom_Dynamic_Shipping';
    return $methods;
}

// 自定义配送方式核心类
class WC_Custom_Dynamic_Shipping extends WC_Shipping_Method {
    public function __construct($instance_id = 0) {
        $this->id = 'custom_dynamic_shipping';
        $this->instance_id = absint($instance_id);
        $this->method_title = '动态API配送';
        $this->method_description = '通过API获取的动态配送选项';
        $this->supports = [
            'shipping-zones',
            'instance-settings',
        ];
        $this->init();
    }

    public function init() {
        $this->init_form_fields();
        $this->init_settings();
        $this->enabled = $this->get_option('enabled');
        add_action('woocommerce_update_options_shipping_' . $this->id, [$this, 'process_admin_options']);
    }

    public function init_form_fields() {
        $this->form_fields = [
            'enabled' => [
                'title'       => '启用',
                'type'        => 'checkbox',
                'description' => '启用该配送方式',
                'default'     => 'yes'
            ]
        ];
    }
}

3. 为指定区域添加动态配送费率

通过woocommerce_package_rates钩子，判断当前配送区域是否为"United_States"，然后添加动态选项：

add_filter('woocommerce_package_rates', 'add_dynamic_shipping_rates_for_us_zone', 10, 2);
function add_dynamic_shipping_rates_for_us_zone($rates, $package) {
    // 获取当前用户所在的配送区域
    $shipping_zone = wc_get_shipping_zone($package);
    if ($shipping_zone->get_zone_name() !== 'United_States') {
        return $rates;
    }

    // 从会话中读取API获取的配送报价
    $shipping_quotes = WC()->session->get('custom_shipping_quotes');
    if (empty($shipping_quotes)) {
        return $rates;
    }

    // 遍历报价，创建配送费率选项
    foreach ($shipping_quotes as $quote) {
        $rate_id = 'custom_dynamic_' . sanitize_title($quote['name']);
        $rate = new WC_Shipping_Rate();
        
        $rate->id = $rate_id;
        $rate->label = $quote['name'];
        $rate->cost = $quote['price'];
        $rate->taxes = []; // 如需计算税费，可在此添加逻辑
        $rate->method_id = 'custom_dynamic_shipping';

        $rates[$rate_id] = $rate;
    }

    return $rates;
}

注意事项

需在WooCommerce后台的United_States配送区域中，启用"动态API配送"这个方式
可根据需求格式化价格（比如保留两位小数：number_format($quote['price'], 2)）
会话数据会随用户会话结束自动清除，避免旧数据干扰后续订单
如需支持税费计算，可结合WooCommerce的税费规则调整$rate->taxes字段

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