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.4.7. Dùng chúng để đổi phí ship, sửa dữ liệu trước khi đăng đơn, thêm nhãn đơn hàng hay tuỳ biến trang thanh toán — mà không phải sửa file plugin, vì mọi thay đổi trong plugin sẽ mất khi cập nhật.

Đặ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.

Action

Hook	Tham số	Chạy khi nào
`after_up_order_to_ghtk`	`$order`, `$order_ghtk`	Ngay sau khi đăng đơn lên GHTK thành công. `$order_ghtk` là phản hồi của GHTK, chứa mã vận đơn. Đây là hook chính để nối sang hệ thống khác.
`ghtk_after_webhook_process`	`$order`, `$result`	Sau khi plugin xử lý xong một lần webhook từ GHTK.
`devvn_vn_checkout_order_action`	`$order`	Trong hộp thao tác của trang đơn hàng — dùng để thêm nút của riêng bạn.
`vn_checkout_after_product_column_order`	`$order`	Sau cột sản phẩm ở danh sách đơn hàng, khi bật giao diện đơn hàng mới.
`ghtk_before_template_part` · `ghtk_after_template_part`	`$template_name`, `$template_path`, `$located`, `$args`	Trước và sau khi nạp một tệp giao diện của plugin.
`before_ghtk_tracking_form` · `after_ghtk_tracking_form` · `after_ghtk_tracking_result`	không có	Ba vị trí chèn nội dung vào trang tra cứu vận đơn.
`devvn_setting_tab_before_vn_checkout` · `devvn_setting_tab_mid_vn_checkout`	không có	Chèn thêm tab của riêng bạn vào trang Cài đặt GHTK.
`ghtk_license_tab_rows`	không có	Thêm dòng vào bảng của tab License.
`ghtk_license_changed`	`$valid` (bool)	Trạng thái license đổi giữa hợp lệ và không hợp lệ.
`ghtk_license_log`	`$message`	Mỗi dòng nhật ký của phần license.

Filter — phí vận chuyển

Hook	Mặc định / tham số	Dùng để
`devvn_ghtk_shipping_methob`	mảng `road`, `fly`	Thêm hoặc bớt hình thức vận chuyển hiện cho khách. Thêm khoá `xteam` để bật xFast.
`devvn_ghtk_shipping_fee`	`$fee`, `$method_id`	Cộng thêm hoặc bớt tiền vào phí ship GHTK trả về.
`devvn_ghtk_rate`	mảng thông tin gói cước	Sửa toàn bộ gói cước trước khi WooCommerce hiển thị.
`devvn_ghtk_data_before_shipment_fee`	`$data`	Sửa dữ liệu gửi lên GHTK khi hỏi phí. Hay dùng nhất là đặt cân nặng mặc định cho sản phẩm chưa khai.
`devvn_ghtk_data_before_bbs_shipment_fee`	`$data`	Như trên, cho gói cước hàng nặng BBS.
`ghtk_allow_xfast`	`['HOCHIMINH', 'HANOI']`	Những tỉnh nào được dùng dịch vụ giao nhanh xFast.
`text_road` · `text_fly` · `text_xteam` · `text_bbs`	tên hiển thị	Đổi tên từng hình thức vận chuyển hiện ở trang thanh toán.
`devvn_title_shipping_fee_failed`	`'Phí vận chuyển sẽ báo sau.'`	Đổi dòng chữ hiện khi không hỏi được phí từ GHTK.
`ghtk_is_freeship` · `ghtk_is_freeship_default`	bool, `$order`	Tự quyết định đơn nào được miễn phí vận chuyển.
`devvn_freeshipping_methob`	`['free_shipping', …]`	Phương thức nào được coi là "miễn phí" cho logic tự ẩn phương thức khác.
`list_methob_remove_special`	`['vtpost_shipping_method', 'ghtk_shipping_method']`	Phương thức nào bị ẩn khi bật tuỳ chọn ẩn phí ship hãng vận chuyển.

Filter — đăng đơn lên GHTK

Hook	Tham số	Dùng để
`devvn_ghtk_data_before_create_order_to_ghtk`	`$data`, `$order`	Sửa toàn bộ dữ liệu ngay trước khi tạo vận đơn. Hook mạnh nhất của nhóm này.
`devvn_ghtk_create_order_products`	`$products`, `$this`, `$order`	Sửa danh sách sản phẩm gửi kèm vận đơn.
`ghtk_tags`	mảng nhãn	Thêm hoặc bớt nhãn đơn hàng trong hộp thoại đăng đơn.
`devvn_ghtk_tags_default`	`[]`	Nhãn nào được tích sẵn. Ví dụ trả về `[10, 11]` để luôn cho xem hàng và đồng kiểm.
`devvn_ghtk_order_note`	ghi chú của khách	Đổi ghi chú gửi cho shipper.
`default_ghtk_pick_work_shift`	`''`	Ca lấy hàng chọn sẵn: 1 sáng, 2 chiều, 3 tối.
`ghtk_disable_cod`	`false`, `$order`	Ép tiền thu hộ về 0 cho những đơn nhất định.
`prefix_id_to_ghtk`	`''`, `$order`	Thêm tiền tố vào mã đơn gửi sang GHTK, hữu ích khi một tài khoản GHTK dùng cho nhiều website.
`ghtk_filter_address`	mảng quy tắc	Quy tắc làm sạch chuỗi địa chỉ trước khi gửi, để tránh GHTK báo địa chỉ không hợp lệ.
`get_order_weight` · `get_order_length` · `get_order_width` · `get_order_height`	giá trị, `$order_id`	Tự tính cân nặng và kích thước đơn theo cách của bạn.

