Kết nối GHN với website: nền tảng, API hay plugin WooCommerce

Chào anh em! Shop có website mà gửi Giao Hàng Nhanh (GHN) thì kịch bản quen thuộc là: khách hỏi phí ship, mở khachhang.ghn.vn tra tay; có đơn thì chép tên, số điện thoại, địa chỉ sang GHN; giao xong lại quay về web đổi trạng thái đơn. Kết nối GHN với website là để bỏ mấy việc chép tay đó. Có ba đường: dùng nền tảng bán hàng có sẵn kết nối, tự code qua API của GHN, hoặc cài plugin nếu web chạy WordPress/WooCommerce. Đọc xong, anh em chọn được đường hợp với website của mình và biết phải chuẩn bị gì trước khi bắt tay làm.

Plugin ở cách 3 là sản phẩm mình viết và bảo trì, anh em nhớ điều đó khi so ba cách. Phần về GHN (API, token, webhook, tên mục trên khachhang.ghn.vn) mình lấy theo tài liệu chính thức tại developer.ghn.vn, các trang trên ghn.vn và giao diện khachhang.ghn.vn, kiểm lại vào tháng 10/2026. GHN đổi giao diện thì tên nút có thể lệch chút, anh em cứ theo ý các bước.

Kết nối GHN với website gồm những việc gì?

• Ở trang thanh toán, khách chọn địa chỉ xong thì website hỏi GHN rồi hiện cước theo khối lượng và tuyến, thay vì đồng giá cả nước.
• Website gửi người nhận, khối lượng, tiền thu hộ sang GHN để tạo vận đơn và nhận lại mã vận đơn, không phải gõ lại.
• Vận đơn in theo mẫu GHN (A5, 80 × 80, 52 × 70) để dán lên gói hàng.
• Mỗi khi vận đơn đổi trạng thái, GHN báo về website qua webhook, đơn giao xong tự chuyển sang hoàn thành.
• Website phải biết lấy hàng ở cửa hàng nào và gửi đúng tỉnh, phường/xã theo danh mục của GHN.

Chuẩn bị chung cho cả ba cách

• Tài khoản GHN đăng ký trên sso.ghn.vn bằng số điện thoại (hoặc Google, Apple) phải được xác thực. Tài khoản chưa xác thực chỉ lên được một số đơn dùng thử, nên xác thực xong rồi hãy chạy thật. Các bước chi tiết ở bài đăng ký tài khoản GHN.
• Token API do shop tự lấy trên khachhang.ghn.vn: bấm tên tài khoản ở góc trên bên trái → Thông tin tài khoản → tab Bảo mật → Token API & IP tin cậy → Quản lý, trang mở ra có ô Token API, bấm biểu tượng con mắt để xem (theo tài liệu GHN sẽ hỏi OTP). Tài liệu GHN còn mô tả cách lấy qua mục Quản lý token trên Developer Portal. Từng bước kèm ảnh có ở bài lấy token GHN.
• Cửa hàng (địa chỉ lấy hàng) khai ở mục Quản lý cửa hàng trên khachhang.ghn.vn. Một tài khoản có thể có nhiều cửa hàng, mỗi cửa hàng một mã ShopId.
• Từng sản phẩm phải có cân nặng (và kích thước nếu hàng cồng kềnh), vì sản phẩm để trống cân nặng là không ra phí.

⚠️ Dưới ô token có Danh sách IP được phép sử dụng, mặc định “Mọi IP đều có thể truy cập API”. Thêm IP tin cậy thì phải thêm cả IP máy chủ website, không thì website gọi API bị lỗi 401.

Cách 1: Dùng nền tảng bán hàng có sẵn kết nối GHN

Website chạy trên nền tảng bán hàng dựng sẵn thì trước khi nghĩ tới code, mở phần cài đặt vận chuyển (đối tác giao hàng) của nền tảng xem có GHN chưa. Mình không liệt kê tên nền tảng vì chưa đối chiếu hướng dẫn chính thức về GHN của từng bên; tìm chữ “GHN” trong trang trợ giúp của nền tảng là nhanh. Phần chuẩn bị vẫn như trên: tài khoản đã xác thực, token, cửa hàng lấy hàng khai đúng.

• Cách này hợp với shop đang bán trên chính nền tảng đó.
• Công sức bỏ ra ít vì nền tảng lo bảo trì; đổi lại bạn chỉ dùng được những gì nền tảng làm sẵn, và chuyển cả website sang nền tảng khác chỉ vì phần vận chuyển thì không đáng.

Cách 2: Tự code qua API GHN

