Hook action và filter

Danh sách hook của plugin, đọc trực tiếp từ mã nguồn phiên bản 1.3.6. Đủ để đổi phí ship, sửa dữ liệu trước khi đăng đơn, loại bớt gói dịch vụ 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_vnpost_create_order`	`$order_id`	Ngay sau khi đăng đơn VNPost thành công. Hook chính để nối sang hệ thống khác — số hiệu đọc bằng `$order->get_meta('vnpost_itemcode')`. Chính plugin dùng hook này để gửi email báo vận đơn.
`after_vnpost_order_action_html`	`$order`	Cuối ô VNPost trong trang sửa đơn hàng. Dùng để thêm nút của riêng bạn.
`devvn_setting_tab_before_vn_checkout`	không có	Trước phần cài đặt trang thanh toán dùng chung.

Filter — phí vận chuyển và dịch vụ

Hook	Mặc định / tham số	Dùng để
`devvn_vnpost_rate`	mảng `id`, `label`, `cost`, `meta_data`	Đổi phương thức vận chuyển trước khi WooCommerce nhận — kể cả số tiền ở khoá `cost`. Hook chính để cộng phụ phí hay miễn phí ship.
`vnpost_service_name`	`$service`	Đổi tên gói dịch vụ hiện cho khách.
`vnpost_exclude_services`	`['EMS', 'BK']`	Danh sách mã gói không hiện cho khách.
`get_vnpost_spdv`	mảng	Sửa danh sách gói dịch vụ plugin biết.
`vnpost_get_fee` · `vnpost_get_fee_args`	`$args`	Sửa dữ liệu gửi đi khi hỏi giá.
`vnpost_cod_fee`	`['cod']`	Những mã cổng thanh toán được coi là COD (có thu hộ).
`devvn_title_shipping_fee_failed`	`'Phí vận chuyển sẽ báo sau.'`	Chữ hiện khi VNPost không trả được giá.

Filter — đăng đơn và huỷ đơn

Hook	Tham số	Dùng để
`vnpost_create_order`	`$args`	Sửa toàn bộ dữ liệu gửi lên VNPost ngay trước khi đăng đơn. Hook mạnh nhất của plugin.
`vnpost_create_order_args`	`$args`	Sửa tham số ở tầng thấp hơn của lệnh tạo đơn.
`vnpost_order_code`	`$OrderCode`, `$order`	Đổi mã đơn gửi sang VNPost — dùng khi bạn muốn mã theo quy ước riêng.
`vnpost_correct_order_args`	`$args`	Sửa dữ liệu khi gửi lệnh chỉnh sửa đơn.
`vnpost_cancel_order` · `vnpost_check_cancel_order`	`$args`	Sửa dữ liệu khi gửi yêu cầu huỷ và khi hỏi lại kết quả huỷ.
`vnpost_create_ticket_args`	`$args`	Sửa dữ liệu khi tạo phiếu yêu cầu với VNPost.

Filter — trạng thái, địa chỉ, webhook

Hook	Mặc định / tham số	Dùng để
`devvn_vnpost_to_order_status_<ma>`	trạng thái đã ánh xạ	Ép trạng thái WooCommerce cho một mã trạng thái VNPost cụ thể, bỏ qua bảng ánh xạ trong giao diện.
`devvn_vnpost_status` · `devvn_vnpostv2_status`	mảng	Sửa danh sách trạng thái VNPost plugin biết (hệ cũ và hệ mới).
`devvn_vnpost_webhook_pubkey`	khoá công khai RSA	Thay khoá công khai dùng để xác thực chữ ký webhook. Chỉ đổi khi VNPost cấp khoá mới.
`devvn_vnpost_is_two_level_address`	`false`	Bật chế độ địa chỉ hai cấp (Tỉnh → Phường), bỏ cấp Quận/Huyện.
`devvn_vnpost_resolve_address`	`$out`, `$role`, `$addr`, `$is_two_level`	Can thiệp vào cách plugin quy đổi địa chỉ WooCommerce sang mã địa chỉ VNPost.
`devvn_vnpost_city_2cap`	mảng	Danh sách tỉnh áp dụng địa chỉ hai cấp.
`devvn_vnpost_token_ttl`	`50 * MINUTE_IN_SECONDS`	Thời gian giữ token trước khi xin lại.

Filter — email, giao diện, gỡ lỗi

Hook	Mặc định / tham số	Dùng để
`vnpost_mail_string_filter`	`$string`, `$order`	Thêm mã thay thế của riêng bạn vào email báo vận đơn.
`vnpost_tracking_order_priority`	`10`	Độ ưu tiên khi plugin chèn hành trình vào trang chi tiết đơn hàng của khách.
`vnpost_option` · `vnpost_get_option`	mảng · `$value`, `$name`, `$default`	Đọc và ghi đè tuỳ chọn của plugin bằng code.
`vnpost_debug`	`false`	Trả `true` để bật ghi nhật ký bằng code thay vì bật ở giao diện.

Ví dụ hay dùng

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

PHP

add_filter( 'devvn_vnpost_rate', function ( $rate ) {
    $rate['cost'] = $rate['cost'] + 5000;
    return $rate;
} );

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

PHP

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

Giấu bớt gói dịch vụ không muốn bán

PHP

add_filter( 'vnpost_exclude_services', function ( $codes ) {
    $codes[] = 'ETN013'; // Hoả tốc
    return $codes;
} );

Đổi mã đơn gửi sang VNPost theo quy ước riêng

PHP

add_filter( 'vnpost_order_code', function ( $code, $order ) {
    return 'SHOP-' . $order->get_id();
}, 10, 2 );

Thêm ghi chú cố định vào mọi vận đơn

PHP

add_filter( 'vnpost_create_order', function ( $args ) {
    $args['Description'] = 'Goi truoc khi giao 15 phut';
    return $args;
} );

Tên khoá trong $args theo đúng tài liệu API của VNPost. Bật Ghi log (debug) rồi đăng thử một đơn, xem WooCommerce → Trạng thái → Nhật ký để biết cấu trúc thật trước khi sửa.

Ghi lại số hiệu vận đơn sang hệ thống khác

PHP

add_action( 'devvn_after_vnpost_create_order', function ( $order_id ) {
    $order = wc_get_order( $order_id );
    $itemcode = $order ? $order->get_meta( 'vnpost_itemcode' ) : '';
    if ( $itemcode ) {
        error_log( 'Don ' . $order_id . ' co so hieu ' . $itemcode );
    }
} );

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

PHP

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

Thử ở môi trường Sandbox trước

Hai hook devvn_vnpost_rate và vnpost_create_order tác động thẳng lên số tiền khách trả và lên vận đơn thật. Chuyển sang Sandbox ở mục Đăng nhập để thử — đơn tạo ở đó không phát sinh chi phí.

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