Kết nối Giao Hàng Nhanh (GHN)

Trang này nói riêng về Giao Hàng Nhanh (GHN): lấy tài khoản, kết nối, và những điều chỉ GHN mới có. Cơ chế chung cho mọi hãng — địa chỉ lấy hàng, phí rơi về mặc định khi hãng không trả lời kịp, gắn hãng vào một phương thức vận chuyển, trạng thái vận đơn đổi đơn hàng thế nào — đã có ở Ứng dụng Vận chuyển.

Kết nối GHN để làm gì

Kết nối GHN xong, cửa hàng có thêm bốn thứ: khách thấy đúng phí GHN báo ngay lúc đặt hàng (thay vì phí cố định đoán trước), bạn tạo vận đơn thẳng từ đơn hàng (Tạo vận đơn) không cần đăng nhập sang GHN, in nhãn vận đơn ngay tại đó (In vận đơn), và trạng thái đơn tự cập nhật mỗi khi GHN báo tin qua webhook — không phải tự tra cứu rồi gõ tay.

Lấy tài khoản GHN

GHN có hai môi trường khác hẳn nhau, mỗi nơi một tài khoản riêng:

Môi trường	Cổng	Dùng để làm gì
Thử nghiệm (sandbox)	5sao.ghn.dev	Thử kết nối, thử tạo vận đơn — không tốn tiền, không lấy hàng thật
Thật	khachhang.ghn.vn	Vận đơn thật, hãng thật sự đến lấy hàng

Token API và Shop ID của hai môi trường là hai cặp khác nhau — token thử không dùng được ở môi trường thật và ngược lại. Ô Token API trên thẻ GHN ghi rõ:

"Vào GHN Khách hàng → Chủ cửa hàng → Xem để lấy Token API."

Và ô Mã cửa hàng (Shop ID):

"Vào GHN Khách hàng → Quản lý cửa hàng để xem ID cửa hàng."

Nên khai luôn địa chỉ cửa hàng trong tài khoản GHN đó — đây thường là địa chỉ gắn với tài khoản lúc đăng ký, khác với địa chỉ lấy hàng bạn điền lại trong Store Builder (xem Ứng dụng Vận chuyển §Địa chỉ lấy hàng), vì Store Builder gọi API của GHN bằng Token + Shop ID chứ không đọc địa chỉ đăng ký từ phía GHN.

Kết nối trong ứng dụng Vận chuyển

Quản lý → Ứng dụng → Tích hợp sẵn → Vận chuyển, mở thẻ Giao Hàng Nhanh (GHN). Thẻ chia ba mục: Tài khoản kết nối, Địa chỉ lấy hàng, Webhook.

Kiểm tra kết nối thử đúng những giá trị bạn đang gõ trên thẻ, ngay cả khi chưa bấm Lưu — không có gì được lưu chỉ vì bạn bấm nó. Ô Token API để trống thì nó dùng token đã lưu trước đó. Nhờ vậy bạn kiểm tra được cặp Token + Shop ID trước, rồi mới lưu. Nếu công tắc Bật đơn vị vận chuyển này đang bật, Lưu chỉ thành công khi đã có Token API, Mã cửa hàng (Shop ID), Tỉnh / thành lấy hàng và Phường / xã lấy hàng — thiếu một ô thì không có gì được lưu. Vì vậy địa chỉ lấy hàng để sau bước kiểm tra. Thứ tự:

1. Bật Chế độ thử nghiệm (sandbox) nếu bạn đang dùng token thử — ô này ghi rõ "Dùng môi trường thử của đơn vị vận chuyển — không tạo đơn lấy hàng thật."

2. Dán Token API và Mã cửa hàng (Shop ID) đúng cặp của môi trường vừa chọn. Ô Token API là ô duy nhất không đọc lại được sau khi lưu — chỉ hiện •••• đã lưu; để trống khi lưu thì token cũ giữ nguyên.