Website tự viết (Laravel, PHP thuần, WordPress không dùng WooCommerce) hoặc cần nối thẳng phần mềm kho, ERP thì gọi API của GHN. Tài liệu chính thức nay ở developer.ghn.vn (đường dẫn tài liệu cũ trên api.ghn.vn không còn dùng). Có hai môi trường, hai tài khoản và hai token riêng: Production https://online-gateway.ghn.vn cho tài khoản khachhang.ghn.vn, Staging https://dev-online-gateway.ghn.vn cho tài khoản thử trên 5sao.ghn.dev, GHN ghi là “không phát sinh đơn thật”.

Mọi request gửi header Token, đa số API cần thêm ShopId; tiền tính bằng đồng, khối lượng gram, kích thước cm. Luồng tối thiểu:

Có thể bạn cần

Gửi Zalo ZNS bằng link API

Plugin GHN cho WooCommerce: kết nối Giao Hàng Nhanh, tính phí ship & in vận đơn

[Addon] Đăng đơn tự động/hàng loạt lên GHN

1. Lấy ShopId bằng GET /shiip/public-api/v2/shop/all, API này chỉ cần Token, trường _id của từng cửa hàng là ShopId.
2. Chọn bộ địa chỉ, vì từ 01/07/2025 GHN chạy song song địa chỉ cũ 3 cấp và mới 2 cấp (danh mục mới có 34 tỉnh/thành); lúc tạo đơn, trường is_new_to_address báo bạn gửi kiểu nào.
3. Để tính phí, API fee vẫn cần mã quận/huyện, mã phường/xã theo mô hình cũ; còn API Xem trước đơn (preview) nhận cùng dữ liệu như tạo đơn, trả phí và ngày giao dự kiến mà không tạo đơn.
4. Tạo đơn bằng v2/shipping-order/create với service_type_id (2 hàng nhẹ, 5 hàng nặng), payment_type_id (1 shop trả, 2 người nhận trả), required_note. Gửi kèm client_order_code: gọi lại cùng mã thì GHN trả đơn đã tạo thay vì tạo trùng. Lưu order_code trả về.
5. Huỷ đơn bằng v2/switch-status/cancel; muốn in thì gọi v2/a5/gen-token rồi mở link in A5, 80 × 80 hoặc 52 × 70 (token in sống khoảng 30 phút).
6. Để nhận trạng thái, khai webhook ở Developer Portal, mục Cấu hình webhook → tab Order, khoảng 15 phút sau thì có hiệu lực.

GHN gợi ý gọi thử ở staging trước rồi mới đổi sang production. Trong WordPress, bước gọi thử có thể đơn giản như sau (token để trong hằng số phía server):

// Gọi thử API GHN ở staging: lấy danh sách cửa hàng (ShopId) theo token.
define( 'DEVVN_GHN_API', 'https://dev-online-gateway.ghn.vn/shiip/public-api/' );
define( 'DEVVN_GHN_TOKEN', 'YOUR_TOKEN' );

function devvn_ghn_get_shops() {
	$response = wp_remote_get(
		DEVVN_GHN_API . 'v2/shop/all',
		array(
			'timeout' => 15,
			'headers' => array(
				'Token'        => DEVVN_GHN_TOKEN,
				'Content-Type' => 'application/json',
			),
		)
	);
	if ( is_wp_error( $response ) ) {
		return $response;
	}
	$body = json_decode( wp_remote_retrieve_body( $response ), true );
	if ( ! isset( $body['code'] ) || 200 !== (int) $body['code'] ) {
		return new WP_Error( 'devvn_ghn_error', isset( $body['message'] ) ? $body['message'] : 'GHN error' );
	}
	return isset( $body['data']['shops'] ) ? $body['data']['shops'] : array(); // Mỗi shop có _id = ShopId.
}

Code PHP cho tính phí, tạo đơn, huỷ, in, kèm các lỗi hay gặp, mình viết ở bài tích hợp API GHN. Phần nhận trạng thái đơn có bài riêng về webhook GHN.

• Cách này hợp với lập trình viên, hệ thống có luồng đơn riêng, hoặc khi chỉ cần một API lẻ như tính phí.
• Gọi được API thì không lâu, phần tốn công là mọi thứ xung quanh (ô địa chỉ khớp dữ liệu GHN, màn hình tạo đơn, in phiếu, webhook, đường lùi khi API chậm), tính bằng ngày tới tuần và còn sửa tiếp mỗi lần GHN đổi API.

Cách 3: Cài plugin GHN cho WooCommerce

