Kết nối API GHN

Plugin nói chuyện với GHN qua đúng một ô: Token Key. Không có ô ShopID — plugin tự lấy danh sách cửa hàng/kho theo token. Lấy token từ tài khoản GHN, dán vào, lưu lại, rồi đồng bộ kho để kiểm tra.

Kết nối Giao Hàng Nhanh (GHN) với WooCommerce trong 4 bước — Video bắt đầu ở 0:13: lấy Token API trên khachhang.ghn.vn, rồi dán Token Key và chọn môi trường trong tab Cài đặt GHN.

Mở tab Cài đặt GHN

Vào WooCommerce → Cài đặt GHN, tab Cài đặt GHN.

Tab Cài đặt GHN với lựa chọn môi trường, ô Token Key và ô Ghi chú bắt buộc — Token Key trong ảnh là giá trị mẫu. Bấm vào ảnh để phóng to.

Cài đặt GHN — tab thứ hai.
Môi trường — chọn một trong hai:
Product dùng tài khoản thật tại khachhang.ghn.vn. Đây là lựa chọn khi bán hàng thật, và là mặc định.
Test dùng tài khoản thử trên môi trường thử nghiệm của GHN (5sao.ghn.dev). Theo tài liệu GHN, gọi API ở môi trường này không phát sinh đơn thật. Liên kết in vận đơn cũng chuyển sang máy chủ thử.
Token Key — dán Token API lấy từ tài khoản GHN. Mỗi môi trường là một tài khoản riêng, token riêng: đừng dán token Test khi đang chọn Product và ngược lại.
Ghi chú bắt buộc — quy định shipper có cho khách xem hàng hay không: Cho xem hàng, không cho thử (mặc định) · Cho thử hàng · Không cho xem hàng. Đây là giá trị chọn sẵn cho mọi vận đơn; lúc tạo từng đơn vẫn đổi được.

Bấm Lưu thay đổi ở cuối trang.

Token Key là chìa khoá tài khoản GHN

Ai có token này là tạo và huỷ được vận đơn dưới tên tài khoản của bạn. Khi chụp màn hình nhờ hỗ trợ, che ô này lại; đừng dán token vào tin nhắn hay nhóm chat. Lỡ lộ thì vào tài khoản GHN đổi token rồi cập nhật vào đây.

Lấy Token Key ở đâu

Theo giao diện khachhang.ghn.vn tháng 10/2026 (GHN có thể đổi giao diện):

Đăng nhập khachhang.ghn.vn bằng tài khoản của cửa hàng, bấm vào tên tài khoản ở góc trên bên trái để mở trang Thông tin tài khoản. Liên kết "Lấy token key tại đây" dưới ô Token Key trong plugin dẫn tới khachhang.ghn.vn/account.
Chọn tab Bảo mật, tìm mục Token API & IP tin cậy và bấm Quản lý. Một trang mới của GHN mở ra.
Ô Token API đang hiện dạng dấu chấm. Bấm biểu tượng con mắt để xem; theo tài liệu GHN, hệ thống sẽ hỏi mã OTP gửi về số điện thoại của tài khoản.
Chép nguyên chuỗi token, đừng chép thừa dấu cách, rồi dán vào ô Token Key.

Cách thứ hai theo tài liệu GHN: đăng nhập Developer Portal của GHN, vào Quản lý token trong menu tài khoản.

Có khai danh sách IP tin cậy thì phải thêm IP máy chủ website

Ngay dưới ô Token API là Danh sách IP được phép sử dụng. Để trống thì mọi IP đều gọi được API. Nếu bạn thêm IP vào đây, phải thêm cả IP máy chủ đang chạy website (hỏi hosting nếu chưa biết) — không thì website gọi GHN bị từ chối, phí ship không hiện và không tạo được vận đơn.

Không cần thêm vào khu vực giao hàng

Phí GHN tự hiện ở trang thanh toán ngay khi kết nối xong. Bạn sẽ không thấy GHN trong danh sách Thêm phương thức vận chuyển của một khu vực giao hàng — đó là bình thường, không phải lỗi.

Muốn tắt hẳn việc tính phí GHN thì vào WooCommerce → Cài đặt → Vận chuyển → Giao hàng nhanh (GHN), bỏ tích Kích hoạt (mặc định đang bật). Ô Tiêu đề ở đó không hiện ra cho khách: khách thấy tên gói GHN như Hàng nhẹ, Hàng nặng. Muốn đổi tên gói thì dùng filter ghn_service_name ở bài Hook.

Cách kiểm tra đã nối được chưa

Lưu Token Key xong, sang tab Cửa hàng/Kho.
Bấm Đồng bộ kho hàng từ GHN — phải thấy cửa hàng của bạn hiện ra.
Không ra kho nào nghĩa là token sai, chưa lưu, hoặc đang chọn nhầm môi trường.

Lỗi thường gặp

Hiện tượng	Cách xử lý
Đồng bộ kho không ra gì	Token sai, chưa bấm Lưu thay đổi, hoặc đang chọn nhầm môi trường so với token đang dùng.
Phí ship không hiện dù token đúng	Chưa đồng bộ kho, sản phẩm chưa khai khối lượng, hoặc license không hợp lệ. Xem bảng lưu ý và License.
Đang chạy tốt bỗng lỗi xác thực	Token đã được đổi bên GHN, hoặc tài khoản GHN vừa thêm IP tin cậy mà chưa có IP máy chủ website. Dán token mới, hoặc thêm IP máy chủ vào danh sách.
Vận đơn "thử" lại thành đơn thật	Đang ở môi trường Product. Muốn thử thì đổi sang Test và dán token của tài khoản thử. Đơn thật lỡ tạo thì bấm Hủy đơn hàng trong ô GHN của đơn.

Tiếp theo: đồng bộ cửa hàng / kho.