3. Bấm Kiểm tra kết nối. Thẻ hỏi GHN bằng chính Token và Shop ID vừa gõ rồi báo tại chỗ. Token sai, hoặc token thuộc môi trường khác với công tắc sandbox đang chọn, báo:

   "Token hoặc mã shop không đúng — kiểm tra lại thông tin phía trên rồi thử lại."

   Token đúng nhưng Shop ID không thuộc tài khoản của token đó thì báo:

   "Mã cửa hàng (Shop ID) không thuộc tài khoản này — kiểm tra lại Shop ID trên trang khách hàng GHN."

   Cả hai trường hợp đều kèm một thông báo (toast) "Không kết nối được"; thành công thì báo "Đã kết nối".

4. Điền Địa chỉ lấy hàng và Khối lượng mặc định mỗi kiện — dùng chung cơ chế với mọi hãng khác, chi tiết từng ô ở Ứng dụng Vận chuyển.

5. Bật Bật đơn vị vận chuyển này, rồi bấm Lưu.

Nhãn Thử nghiệm cạnh badge Đã kết nối phản ánh trạng thái đã lưu, không đổi ngay khi bạn mới gạt công tắc sandbox — nó chỉ xuất hiện sau khi bấm Lưu với sandbox đang bật. Ngược lại, link Mở trang khách hàng luôn có mặt (không cần bật sandbox trước) và đổi đích ngay khi bạn gạt công tắc, kể cả trước khi lưu: 5sao.ghn.dev lúc công tắc sandbox đang bật, khachhang.ghn.vn lúc tắt. Riêng link Chưa có tài khoản? Đăng ký tài khoản thử chỉ hiện khi công tắc sandbox đang bật — GHN không có trang đăng ký thử riêng, nên link này cũng mở 5sao.ghn.dev; bạn tạo tài khoản thử ngay tại đó.

Webhook

Mục Webhook trên thẻ GHN giải thích rõ cách gắn webhook cho đúng hãng này:

"Gửi URL này cho bộ phận hỗ trợ của GHN để họ cấu hình webhook cho shop của bạn — nếu trang GHN của bạn có mục cài đặt webhook, bạn có thể dán URL vào đó."

Nghĩa là GHN không có chỗ tự đăng ký webhook được xác nhận sẵn trên mọi tài khoản — cách chắc ăn là bấm Hiện URL webhook (chỉ vai trò có quyền sửa cài đặt cửa hàng mới bấm được) rồi gửi URL đó cho bộ phận hỗ trợ GHN. Nếu tài khoản của bạn có sẵn ô webhook trong trang quản trị GHN thì dán thẳng vào đó cũng được. Tạo lại URL webhook phát hành URL mới và huỷ ngay URL cũ — nhớ báo lại cho GHN sau khi bấm.

Tính phí GHN trên một phương thức vận chuyển

Vào Cài đặt → Vận chuyển → Phương thức vận chuyển, mở một phương thức, đổi Nguồn phí từ Cố định / theo vùng sang Một đơn vị vận chuyển đã kết nối, chọn Giao Hàng Nhanh (GHN), rồi chọn Dịch vụ — để mặc định (Dịch vụ mặc định của đơn vị) hoặc chọn thẳng Hàng nhẹ (E-commerce), dịch vụ duy nhất GHN cung cấp trên nền tảng này hiện nay.

Từ đó, khách thấy đúng phí GHN báo ngay khi điền địa chỉ ở trang thanh toán — không phải một con số áng chừng rồi sửa lại sau. Ba trường hợp phí rơi về đúng phí cố định/theo vùng đã đặt cho phương thức đó:

• GHN không trả lời trong vòng 3 giây.
• GHN trả lời lỗi.
• GHN không dò được phường/xã của khách sang mã của GHN.

"Không bao giờ 0đ" chỉ đúng theo nghĩa: một báo giá của GHN trả về 0đ không có nghĩa gì, nên nền tảng không dùng nó — nó KHÔNG có nghĩa là phí cuối cùng luôn khác 0đ. Nếu bạn để phí cố định (ô Phí) của phương thức là 0đ, một lần rơi về fallback vẫn tính đúng 0đ — hộp thoại phương thức cảnh báo ngay khi gặp trường hợp này:

"Phí cố định của phương thức này đang là 0. Nếu đơn vị vận chuyển không báo được phí, đơn hàng sẽ được giao miễn phí."

Vì vậy hãy đặt phí cố định/theo vùng ở mức hợp lý cho phương thức này, coi nó là mức giá thay thế thật sự cho những lần GHN không kịp trả lời.

