Ứng dụng Vận chuyển

Quản lý → Ứng dụng → Tích hợp sẵn → Vận chuyển (en: Manage → Apps → Built in → Shipping). Bấm Cài đặt trên thẻ, rồi Quản lý để mở màn hình cấu hình.

"Kết nối Giao Hàng Nhanh hoặc Giao Hàng Tiết Kiệm để tính phí, tạo vận đơn và theo dõi đơn hàng"

Một thẻ mỗi hãng

Màn hình liệt kê từng hãng thành một thẻ có thể mở ra: hiện tại là Giao Hàng Nhanh (GHN) và Giao Hàng Tiết Kiệm (GHTK). Mỗi thẻ chia ba mục cố định — Tài khoản kết nối, Địa chỉ lấy hàng, Webhook — và mang đúng những ô hãng đó cần trong mục Tài khoản kết nối: GHN hỏi Token API và Mã cửa hàng (Shop ID); GHTK hỏi Token API và Mã shop — cùng badge Đã kết nối / Chưa kết nối và một link Tài liệu sang trang phát triển của chính hãng.

Trang này nói về cơ chế chung của cả hai hãng. Riêng về GHN — lấy tài khoản, kết nối, và những tình huống chỉ GHN mới có (địa chỉ sau sáp nhập, lỗi số nhà ở Hải Châu) — xem Kết nối Giao Hàng Nhanh (GHN).

Giao Hàng Tiết Kiệm (GHTK) đang được hoàn thiện trên nền tảng này — thẻ GHTK đã có sẵn, nhưng việc kết nối và tạo vận đơn qua GHTK chưa được xác minh đầy đủ với tài khoản thật. Nếu bạn muốn chuẩn bị trước, có thể đăng ký tài khoản thử GHTK ngay bây giờ.

Lấy token GHN

Vào tài khoản GHN của bạn (chi tiết đầy đủ, gồm sandbox vs. thật, ở Kết nối Giao Hàng Nhanh (GHN)):

Ô	Lấy ở đâu
Token API	"Vào GHN Khách hàng → Chủ cửa hàng → Xem để lấy Token API."
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."

Lấy token GHTK

Đang hoàn thiện. Kết nối GHTK chưa được xác minh đầy đủ với tài khoản thật — bảng dưới đây là các ô trên thẻ, để bạn chuẩn bị trước bằng tài khoản thử GHTK.

Ô	Lấy ở đâu
Token API	"Vào Thông tin shop → Cấu hình API trên trang GHTK rồi chọn "Tạo Token"."
Mã shop	"Mã shop của bạn trên GHTK — xem tại Thông tin shop → Tài khoản."

Ô Token API là ô duy nhất không đọc lại được sau khi lưu — giống hệt cổng thanh toán: lưu rồi thì ô chỉ báo đã có khoá, đổi thì gõ đè, giữ nguyên thì để trống khi lưu. Shop ID và Mã shop đọc lại bình thường, vì chúng vốn không phải bí mật.

Chế độ thử nghiệm (sandbox)

Chế độ thử nghiệm (sandbox) — "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." Bật lên thì mọi báo giá và vận đơn của thẻ đó đi vào cổng dev của hãng thay vì cổng chính thức. Hãy thử ở đây trước khi bật thật. Với GHN, Kiểm tra kết nối đã xác nhận token, môi trường (thử hay thật) và Shop ID; một vận đơn thử đầu tiên còn chứng minh thêm địa chỉ lấy hàng và địa chỉ giao hàng được hãng chấp nhận.

Nhãn Thử nghiệm cạnh badge Đã kết nối cho biết đang ở môi trường nào mà không cần mở thẻ — nhưng nó 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ên chỉ xuất hiện sau khi bấm Lưu với sandbox đang bật. Link Mở trang khách hàng thì khác: luôn có mặt kể cả khi sandbox đang tắt, và đổi đích ngay khi bạn gạt công tắc, trước cả khi lưu — cổng thử của hãng lúc công tắc đang bật, cổng chính thức lúc tắt. Riêng link Chưa có tài khoản? Đăng ký tài khoản thử mới thật sự phụ thuộc công tắc — chỉ hiện khi sandbox đang bật, và có hay không tuỳ hãng có cổng đăng ký thử riêng: GHTK có (khachhang-staging.ghtklab.com/web/dang-ky), còn GHN thì không, nên link của GHN mở thẳng 5sao.ghn.dev để bạn tạo tài khoản thử ngay tại đó.

