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

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

Поставяйте примерите във functions.php на дъщерна тема или в собствен плъгин.

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

Филтри

pigeon_calculate_data

Променя данните (payload), изпращани към Pigeon API при изчисляване на цената за доставка.

• Параметри: $payload (масив — заявката към API), $data (вътрешни данни)
• Връща: $payload

add_filter( 'pigeon_calculate_data', function ( $payload, $data ) {
    // Пример: наложи стандартна услуга
    $payload['service_type'] = 'standard';
    return $payload;
}, 10, 2 );

pigeon_calculate_result

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

• Параметри: $calc (отговор от API), $payload, $data, $opts (настройки)
• Връща: $calc

add_filter( 'pigeon_calculate_result', function ( $calc, $payload, $data, $opts ) {
    return $calc;
}, 10, 4 );

pigeon_create_shipment_data

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

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

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

pigeon_create_shipment_result

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

• Параметри: $result (полето data от отговора на API), $payload, $data, $opts
• Връща: $result

add_filter( 'pigeon_create_shipment_result', function ( $result, $payload, $data, $opts ) {
    return $result;
}, 10, 4 );

pigeon_address_validation

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

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

add_filter( 'pigeon_address_validation', function ( $result, $data ) {
    if ( empty( $data['pigeon_city_id'] ) ) {
        return array( 'valid' => false, 'msg' => 'Моля, изберете град.' );
    }
    return $result;
}, 10, 2 );

pigeon_geolocation

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

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

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

Действия

pigeon_shipment_created

Изпълнява се след успешно създаване на товарителница (вкл. при автоматично генериране).

• Параметри: $order_id, $shipment (масив с данните за пратката, вкл. reference_number)

add_action( 'pigeon_shipment_created', function ( $order_id, $shipment ) {
    // Пример: запиши референтния номер като бележка към поръчката
    $order = wc_get_order( $order_id );
    if ( $order && ! empty( $shipment['reference_number'] ) ) {
        $order->add_order_note( 'Pigeon товарителница: ' . $shipment['reference_number'] );
    }
}, 10, 2 );