Hook action và filter

Danh sách hook của plugin, đọc trực tiếp từ mã nguồn phiên bản 2.6.1. Đủ để đổi phí ship, sửa dữ liệu trước khi tạo vận đơn, đổi cách tính khối lượng quy đổi và móc vào luồng webhook — mà không phải sửa file plugin.

Đặt code ở đâu

Đặt trong functions.php của child theme, hoặc tốt hơn là một plugin nhỏ riêng để đổi giao diện không mất code. Đừng sửa file trong thư mục plugin — mọi thay đổi sẽ mất khi cập nhật.

Action

Hook	Tham số	Chạy khi nào
`devvn_after_vtp_create_order`	`$order`	Ngay sau khi tạo vận đơn ViettelPost thành công. Hook chính để nối sang hệ thống khác — mã vận đơn đọc bằng `$order->get_meta('vtpost_order_number')`.
`vn_shipping_tabs_nav`	`$current_tab`	Giữa thanh tab, để thêm tab của riêng bạn.
`vn_shipping_tabs_content_<tab>`	`$current_tab`	Nội dung của tab tự thêm. Chính addon đăng đơn tự động dùng cặp hook này.
`before_vn_shipping_tabs_nav` · `after_vn_shipping_tabs_nav`	`$current_tab`	Trước và sau toàn bộ thanh tab.
`vn_checkout_setting_general`	không có	Nội dung tab General — module trang thanh toán dùng chung móc vào đây.

Filter — phí vận chuyển

Hook	Mặc định / tham số	Dùng để
`viettelpost_money_total`	`$rate['MONEY_TOTAL']`, `$rate`	Đổi số tiền phí ship hiện cho khách. Đây là hook gọn nhất để cộng phụ phí hay giảm giá ship.
`devvn_vtp_rate`	mảng `id`, `label`, `cost`, `calc_tax`, `meta_data`	Sửa nguyên gói phương thức vận chuyển trước khi WooCommerce nhận. Mạnh hơn nhưng dễ làm hỏng hơn.
`prefix_name_shipping_vtp`	`$service_name`	Đổi tên phương thức hiện ở trang thanh toán.
`devvn_viettelpost_service_name`	`$name`, `$service`	Đổi tên theo từng mã dịch vụ.
`devvn_title_shipping_fee_failed`	`'Phí vận chuyển sẽ báo sau.'`	Chữ hiện khi ViettelPost không trả được giá.
`vtpost_getprice_args`	`$data`, `$package`, `$hubid`, `$payment_methob`	Sửa dữ liệu gửi đi khi hỏi giá cho giỏ hàng.
`vtpost_getprice_args_order`	`$data`, `$order_id`, `$hubid`, `$args`	Như trên nhưng khi hỏi giá cho một đơn cụ thể.
`vtpost_getpriceall_args`	`$data`	Sửa dữ liệu khi hỏi giá tất cả dịch vụ cùng lúc.
`data_out_find_available_shipping`	`$data`, `$package`, `$hubid`, `$payment_methob`	Sửa dữ liệu khi dò danh sách dịch vụ khả dụng.

Filter — khối lượng và kho

Hook	Mặc định	Dùng để
`vtp_so_quydoi`	`6000` (dịch vụ tiết kiệm: `5000`)	Số chia khi tính khối lượng quy đổi theo kích thước: `(dài × rộng × cao) / số này`. ViettelPost lấy giá trị lớn hơn giữa cân nặng thật và khối lượng quy đổi.
`skip_weight_conversion`	`false`	Trả `true` để bỏ hẳn việc quy đổi theo kích thước, chỉ dùng cân nặng thật. Hợp với hàng nhỏ mà nặng.
`vtp_store_default`	`$HubID_Order`, `$order`	Ép kho gửi cho một đơn cụ thể, ghi đè kết quả chọn theo khu vực bán hàng.
`vtpost_auto_detect_provinces`	`[1, 2]`	Danh sách mã tỉnh áp dụng cơ chế dò tự động của ViettelPost (mặc định là Hà Nội và TP.HCM).

Filter — tạo vận đơn