Địa chỉ lấy hàng

Mỗi thẻ giữ địa chỉ lấy hàng của riêng nó — không dùng chung địa chỉ cửa hàng ở Cài đặt → Địa chỉ, vì đó là nơi hãng vận chuyển thật sự đến lấy kiện, có thể khác kho ghi trên giấy tờ. Cần điền: Tên người gửi hàng, Số điện thoại lấy hàng, Địa chỉ lấy hàng (số nhà, đường), rồi Tỉnh / thành lấy hàng và Phường / xã lấy hàng — hai ô chọn dùng đúng danh sách hành chính hai cấp (tỉnh → phường, sau đợt sáp nhập) mà biểu mẫu đặt hàng trên storefront cũng dùng. Chưa chọn tỉnh thì ô phường bị khoá.

Khối lượng mặc định mỗi kiện đứng ngay dưới đó — dùng khi một đơn không có sản phẩm nào ghi cân nặng (xem phần Cân nặng bên dưới).

Kiểm tra kết nối

Kiểm tra kết nối thử đúng những giá trị bạn đang gõ trên thẻ, kể cả khi chưa bấm Lưu — nó không lưu gì cả. Ô Token API để trống thì dùng token đã lưu. Nhờ vậy bạn kiểm tra token và Shop ID/Mã shop trước rồi mới điền địa chỉ lấy hàng, bật hãng và Lưu. Với GHN, kiểm tra còn xác minh Shop ID có thuộc tài khoản của token không (chi tiết ở Kết nối Giao Hàng Nhanh (GHN)).

Kết quả báo ngay tại chỗ chứ không bắt bạn phải thử tạo một vận đơn thật mới biết. Bất kỳ lỗi nào cũng hiện một thông báo (toast) tiêu đề "Không kết nối được". Riêng hai lỗi dưới đây còn hiện thêm câu cụ thể ở khu vực kết quả dưới nút. Hãng từ chối vì token sai — kể cả khi bạn dán nhầm token của môi trường kia (sandbox/thật):

"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 của GHN không thuộc tài khoản đó:

"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."

Mọi lỗi khác hiện nguyên văn thông báo kỹ thuật (thường bằng tiếng Anh), kèm lý do của hãng nếu hãng có trả về — bất kể bạn đang quản trị cửa hàng bằng ngôn ngữ nào, vì đó không qua bản dịch của Store Builder.

URL webhook

Mục Webhook trên mỗi thẻ đã ghi rõ cách gắn đúng của hãng đó — cách làm khác nhau giữa hai hãng, nên đọc đúng thẻ bạn đang dùng là đủ:

GHN: "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 đó." (chi tiết ở Kết nối Giao Hàng Nhanh (GHN))

GHTK: "GHTK chưa hỗ trợ tự đăng ký webhook — hãy gửi URL này cho bộ phận hỗ trợ của GHTK để họ gắn vào shop của bạn."

Cơ chế chung phía sau cả hai: hãng vận chuyển gọi ngược về cửa hàng khi trạng thái của một vận đơn đổi — lấy hàng xong, đang giao, đã giao. Địa chỉ đó không hiện sẵn trên danh sách: nút Hiện URL webhook phải được bấm mỗi lần bạn cần nó, vì đoạn cuối của URL chính là chuỗi bí mật xác thực lệnh gọi đó — hiện sẵn trong danh sách nghĩa là bất kỳ ai xem được màn hình (kể cả một vai trò chỉ-xem) cũng đọc được chuỗi bí mật đó. Chỉ vai trò có quyền sửa cài đặt cửa hàng mới bấm được Hiện URL webhook.