Miễn phí từ một mức tiền vẫn luôn thắng — đơn đã đạt ngưỡng thì không hỏi giá GHN nữa. Và lần đầu một phường/xã được hỏi giá, cửa hàng phải tra mã GHN cho phường/xã đó trước — nếu việc tra chưa xong trong 3 giây, đúng lần đó cũng rơi về phí cố định; các lần hỏi giá sau cho cùng phường/xã dùng lại kết quả đã tra nên gần như luôn ra đúng giá GHN.

Địa chỉ sau đợt sáp nhập 2025

GHN định giá theo tên phường/xã mới sau đợt sáp nhập hành chính 2025 — đúng danh sách tỉnh/phường mà biểu mẫu đặt hàng trên storefront dùng, nên phần lớn địa chỉ không cần bạn làm gì thêm. Nhưng có hai kiểu địa chỉ GHN từ chối, và cả hai đều không phải lỗi của cửa hàng:

Một số phường/xã GHN chưa nhận ra. Tính đến tháng 10/2026, ba phường/xã sau chưa có trong hệ thống GHN dù đã có trên nền tảng:

• Xã Đak Rong (Gia Lai)
• Phường Kỳ Lừa (Lạng Sơn)
• Xã Vụ Bổn (Đắk Lắk)

Đặt hàng giao tới một trong ba phường/xã này, hộp thoại tạo vận đơn báo lỗi và không tạo được vận đơn — chưa có cách nào tạo vận đơn GHN cho các phường/xã này lúc này. Câu báo lỗi luôn bằng ngôn ngữ bạn đang quản trị, gọi đúng tên phường/xã và tỉnh của đơn:

"{carrier} chưa hỗ trợ phường/xã {ward}, {province}."

({carrier} là tên hãng trên thẻ, {ward} và {province} được thay bằng địa chỉ thật của đơn.) Nếu địa chỉ giao hàng không dùng được mà không xác định được phường/xã nào, câu là "{carrier} chưa nhận được địa chỉ giao hàng này — kiểm tra lại phường/xã của đơn hàng." Còn khi lỗi nằm ở địa chỉ lấy hàng thì câu là "{carrier} chưa nhận được địa chỉ lấy hàng — kiểm tra phường/xã lấy hàng ở Ứng dụng → Vận chuyển."

GHN có thể từ chối một số nhà cụ thể trong một phường/xã nó vẫn nhận ra bình thường. Đo được trên môi trường thử nghiệm (sandbox) của GHN, ở Phường Hải Châu, Đà Nẵng: GHN từ chối "25 Bạch Đằng", "1 Bạch Đằng", "100 Bạch Đằng" nhưng chấp nhận "12 Bạch Đằng", "30 Bạch Đằng" — cùng một phường. Đây là cách GHN tự dò địa chỉ, không phải điều cửa hàng kiểm soát được; chưa được xác minh việc này có xảy ra ở môi trường thật hay không. Khi gặp, hộp thoại tạo vận đơn báo:

"Đơn vị vận chuyển từ chối yêu cầu: ghn: phường/xã người nhận không tồn tại trong hệ thống"

Phần trước dấu hai chấm ("Đơn vị vận chuyển từ chối yêu cầu:") là của Store Builder; phần sau là nguyên văn GHN trả về (tiền tố ghn: hơi kỹ thuật, nhưng đúng là những gì GHN gửi). Gặp lỗi này thì: kiểm tra lại con đường ghi trên đơn có thật sự thuộc phường/xã đã chọn không, thử đổi cách viết tên đường, rồi tạo lại; nếu vẫn báo lỗi sau khi đã kiểm tra, liên hệ bộ phận hỗ trợ GHN. Đừng bỏ hẳn số nhà khỏi địa chỉ — người giao hàng vẫn cần nó để tìm đúng nơi.

Tạo, in, huỷ vận đơn GHN từ một đơn hàng

