WooCommerce自定义配送API集成求助：请求发送位置与实现示例

核心实现思路 #

自定义配送方式需扩展WooCommerce的WC_Shipping_Method类，在两个关键节点调用第三方API：

• 结算页实时计算运费：用户选择配送方式时，调用API获取实时运费价格
• 订单创建后同步数据：用户提交订单后，推送订单信息至物流API生成运单

代码示例：实时运费计算（核心部分） #

以下是完整的自定义配送方式插件框架，包含API调用逻辑：

// 初始化自定义配送方式
add_action('woocommerce_shipping_init', 'custom_shipping_method_init');
function custom_shipping_method_init() {
    if (!class_exists('WC_Custom_Shipping_Method')) {
        class WC_Custom_Shipping_Method extends WC_Shipping_Method {
            public function __construct($instance_id = 0) {
                $this->id = 'custom_shipping';
                $this->instance_id = absint($instance_id);
                $this->method_title = __('第三方物流配送', 'woocommerce');
                $this->method_description = __('集成第三方物流API的配送方式', 'woocommerce');
                $this->supports = array('shipping-zones', 'instance-settings');
                $this->init();
            }

            // 初始化设置项
            public function init() {
                $this->init_form_fields();
                $this->init_settings();
                $this->title = $this->get_option('title');
                add_action('woocommerce_update_options_shipping_' . $this->id, array($this, 'process_admin_options'));
            }

            // 后台设置表单
            public function init_form_fields() {
                $this->form_fields = array(
                    'title' => array(
                        'title' => __('显示名称', 'woocommerce'),
                        'type' => 'text',
                        'default' => __('第三方物流配送', 'woocommerce'),
                    ),
                    'api_url' => array(
                        'title' => __('API请求地址', 'woocommerce'),
                        'type' => 'text',
                        'desc_tip' => true,
                        'description' => __('第三方物流提供的POST接口地址'),
                    ),
                    'api_key' => array(
                        'title' => __('API认证密钥', 'woocommerce'),
                        'type' => 'password',
                        'desc_tip' => true,
                        'description' => __('接口所需的认证密钥'),
                    ),
                );
            }

            // 计算运费时调用API
            public function calculate_shipping($package = array()) {
                $api_url = $this->get_option('api_url');
                $api_key = $this->get_option('api_key');

                // 构造API请求参数（根据第三方文档调整字段）
                $request_data = array(
                    'origin' => array(
                        'city' => '北京市',
                        'postcode' => '100000'
                    ),
                    'destination' => array(
                        'city' => $package['destination']['city'],
                        'postcode' => $package['destination']['postcode']
                    ),
                    'total_weight' => $package['contents_weight'],
                    'items' => array()
                );

                // 遍历购物车商品，补充商品信息
                foreach ($package['contents'] as $item) {
                    $product = $item['data'];
                    $request_data['items'][] = array(
                        'name' => $product->get_name(),
                        'quantity' => $item['quantity'],
                        'weight' => $product->get_weight() ?: 0.5 // 无重量时设默认值
                    );
                }

                // 发送POST请求
                $response = wp_remote_post($api_url, array(
                    'headers' => array(
                        'Content-Type' => 'application/json',
                        'Authorization' => 'Bearer ' . $api_key // 认证方式根据文档调整
                    ),
                    'body' => json_encode($request_data),
                    'timeout' => 10,
                ));

                // 处理API响应
                if (!is_wp_error($response)) {
                    $response_body = json_decode(wp_remote_retrieve_body($response), true);
                    if ($response_body && isset($response_body['fee'])) {
                        // 添加计算得到的运费
                        $this->add_rate(array(
                            'id' => $this->id . $this->instance_id,
                            'label' => $this->title,
                            'cost' => $response_body['fee'],
                            'calc_tax' => 'per_item'
                        ));
                    } else {
                        // 响应异常时使用默认运费
                        $this->add_rate(array(
                            'id' => $this->id . $this->instance_id,
                            'label' => $this->title . ' (暂无法获取实时运费)',
                            'cost' => 20,
                            'calc_tax' => 'per_item'
                        ));
                    }
                } else {
                    // 请求失败时使用默认运费
                    $this->add_rate(array(
                        'id' => $this->id . $this->instance_id,
                        'label' => $this->title . ' (服务暂时不可用)',
                        'cost' => 20,
                        'calc_tax' => 'per_item'
                    ));
                    // 记录错误日志
                    error_log('物流API请求失败: ' . $response->get_error_message());
                }
            }
        }
    }
}