Gửi URL đó theo đúng cách mục Webhook trên thẻ hãng đó đã ghi — mỗi hãng một địa chỉ riêng, vì mỗi hãng xác thực bằng chuỗi bí mật của thẻ đó. Thiếu bước này thì vận đơn vẫn tạo được, nhưng trạng thái giao hàng không bao giờ tự cập nhật — bạn phải tự vào tra cứu bên hãng và cập nhật tay.

Tạo lại URL webhook phát hành một chuỗi bí mật mới cho hãng đó. "URL cũ ngừng hoạt động ngay lập tức." Vì vậy hãy cập nhật URL mới sang trang quản trị của hãng ngay sau khi bấm — mọi sự kiện hãng gửi vào URL cũ, kể cả những sự kiện đang trên đường, sẽ bị từ chối.

Gắn một phương thức vận chuyển với hãng

Phương thức vận chuyển (Cài đặt → Vận chuyển → Phương thức vận chuyển) có ô Nguồn phí: Cố định / theo vùng (như trước giờ) hoặc Một đơn vị vận chuyển đã kết nối. Chọn một hãng thì hiện thêm ô Dịch vụ — Dịch vụ mặc định của đơn vị hoặc một dịch vụ cụ thể của hãng đó (GHN: Hàng nhẹ (E-commerce); GHTK: Đường bộ, Đường bay, XFAST). Ô này bị khoá và kèm gợi ý "Hãy kết nối một đơn vị vận chuyển ở Ứng dụng → Vận chuyển để tính phí qua đơn vị đó." nếu cửa hàng chưa có hãng nào vừa kết nối vừa đang bật.

Đổi nguồn phí không đổi tên phương thức khách nhìn thấy trên biểu mẫu đặt hàng — chỉ đổi phí được tính ra bằng cách nào.

Khi hãng không trả lời được kịp

Mỗi lần checkout hỏi giá một phương thức gắn hãng, cửa hàng chờ hãng tối đa 3 giây. Hãng trả lời chậm hơn, trả lời lỗi, hoặc không dò được địa chỉ phường/xã của khách sang mã của hãng, thì phí tính lại theo đúng phí cố định/theo vùng đã đặt cho phương thức đó, và khách vẫn đặt được hàng bình thường. Một báo giá của hãng bằng đúng 0đ bị coi là vô nghĩa nên nền tảng bỏ qua nó — điều đó không có nghĩa là phí cuối cùng luôn khác 0đ; phí fallback thì bằng đúng phí cố định/theo vùng bạn đã đặt, kể cả khi bạn đặt phí đó là 0đ. Hộp thoại phương thức cảnh báo ngay khi phí cố định của một phương thức tính phí qua hãng đang là 0:

"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í."

Hãy đặt một phí thay thế hợp lý. Mỗi lần rơi về phí cố định đều được ghi log ở phía máy chủ.

Miễn phí từ một mức tiền vẫn thắng tuyệt đối: một đơn đã đạt ngưỡng miễn phí thì không hãng nào được hỏi giá nữa, kể cả khi phương thức đó gắn hãng.

Tạo vận đơn từ một đơn hàng

Mở một đơn hàng: nếu cửa hàng có ít nhất một hãng đã 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 trên thẻ hãng đó phải đang bật), nút Tạo vận đơn hiện cạnh nút ghi nhận kiện hàng thủ công. Bấm vào mở hộp thoại Tạo vận đơn: "Chọn một đơn vị vận chuyển đã kết nối và dịch vụ của họ — vận đơn được tạo trực tiếp qua API." Chọn Đơn vị vận chuyển (hộp chọn tự chọn sẵn hãng đầu tiên đang kết nối) và Dịch vụ (hoặc để mặc định), bấm Tạo vận đơn — vận đơn đi thẳng sang hãng, không qua bước duyệt nào khác.

Tạo xong, dòng kiện hàng của đơn hiện thêm mã vận đơn, link tra cứu (donhang.ghn.vn với GHN — link tra cứu của GHTK chưa được xác minh, vì GHTK vẫn đang hoàn thiện), phí vận chuyển hãng báo, thu hộ (COD) nếu đơn thanh toán khi nhận hàng, và trạng thái hãng ngay lúc đó (thường là Chờ lấy hàng).