Filter — trạng thái và webhook

Hook	Dùng để
`devvn_ghtk_status`	Sửa bảng tên các trạng thái GHTK hiển thị trong trang cài đặt.
`devvn_ghtk_to_order_status_<mã>`	Quyết định trạng thái WooCommerce cho một mã trạng thái GHTK cụ thể, ghi đè lựa chọn trong trang cài đặt. Ví dụ `devvn_ghtk_to_order_status_5`.
`devvn_mail_string_filter`	Sửa nội dung email báo mã vận đơn gửi cho khách.
`ghtk_tracking_order_logs_priority`	Đổi vị trí khối nhật ký vận đơn trong trang xem đơn của khách.
`ghtk_tracking_input_text` · `ghtk_tracking_submit_text`	Đổi chữ trong ô nhập và nút của form tra cứu vận đơn.

Filter — trang thanh toán và địa chỉ

Hook	Dùng để
`ghtk_custom_field_checkout`	Sửa các trường ở trang thanh toán: đổi lớp CSS, bỏ trường, đổi thứ tự.
`devvn_checkout_fields` · `devvn_woocommerce_order_fields`	Sửa danh sách trường ở trang thanh toán và ở trang sửa đơn hàng.
`get_customer_address_shipping`	Đổi cách plugin đọc địa chỉ giao hàng từ đơn.
`load_address_type` · `load_address_type_2` · `get_json_address_url`	Đổi cách và nơi nạp dữ liệu tỉnh/huyện/xã.
`phone_get_address_only_vn`	Bật/tắt kiểm tra số điện thoại theo định dạng Việt Nam.
`get_address_byphone`	Sửa kết quả trả về khi lấy địa chỉ tự động từ số điện thoại.
`devvn_formatted_woocommerce_price`	Đổi cách hiển thị giá khi bật chuyển giá sang dạng chữ.
`wc_devvn_cart_contents_weight` · `wc_devvn_cart_contents_dimension` · `wc_devvn_cart_quantity_package`	Tự tính cân nặng, kích thước và số lượng kiện của giỏ hàng.

Filter — giao diện quản trị và tiện ích

Hook	Dùng để
`devvn_ghtk_manage_shop_order_posts_columns`	Thêm hoặc bớt cột ở danh sách đơn hàng.
`ghtk_order_column_devvn_products` · `ghtk_order_column_devvn_stt`	Sửa nội dung cột sản phẩm và cột trạng thái ở danh sách đơn hàng.
`ghtk_template_path` · `ghtk_locate_template` · `ghtk_get_template`	Đổi thư mục và cách tìm tệp giao diện ghi đè trong theme. Mặc định là `devvn-ghtk/`.
`ghtk_fragments_default`	Sửa các mảnh giao diện cập nhật bằng AJAX ở trang thanh toán.
`devvn_ghtk_debug`	Bật ghi log không cần vào trang cài đặt: `add_filter('devvn_ghtk_debug', '__return_true');`
`ghtk_license_capability`	Quyền cần có để xem và sửa tab License. Mặc định `manage_woocommerce`.
`string_hide_length`	Số ký tự giữ lại khi che bớt chuỗi nhạy cảm trong giao diện.

Ví dụ hay dùng

Đặt cân nặng mặc định cho sản phẩm chưa khai

Đây là đoạn code được hỏi nhiều nhất. Sản phẩm không có cân nặng sẽ khiến GHTK tính sai phí.

PHP

add_filter( 'devvn_ghtk_data_before_shipment_fee', function ( $data ) {
    if ( empty( $data['weight'] ) ) {
        $data['weight'] = 500;   // gram
    }
    return $data;
} );

Luôn tích sẵn "Cho xem hàng" và "Đồng kiểm"

PHP

add_filter( 'devvn_ghtk_tags_default', function () {
    return array( 10, 11 );
} );

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

PHP

add_filter( 'devvn_ghtk_shipping_fee', function ( $fee, $method_id ) {
    return $fee + 5000;
}, 10, 2 );

Bật hình thức giao nhanh xFast

PHP

add_filter( 'devvn_ghtk_shipping_methob', function ( $methods ) {
    $methods['xteam'] = 'Giao nhanh xFast 2h';
    return $methods;
} );

Gửi thông báo riêng sau khi đăng đơn thành công

PHP

add_action( 'after_up_order_to_ghtk', function ( $order, $order_ghtk ) {
    $label = isset( $order_ghtk['order']['label_id'] ) ? $order_ghtk['order']['label_id'] : '';
    if ( $label ) {
        error_log( 'Đơn ' . $order->get_id() . ' có mã vận đơn ' . $label );
    }
}, 10, 2 );

Bật ghi log để tìm lỗi

PHP

add_filter( 'devvn_ghtk_debug', '__return_true' );

Log ghi vào WooCommerce → Trạng thái → Nhật ký. Nhớ tắt khi xong.

Thử trên bản sao trước khi dùng thật

Các hook nhóm đăng đơn tác động thẳng lên vận đơn thật và tiền thu hộ. Hãy bật Sandbox ở tab Cài đặt GHTK để thử, hoặc thử trên bản sao website trước khi đưa lên bản chính.

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