// 将自定义配送方式添加到WooCommerce
add_filter('woocommerce_shipping_methods', 'add_custom_shipping_method');
function add_custom_shipping_method($methods) {
    $methods['custom_shipping'] = 'WC_Custom_Shipping_Method';
    return $methods;
}

代码示例：订单创建后同步数据 #

如果需要在用户下单后推送订单信息至物流API，使用woocommerce_new_order钩子：

add_action('woocommerce_new_order', 'push_order_to_shipping_api', 10, 1);
function push_order_to_shipping_api($order_id) {
    $order = wc_get_order($order_id);
    if (!$order) return;

    // 获取API配置（从自定义配送方式的设置中读取）
    $shipping_settings = get_option('woocommerce_custom_shipping_settings');
    $api_url = $shipping_settings['api_url'];
    $api_key = $shipping_settings['api_key'];

    // 构造订单同步数据
    $request_data = array(
        'order_sn' => $order->get_order_number(),
        'customer' => array(
            'name' => $order->get_billing_full_name(),
            'phone' => $order->get_billing_phone(),
            'email' => $order->get_billing_email()
        ),
        'shipping_address' => array(
            'address' => $order->get_shipping_address_1() . ' ' . $order->get_shipping_address_2(),
            'city' => $order->get_shipping_city(),
            'postcode' => $order->get_shipping_postcode(),
            'country' => $order->get_shipping_country()
        ),
        'items' => array()
    );

    // 遍历订单商品
    foreach ($order->get_items() as $item) {
        $product = $item->get_product();
        $request_data['items'][] = array(
            'sku' => $product->get_sku(),
            'name' => $item->get_name(),
            'quantity' => $item->get_quantity(),
            'price' => $item->get_subtotal()
        );
    }

    // 发送POST请求
    $response = wp_remote_post($api_url, array(
        'headers' => array(
            'Content-Type' => 'application/json',
            'Authorization' => 'Bearer ' . $api_key
        ),
        'body' => json_encode($request_data),
        'timeout' => 15,
    ));

    // 处理响应并添加订单备注
    if (is_wp_error($response)) {
        $error_msg = '物流API推送失败: ' . $response->get_error_message();
        $order->add_order_note($error_msg);
        error_log($error_msg);
    } else {
        $response_code = wp_remote_retrieve_response_code($response);
        if ($response_code == 200) {
            $order->add_order_note('已成功推送订单至第三方物流系统');
        } else {
            $error_msg = '物流API响应异常，响应码: ' . $response_code . '，响应内容: ' . wp_remote_retrieve_body($response);
            $order->add_order_note('推送物流系统失败，请联系管理员');
            error_log($error_msg);
        }
    }
}

关键注意事项 #

• API参数匹配：务必对照第三方物流的API文档调整request_data的字段名称和格式，确保和Postman测试时的参数完全一致
• 认证方式：常见的认证方式有Bearer Token、API Key放在Header或请求体，根据文档调整headers参数
• 异常处理：必须处理请求超时、响应错误等情况，避免影响用户结算或订单创建流程
• 日志调试：开启WooCommerce系统日志（WooCommerce > 设置 > 系统状态 > 日志），或使用error_log()记录请求/响应内容，方便排查问题

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