Bốn bước bên dưới có trong video gần 3 phút này: lấy token, cấu hình, kiểm phí ship, tạo và in vận đơn.

Web chạy WooCommerce thì không phải viết lại những thứ ở cách 2. Mình lấy ví dụ plugin kết nối GHN với WooCommerce bản Pro của mình. Website cần WooCommerce 5.6 trở lên, PHP 7.2 tới 8.x, hosting bật ionCube Loader; ô tỉnh, phường/xã ở trang thanh toán có sẵn trong plugin. Kết nối gồm 4 bước.

Bước 1: Cài plugin, kích hoạt license, dán token

Tải file zip lên ở Plugin → Cài mới → Tải plugin lên, kích hoạt, rồi vào WooCommerce → Cài đặt GHN, tab License dán mã bản quyền; chưa kích hoạt thì tab Cài đặt GHN và Cửa hàng/Kho tự chuyển về tab License. Sang tab Cài đặt GHN: chọn Môi trường (Product cho tài khoản khachhang.ghn.vn, Test cho tài khoản 5sao.ghn.dev), dán token vào ô Token Key, chọn Ghi chú bắt buộc mặc định rồi lưu. Không có ô ShopId, plugin tự lấy cửa hàng theo token. Xem cài đặt plugin, license và kết nối API GHN.

Bước 2: Đồng bộ cửa hàng/kho từ GHN

Tab Cửa hàng/Kho, bấm Đồng bộ kho hàng từ GHN để kéo về các cửa hàng đã khai trên khachhang.ghn.vn; ra được kho nghĩa là token đúng. Plugin chỉ đồng bộ và hiển thị kho, thêm hay sửa kho thì làm trên khachhang.ghn.vn rồi bấm đồng bộ lại. Tích Đặt làm kho chính (lưu ngay). Có nhiều kho thì mở Khu vực bán hàng ở từng thẻ kho, chọn các tỉnh kho đó phụ trách rồi bấm Lưu trong popup; tỉnh không kho nào phụ trách thì dùng kho chính. Xem cửa hàng và kho gửi hàng.

Bước 3: Cân nặng, địa chỉ 2 cấp và phí ở trang thanh toán

• Khai cân nặng (và kích thước) cho sản phẩm, vì plugin không đặt cân nặng mặc định. Plugin gửi khối lượng và kích thước gói, GHN tự quy đổi.
• Khi mới cài, plugin dùng bộ địa chỉ 3 cấp cũ (“v2.0 – trước 01.07.2025”). Muốn dùng địa chỉ 2 cấp (Tỉnh, Phường/Xã) theo đơn vị hành chính mới thì vào tab Cài đặt chung, mục Cập nhật dữ liệu địa chỉ, chọn ô ngoài cùng bên trái ở dòng Đơn vị hành chính rồi bấm Cập nhật database. Trang thanh toán dạng khối (Checkout Block) chỉ chạy ở chế độ 2 cấp.
• Không cần thêm GHN vào khu vực giao hàng, vì ở WooCommerce → Cài đặt → Vận chuyển chỉ có ô Kích hoạt (bật sẵn) và Tiêu đề; ở trang thanh toán khách thấy tên gói GHN, còn Tiêu đề không hiện.

Xong bước này, khách chọn tỉnh, phường/xã là thấy phí GHN: một dòng gói có phí thấp hơn (mặc định) hoặc cả hai gói Hàng nhẹ, Hàng nặng. Đơn COD được khai giá theo giỏ hàng nên phí có thể cao hơn đơn chuyển khoản. GHN không trả được giá thì hiện dòng “Phí vận chuyển sẽ báo sau.” với 0đ, khách vẫn đặt được hàng. Xem trang thanh toán và địa chỉ.

Bước 4: Khai webhook để trạng thái tự về

Tab Cập nhật trạng thái tự động có sẵn đường dẫn webhook dạng …/admin-ajax.php?action=devvn_ghn_webhook&hash=…, chỉ có hiệu lực sau khi bấm Lưu thay đổi; bấm “Làm mới Webhook URL” thì nhớ khai lại đường dẫn mới. Trang ghi “Hãy gửi url bên dưới cho GHN để họ cấu hình Webhook nhé”. Theo tài liệu GHN tháng 10/2026, bạn dán đường dẫn này vào mục Cấu hình webhook trên Developer Portal của GHN (tab Order, bấm Tạo webhook, khoảng 15 phút có hiệu lực); nếu tài khoản chưa thấy mục này thì gửi đường dẫn cho GHN qua CSKH để được khai giúp.

Mẫu website nổi bật của tôi