Hook	Mặc định / tham số	Dùng để
`vtp_data_before_create_order`	`$data`, `$orderid`	Sửa toàn bộ dữ liệu gửi lên ViettelPost ngay trước khi tạo vận đơn. Hook mạnh nhất của plugin.
`vtp_order_product_data`	mảng thông tin hàng hoá	Đổi tên, số lượng, giá trị hàng ghi trên vận đơn.
`order_payment_default`	`3`	Hình thức thanh toán mặc định chọn sẵn trong khung tạo vận đơn.
`order_payment_modify`	`$order_payment`, `$order`	Đổi hình thức thanh toán theo từng đơn.
`devvn_ghtk_shipping_cod`	`['SCOD']`	Mã dịch vụ cộng thêm được coi là thu hộ COD.
`vtp_after_create_order_json_data`	`$json_data`, `$orderid`, `$order`	Sửa phản hồi của ViettelPost sau khi tạo vận đơn.
`vtp_after_timeout_create_order_json_data`	`$timeout_json_data`, `$orderid`, `$order`	Xử lý riêng trường hợp ViettelPost trả lời quá chậm.

Filter — trạng thái, email và gỡ lỗi

Hook	Mặc định / tham số	Dùng để
`devvn_vtp_to_order_status_<ma>`	trạng thái đã ánh xạ	Ép trạng thái WooCommerce cho một mã trạng thái ViettelPost cụ thể, bỏ qua bảng ánh xạ trong giao diện.
`devvn_vtp_status`	mảng	Sửa danh sách trạng thái ViettelPost mà plugin biết.
`mail_string_filter`	`$string`, `$order`	Thêm mã thay thế của riêng bạn vào email báo mã vận đơn.
`vtp_debug`	`false`	Trả `true` để ghi nhật ký chi tiết ra file trong thư mục plugin. Chỉ bật khi đang gỡ lỗi.

Ví dụ hay dùng

Cộng thêm phụ phí đóng gói vào phí ship

PHP

add_filter( 'viettelpost_money_total', function ( $cost, $rate ) {
    return $cost + 5000;
}, 10, 2 );

Miễn phí ship cho một hạng khách hàng

PHP

add_filter( 'viettelpost_money_total', function ( $cost, $rate ) {
    $user = wp_get_current_user();
    if ( in_array( 'vip_customer', (array) $user->roles, true ) ) {
        return 0;
    }
    return $cost;
}, 10, 2 );

Bỏ quy đổi khối lượng theo kích thước

Hợp với hàng nhỏ mà nặng — quy đổi theo thể tích chỉ làm cước đội lên vô lý.

PHP

add_filter( 'skip_weight_conversion', '__return_true' );

Đổi tên hàng hoá ghi trên vận đơn

PHP

add_filter( 'vtp_data_before_create_order', function ( $data, $orderid ) {
    $data['ORDER_NOTE'] = 'Cho xem hang, khong cho thu';
    return $data;
}, 10, 2 );

Tên khoá trong $data theo đúng tài liệu API của ViettelPost. Bật vtp_debug rồi tạo thử một vận đơn để xem cấu trúc thật trước khi sửa.

Ép một kho gửi cho đơn của vài tỉnh

PHP

add_filter( 'vtp_store_default', function ( $hub_id, $order ) {
    if ( in_array( $order->get_shipping_state(), array( 'VN-DN', 'VN-QNA' ), true ) ) {
        return '10000002';
    }
    return $hub_id;
}, 10, 2 );

Ghi lại mã vận đơn sang hệ thống khác

PHP

add_action( 'devvn_after_vtp_create_order', function ( $order ) {
    $tracking = $order->get_meta( 'vtpost_order_number' );
    if ( $tracking ) {
        error_log( 'Don ' . $order->get_id() . ' co ma van don ' . $tracking );
    }
} );

Thêm mã thay thế của riêng bạn vào email

PHP

add_filter( 'mail_string_filter', function ( $string, $order ) {
    return str_replace( '{hotline}', '0965 419 096', $string );
}, 10, 2 );

Thử trên bản sao website trước

Hai hook viettelpost_money_total và vtp_data_before_create_order tác động thẳng lên số tiền khách trả và lên vận đơn thật. ViettelPost không có môi trường thử riêng, nên hãy thử trên bản sao website, hoặc tạo vận đơn thử rồi huỷ ngay.

Còn vướng chỗ nào thì xem Giải đáp thắc mắc.