Speedy за WooCommerce — документация за разработчици

Плъгинът Speedy за WooCommerce предоставя набор от филтри (filters) и действия (actions), с които разработчиците могат да променят поведението му, без да редактират кода на самия плъгин. По този начин промените остават непокътнати при бъдещи обновявания.

Всички примери по-долу се поставят във файла functions.php на вашата дъщерна тема (child theme) или в собствен плъгин.

Съвет: филтърът винаги трябва да връща стойност, докато действието само изпълнява код (не връща нищо).

Филтри

speedy_calculation_data

Променя данните, изпращани към Speedy при изчисляване на цената за доставка.

• Параметри: $jsonData (масив — заявката към API), $data (масив — вътрешни данни за поръчката/количката)
• Връща: $jsonData

add_filter( 'speedy_calculation_data', function ( $jsonData, $data ) {
    // Пример: винаги калкулирай за минимум 1 кг
    if ( empty( $jsonData['service']['calculationPrecision'] ) ) {
        $jsonData['parcels'][0]['weight'] = max( 1, $jsonData['parcels'][0]['weight'] );
    }
    return $jsonData;
}, 10, 2 );

speedy_shipping_services

Променя списъка с налични услуги на Speedy, върнати от API.

• Параметри: $services (масив), $speedy_options (настройки на плъгина), $data
• Връща: $services

speedy_shipping_price

Променя крайната цена за доставка, показвана на клиента.

• Параметри: $shipping_price (float), $speedy_options, $data, $price (оригинална цена от API), $service_id
• Връща: $shipping_price

add_filter( 'speedy_shipping_price', function ( $price, $options, $data, $orig, $service_id ) {
    // Пример: добави 2 лв. такса за обработка
    return $price + 2;
}, 10, 5 );

speedy_order_products

Променя списъка с продукти, който отива в товарителницата (съдържание на пратката).

• Параметри: $result (масив/текст), $order (WC_Order)
• Връща: $result

add_filter( 'speedy_order_products', function ( $result, $order ) {
    return 'Поръчка #' . $order->get_order_number();
}, 10, 2 );

speedy_receiver_address_validation

Позволява собствена валидация на адреса на получателя.

• Параметри: $validation (масив, напр. ['valid' => true, 'msg' => '']), $data
• Връща: $validation

add_filter( 'speedy_receiver_address_validation', function ( $validation, $data ) {
    if ( empty( $data['phone'] ) ) {
        return array( 'valid' => false, 'msg' => 'Телефонът е задължителен.' );
    }
    return $validation;
}, 10, 2 );

speedy_create_shipment_data

Променя данните преди създаване на товарителница.

• Параметри: $jsonData (заявката към API), $data
• Връща: $jsonData

add_filter( 'speedy_create_shipment_data', function ( $jsonData, $data ) {
    $jsonData['shipment']['note'] = 'Обади се преди доставка';
    return $jsonData;
}, 10, 2 );

speedy_create_shipment_result

Достъп до отговора след създаване на товарителница.

• Параметри: $jsonResponse (отговор от API), $jsonData, $data, $speedy_options
• Връща: $jsonResponse

speedy_delete_shipment_result

Достъп до отговора след изтриване/анулиране на товарителница.

• Параметри: $jsonResponse, $jsonData, $data, $speedy_options
• Връща: $jsonResponse

speedy_geolocation

Включва/изключва бутона за геолокация („Намери най-близък офис").

• Параметри: $enabled (bool)
• Връща: bool

add_filter( 'speedy_geolocation', '__return_false' ); // изключи геолокацията

Действия

speedy_add_loading

Изпълнява се след успешно създаване на товарителница.

• Параметри: $order_id, $result (отговор от API)

add_action( 'speedy_add_loading', function ( $order_id, $result ) {
    // Пример: запиши в лог
    error_log( 'Speedy товарителница за поръчка #' . $order_id );
}, 10, 2 );