Mẫu website bán trái cây, thực phẩm tươi

Mẫu website cửa hàng kính mắt

Mẫu website bán vật tư kim khí

Mẫu website bánh kem mới nhất

Có webhook, GHN báo huỷ thì đơn WooCommerce chuyển sang Đã huỷ và mã vận đơn được xoá; giao thành công thì chuyển sang Hoàn thành. Trạng thái khác chỉ cập nhật dòng Trạng thái trong hộp GHN của đơn. Xem webhook cập nhật trạng thái.

Kết nối xong, hằng ngày làm gì?

Có đơn thì bấm Tạo vận đơn GHN ngay trong danh sách đơn hoặc trong hộp GHN ở trang sửa đơn. Hộp thoại điền sẵn kho, khối lượng, kích thước, ca lấy hàng, người thanh toán, tiền thu hộ, gói cước kèm giá; kiểm lại rồi bấm Tạo đơn hàng là có mã vận đơn, in phiếu khổ A5, 52 × 70 mm hoặc 80 × 80 mm ngay trong đơn. Xem tạo vận đơn.

Hai lưu ý. Một, tiền thu hộ mặc định bằng tổng đơn gồm phí ship; chọn Người nhận trả phí thì tự sửa ô Tiền thu hộ bớt phần phí ship. Hai, plugin chính không tự đẩy đơn mới sang GHN và không đăng hàng loạt; hai việc đó cần addon đăng đơn tự động/hàng loạt, mua thêm, license riêng.

• Cách này hợp với chủ shop bán bằng WooCommerce, dev hoặc agency làm web cho khách cần chạy ngay.
• Cần hosting có ionCube Loader, tài khoản GHN có token, license plugin.
• Công sức gồm 4 bước trên, cộng việc cập nhật plugin mỗi khi GHN đổi API hay dữ liệu địa giới.

Bản plugin GHN miễn phí cũ

Trước đây mình có làm một bản plugin GHN miễn phí. Bản đó đã ngừng hỗ trợ và chỉ chạy trên PHP 7.x, nên website cần chạy tiếp lâu dài thì dùng bản Pro, chạy được PHP 7.2 tới 8.x. Hai bản dùng chung thư mục plugin nên không chạy song song: cài bản Pro thay cho bản cũ, kích hoạt license rồi làm lại 4 bước ở trên.

Nên chọn cách nào?

Lỗi hay gặp khi kết nối GHN

• Lỗi HTTP 401 là do thiếu header Token, hoặc đã bật danh sách IP tin cậy mà chưa thêm IP máy chủ website.
• Đồng bộ kho không ra gì thường do dán nhầm token Test vào môi trường Product (hay ngược lại), token sai, hoặc tài khoản chưa khai cửa hàng nào.
• Lỗi CLIENT_NOT_OWNER_OF_SHOP nghĩa là ShopId đang gửi không thuộc tài khoản của token, còn ROUTE_NOT_FOUND_SERVICE nghĩa là không có tuyến cho cặp địa chỉ với dịch vụ đã chọn.
• Trang thanh toán không hiện phí GHN khi license chưa kích hoạt hoặc không hợp lệ, chưa đồng bộ kho, sản phẩm thiếu cân nặng, ô Kích hoạt đang tắt, hoặc khách chưa chọn đủ địa chỉ.
• Đơn giao xong mà trạng thái không đổi thường do webhook chưa được khai hoặc chưa đủ 15 phút, quên bấm Lưu, vừa làm mới đường dẫn mà chưa khai lại, web chạy ở máy local, hoặc tường lửa chặn đường dẫn webhook.

Dùng plugin thì xem thêm trang hỏi đáp về plugin GHN.

Câu hỏi thường gặp

Có phải nhờ GHN cấp token không?

Không. Token nằm ngay trong tài khoản, tab Bảo mật → Token API & IP tin cậy, shop tự lấy. Việc nên làm trước là xác thực tài khoản để không bị giới hạn số đơn dùng thử.

Thử kết nối trước khi chạy thật được không?

Được. GHN có môi trường staging với tài khoản trên 5sao.ghn.dev và token riêng, GHN ghi là không phát sinh đơn thật. Trong plugin, chọn Môi trường là Test và dán token tài khoản thử; xong thì đổi về Product cùng token thật.

Anh em đang kết nối mà vướng chỗ nào cứ để lại bình luận, nhớ che token và số điện thoại trước khi dán ảnh nhé. Chúc anh em kết nối xong là khách chọn địa chỉ thấy ngay phí GHN ở trang thanh toán! 🚀