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.0.3. Bộ hook gọn nhưng đủ để đổi phí ship, sửa dữ liệu trước khi tạo đơn 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_spx_order_created`	`$order`, `$data`	Ngay sau khi tạo vận đơn SPX thành công. `$data` chứa phản hồi của SPX, trong đó có mã vận đơn. Đây là hook chính để nối sang hệ thống khác.
`devvn_spx_order_cancelled`	`$order`, `$tracking`	Sau khi huỷ vận đơn thành công.
`devvn_spx_webhook_processed`	`$order`, `$data`	Sau khi plugin xử lý xong một lần webhook từ SPX. Dùng để ghi log riêng hoặc bắn thông báo nội bộ.
`devvn_spx_loaded`	không có	Plugin đã nạp xong. Móc vào đây khi code của bạn cần chắc chắn các lớp của SPX đã tồn tại.
`dvspx_license_changed`	`$valid` (bool)	Trạng thái license đổi giữa hợp lệ và không hợp lệ.
`dvspx_license_log`	`$message`	Mỗi dòng nhật ký của phần license.

Filter

Hook	Tham số	Dùng để
`devvn_spx_shipping_fee`	`$cost`, `$fee`, `$package`, `$method`	Đổi số tiền phí ship cuối cùng hiện cho khách. `$fee` là dữ liệu phí gốc SPX trả về, `$package` là giỏ hàng đang tính.
`devvn_spx_order_payload`	`$payload`, `$order`, `$args`	Sửa toàn bộ dữ liệu gửi lên SPX ngay trước khi tạo vận đơn. Hook mạnh nhất của plugin.
`devvn_spx_api_host`	`$host`, `$environment`	Đổi địa chỉ máy chủ API theo môi trường. Chỉ dùng khi SPX cấp cho bạn một điểm cuối riêng.

Hook của phần trang thanh toán

Tab Cài đặt chung của SPX là module dùng chung của mọi plugin vận chuyển DevVN, nên nó mang theo cả bộ hook riêng: trường checkout, cách tải dữ liệu địa chỉ, định dạng giá, tính cân nặng giỏ hàng. Danh sách đầy đủ nằm ở bài hook của plugin GHTK, mục Filter — trang thanh toán và địa chỉ — dùng được y hệt khi website chạy SPX.

Ví dụ hay dùng

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

PHP

add_filter( 'devvn_spx_shipping_fee', function ( $cost, $fee, $package, $method ) {
    return $cost + 5000;
}, 10, 4 );

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

PHP

add_filter( 'devvn_spx_shipping_fee', function ( $cost, $fee, $package, $method ) {
    $user = wp_get_current_user();
    if ( in_array( 'vip_customer', (array) $user->roles, true ) ) {
        return 0;
    }
    return $cost;
}, 10, 4 );

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

PHP

add_filter( 'devvn_spx_order_payload', function ( $payload, $order, $args ) {
    $payload['parcel_info']['item_name'] = 'Mỹ phẩm';
    return $payload;
}, 10, 3 );

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

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

PHP

add_action( 'devvn_spx_order_created', function ( $order, $data ) {
    $tracking = $order->get_meta( '_spx_tracking_no' );
    if ( $tracking ) {
        error_log( 'Đơn ' . $order->get_id() . ' có mã vận đơn ' . $tracking );
    }
}, 10, 2 );

Bắn thông báo nội bộ khi SPX báo đã giao

PHP

add_action( 'devvn_spx_webhook_processed', function ( $order, $data ) {
    $code = isset( $data['status_code'] ) ? (string) $data['status_code'] : '';
    if ( '4001' === $code ) {
        // 4001 = Đã giao hàng
        do_action( 'my_shop_order_delivered', $order );
    }
}, 10, 2 );

Dữ liệu plugin lưu trên đơn hàng

Đọc bằng $order->get_meta() khi bạn cần dùng lại trong code của mình:

Khoá	Nội dung
`_spx_tracking_no`	Mã vận đơn SPX
`_spx_tracking_link`	Liên kết tra cứu của SPX
`_spx_order_id`	Mã đơn trong hệ thống SPX
`_spx_status` · `_spx_status_code`	Trạng thái vận đơn dạng chữ và dạng mã
`_spx_fee`	Phí SPX ghi nhận cho đơn
`_spx_warehouse`	Kho gửi đã dùng
`_spx_created_at`	Thời điểm tạo vận đơn

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

Hai hook devvn_spx_shipping_fee và devvn_spx_order_payload tác động thẳng lên số tiền khách trả và lên vận đơn thật. Chuyển sang môi trường Test ở tab Kết nối API để thử, hoặc thử trên bản sao website.

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