Cân nặng dùng để tính

Vận đơn dùng tổng cân nặng các sản phẩm trong đơn (đã nhân số lượng từng dòng) — chính là cân nặng bạn khai ở từng biến thể sản phẩm, không phải một con số nhập tay lúc tạo vận đơn. Đơn không có sản phẩm nào khai cân nặng thì dùng Khối lượng mặc định mỗi kiện đã đặt trên thẻ kết nối của hãng đó.

Thu hộ (COD)

Đơn thanh toán khi nhận hàng thì COD gửi cho hãng đúng bằng tổng tiền đơn còn phải thu — không phải toàn bộ giá trị đơn nếu khách đã trả trước một phần. Đơn thanh toán qua cổng khác thì COD gửi 0đ.

In vận đơn

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ữ): nút In vận đơn mở nhãn vận đơn của hãng ngay tại đó — không cần đăng nhập sang trang hãng. 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 dùng được với mọi vận đơn chưa Đã huỷ hoặc Đã hoàn hàng.

Huỷ vận đơn

Vận đơn còn có thể huỷ ở phía hãng thì nút Huỷ vận đơn (biểu tượng, cạnh nút In vận đơn) hiện cạnh dòng đó — với mọi trạng thái trừ Đã giao và Đã huỷ, kể cả Giao thất bại và Đã hoàn hàng vẫn còn nút này, vì hãng có thể còn giữ kiện chưa xử lý xong. Hộp thoại xác nhận hỏi:

"“{tracking}” sẽ được huỷ với đơn vị vận chuyển. Không thể hoàn tác."

({tracking} được thay bằng đúng mã vận đơn của kiện hàng đó) — xác nhận thì gọi thẳng API huỷ của hãng, đưa vận đơn sang Đã huỷ và đơn hàng về Chưa xử lý.

Trạng thái hãng làm gì với đơn hàng

Đơn hàng mang hai ô trạng thái riêng biệt: Trạng thái đơn hàng (Chờ xử lý / Đã xác nhận / Đang giao / Đã giao / Đã hủy) và Xử lý đơn (Chưa xử lý / Một phần / Đã hoàn tất) — cái sau nói kiện hàng đã rời kho hay chưa, không phải khách đã trả tiền chưa. Mỗi lần hãng báo trạng thái vận đơn mới qua webhook, chỉ hai ô này đổi, và chỉ đổi ở đúng bốn mốc:

Trạng thái vận đơn (badge)	Đơn hàng đổi thành
Vừa tạo vận đơn (Chờ lấy hàng)	Xử lý đơn → Đã hoàn tất
Đang giao	Trạng thái đơn hàng → Đang giao
Đã giao	Trạng thái đơn hàng → Đã giao (Xử lý đơn giữ nguyên Đã hoàn tất)
Đã huỷ	Xử lý đơn → Chưa xử lý
Giao thất bại / Đã hoàn hàng	Chỉ vận đơn đổi — đơn hàng giữ nguyên, bạn tự quyết bước tiếp theo

Một đơn hàng đã ở Trạng thái đơn hàng Đã giao hoặc Đã hủy không bao giờ bị một sự kiện đến muộn kéo lùi lại. Và nếu bạn huỷ một vận đơn rồi tạo một vận đơn mới thay cho nó, vận đơn cũ vẫn có thể báo thêm sự kiện muộn — nhưng vì nó không còn là vận đơn đang hoạt động của đơn này, sự kiện đó không còn đường nào chạm vào đơn hàng nữa.

Kiện hàng ghi thủ công (gõ tay tên hãng ở nút Ghi nhận kiện hàng, không chọn từ danh sách đã kết nối) vẫn giữ nguyên hành vi cũ: không hãng nào báo trạng thái về, nên không gì tự đổi Xử lý đơn — bạn vẫn tự cập nhật như trước giờ.

Giới hạn hiện tại

Vài điều nên biết trước, để không mất công đi tìm một tính năng không có:

• GHN mới chỉ dùng dịch vụ Hàng nhẹ (E-commerce). Dịch vụ hàng nặng của GHN cần khai kích thước từng sản phẩm, thứ nền tảng chưa thu thập — sẽ mở khi có.
• Kích thước kiện hàng gửi lên hãng là một mức mặc định, không tính từ kích thước thật của sản phẩm trong đơn — chỉ cân nặng là số thật.
• Báo giá lần đầu cho một phường/xã mới có thể tạm dùng phí cố định. Lần đầu một địa chỉ được hỏi giá, cửa hàng phải tra mã của hãng cho đúng phường/xã đó; nếu việc tra cứu chưa xong trong 3 giây, giá lần đó rơi về phí cố định của phương thức. Những 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 giá thật của hãng.

Ngắt kết nối một hãng

Nút Ngắt kết nối trên mỗi thẻ đã kết nối xoá hẳn token, Shop ID/Mã shop và địa chỉ lấy hàng đã lưu: "Thông tin đăng nhập và địa chỉ lấy hàng sẽ bị xoá. Các phương thức tính phí qua đơn vị này quay về phí cố định." Mọi phương thức đang gắn hãng đó lập tức tính phí cố định/theo vùng của chính nó.

Vì đây là xoá, không phải chỉ tắt, nó ảnh hưởng cả những vận đơn đã tạo trước đó: nút In vận đơn và Huỷ vận đơn trên các vận đơn cũ của hãng đó không còn dùng được nữa (không còn thông tin kết nối để gọi API hãng), và hãng gửi sự kiện cập nhật trạng thái tới URL webhook cũ cũng bị từ chối — trạng thái các vận đơn đó ngừng tự cập nhật. Kết nối lại từ đầu còn phát hành một URL webhook mới, phải gửi lại cho hãng đăng ký lần nữa. Nếu vẫn còn kiện hàng đang trên đường, tắt công tắc Bật đơn vị vận chuyển này trên thẻ đó thay vì bấm Ngắt kết nối — một kết nối bị tắt (chứ chưa xoá) vẫn cho In vận đơn, Huỷ vận đơn, và vẫn nhận được cập nhật trạng thái qua webhook bình thường; nó chỉ ngừng được chọn cho vận đơn mới.

Vì vậy Ngắt kết nối bị từ chối chừng nào hãng đó còn vận đơn đang giao (chưa giao, chưa huỷ, chưa hoàn). Hộp thoại xác nhận vẫn mở và hiện lý do, kèm số vận đơn:

"Chưa thể ngắt kết nối {carrier}: còn {count} vận đơn đang giao. Hãy tắt {carrier} thay vì ngắt kết nối — vận đơn đang giao vẫn in nhãn, huỷ và nhận cập nhật được."

Một lần từ chối không kèm số đếm thì dùng câu ngắn hơn: "Chưa thể ngắt kết nối {carrier}: vẫn còn vận đơn đang giao. Hãy tắt {carrier} thay vì ngắt kết nối — …". Nếu chính bước kiểm tra này gặp lỗi, Ngắt kết nối cũng bị từ chối: hiện thông báo "Không ngắt kết nối được đơn vị này" và không có gì bị xoá. Hết vận đơn đang giao thì Ngắt kết nối chạy như mô tả trên: xoá token, Shop ID/Mã shop và địa chỉ lấy hàng đã lưu.

Gỡ cả ứng dụng Vận chuyển bị chặn chừng nào còn ít nhất một hãng đang bật (Bật đơn vị vận chuyển này) — cùng lý do ứng dụng Thanh toán chặn gỡ khi còn cổng đang bật: một ứng dụng "đã gỡ" mà một kết nối của nó vẫn đang hoạt động là trạng thái không được phép tồn tại. Bấm gỡ khi còn hãng đang bật thì báo:

"Hãy tắt hết các đơn vị vận chuyển trước — đơn hàng vẫn đang được tạo vận đơn qua đó."

Chỉ cần tắt công tắc trên từng thẻ — không cần bấm Ngắt kết nối. Tắt hết rồi mới gỡ được ứng dụng.