Nút Tạo vận đơn chỉ hiện trên đơn hàng khi GHN (hoặc một hãng khác) đã kết nối và đang bật — chỉ lưu Token/Shop ID chưa đủ, công tắc Bật đơn vị vận chuyển này phải đang bật. Mở đơn hàng, bấm Tạo vận đơn, chọn GHN và dịch vụ, bấm Tạo vận đơn trong hộp thoại — vận đơn đi thẳng sang GHN, không qua bước duyệt nào khác. Cân nặng dùng để tính là tổng cân nặng các sản phẩm trong đơn (xem Ứng dụng Vận chuyển nếu đơn không có sản phẩm nào khai cân nặng); thu hộ (COD) gửi GHN đúng bằng số tiền đơn còn phải thu.

Vận đơn tạo xong, dòng kiện hàng hiện hai nút biểu tượng cạnh nhau (chỉ icon, có tooltip khi rê chuột, không có chữ): In vận đơn (biểu tượng máy in) mở cửa sổ in nhãn GHN ngay tại đó — trình duyệt chặn cửa sổ bật lên thì báo "Trình duyệt đã chặn cửa sổ in vận đơn. Vui lòng cho phép pop-up và thử lại." Nút này còn dùng được với mọi vận đơn chưa Đã huỷ hoặc Đã hoàn hàng.

Huỷ vận đơn (biểu tượng huỷ) gọi thẳng API huỷ của GHN — dùng được với mọi trạng thái trừ Đã giao và Đã huỷ; vận đơn đã Đã giao thì không còn nút này, vì GHN coi kiện đã xong, không huỷ ngược lại được nữa.

Link tra cứu của vận đơn GHN luôn trỏ về donhang.ghn.vn — kể cả vận đơn tạo ở chế độ thử nghiệm. Một vận đơn sandbox mở link đó có thể báo "không tìm thấy", vì trang tra cứu thật không biết gì về vận đơn thử; đây là giới hạn đã biết, không phải lỗi của cửa hàng.

Khắc phục sự cố

Gặp gì	Vì sao	Làm gì
"Token hoặc mã shop không đúng…" khi bấm Kiểm tra kết nối	Token gõ sai, hoặc token thuộc môi trường khác với công tắc sandbox đang bật/tắt	Dán lại đúng Token của đúng môi trường (thử hay thật) đang chọn
"Mã cửa hàng (Shop ID) không thuộc tài khoản này…" khi bấm Kiểm tra kết nối	Token đúng, nhưng Shop ID không nằm trong tài khoản của token đó (hoặc thuộc môi trường kia)	Xem lại Shop ID trong GHN Khách hàng → Quản lý cửa hàng, dán lại rồi kiểm tra tiếp
"Chưa thể ngắt kết nối … còn N vận đơn đang giao…" khi bấm Ngắt kết nối	GHN còn vận đơn chưa giao xong, chưa huỷ, chưa hoàn	Tắt công tắc Bật đơn vị vận chuyển này thay vì ngắt kết nối; ngắt kết nối sau khi các vận đơn đó xong
"…phường/xã người nhận không tồn tại trong hệ thống" khi tạo vận đơn	GHN từ chối đúng số nhà này trong địa chỉ, dù phường/xã hợp lệ	Kiểm tra con đường có thật sự thuộc phường/xã đã chọn không, hoặc đổi cách viết tên đường, rồi tạo lại — đừng bỏ số nhà
"… chưa hỗ trợ phường/xã …"	Phường/xã đó chưa có trong hệ thống GHN (ba phường/xã ở mục trên)	Chưa tạo được vận đơn GHN cho phường/xã này; ghi nhận kiện hàng thủ công thay thế
Phí thanh toán hiển thị đúng phí GHN, nhưng phí cố định cũng có thể xuất hiện ở đơn đầu tiên cho một phường/xã mới	Lần đầu hỏi giá phường/xã đó, cửa hàng chưa tra kịp mã GHN trong 3 giây	Bình thường — các đơn sau cho cùng phường/xã sẽ ra đúng giá GHN
Link tra cứu vận đơn báo "không tìm thấy"	Vận đơn tạo ở chế độ thử nghiệm, link tra cứu luôn trỏ môi trường thật	Đúng như thiết kế hiện tại; theo dõi vận đơn thử trong chính trang GHN sandbox
Cửa sổ In vận đơn không mở	Trình duyệt chặn pop-up	Cho phép pop-up cho trang này rồi bấm lại