🌐 Ngôn ngữ: 🇻🇳 Tiếng Việt (hiện tại) · 🇬🇧 English

Giao Hàng Nhanh (GHN) cho GP247 / S-Cart

Giới thiệu

Plugin miễn phí kết nối cửa hàng GP247 / S-Cart với Giao Hàng Nhanh (GHN): khách thấy phí GHN thật ở bước thanh toán, còn bạn tạo vận đơn, in nhãn, huỷ và theo dõi đơn ngay trong trang quản trị. Tài liệu viết cho chủ cửa hàng và người quản trị, không cần biết lập trình. Đọc xong, bạn tự đăng ký tài khoản GHN, lấy Token và ShopId, cấu hình plugin và gửi được đơn đầu tiên.

Plugin chạy trên lớp vận chuyển chuẩn của gp247/shop (từ bản có "Vận chuyển chuẩn ngành").

Plugin làm được gì

Toàn bộ các bước cài đặt:

flowchart LR
    subgraph GHN["Trên trang GHN"]
        direction TB
        A["Đăng ký tài khoản"] --> B["Lấy Token"]
        B --> C["Xem ShopId"]
    end
    subgraph ADMIN["Trong GP247 admin"]
        direction TB
        D["Cài và kích hoạt plugin"] --> E["Nhập Token và ShopId"]
        E --> F["Khai kho lấy hàng và địa chỉ khách"]
        F --> G["Dán URL webhook vào GHN"]
    end
    GHN --> ADMIN
    ADMIN --> H["Thử một đơn rồi chuyển sang môi trường thật"]

Phần 1 — Đăng ký GHN và lấy Token, ShopId

GHN có hai môi trường tách biệt hoàn toàn: tài khoản, Token, ShopId và cấu hình webhook của môi trường này không dùng được ở môi trường kia.

1.1. Lấy Token

Làm lần lượt trên trang của môi trường bạn muốn dùng (nên làm staging trước):

1. Mở trang dành cho nhà phát triển (bảng trên), bấm Đăng nhập ở góc phải trên cùng.

2. Nhập số điện thoại của bạn và làm bước xác minh. Có thể chọn đăng nhập bằng Google hoặc Apple. Với môi trường thật, dùng số điện thoại của tài khoản GHN mà cửa hàng đang gửi hàng.

3. Sau khi đăng nhập, mở menu tài khoản ở góc phải và chọn Quản lý token.

4. Ở thẻ Token API, bấm biểu tượng con mắt. GHN gửi một mã OTP 6 số tới điện thoại của bạn; nhập mã đó để hiện Token.

5. Bấm biểu tượng sao chép để chép Token.

   Token là một chuỗi dạng xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Giữ nó như mật khẩu: chỉ dán vào màn cấu hình GHN trong admin, không gửi qua chat hay email.

6. Để trống ô Danh sách IP được phép sử dụng nếu bạn không chắc IP của máy chủ web. Khi ô này có ít nhất một IP, GHN chặn mọi yêu cầu từ IP khác — kể cả máy chủ của bạn nếu nhập thiếu.

1.2. Tìm ShopId

ShopId là mã số của cửa hàng trên GHN (một tài khoản GHN có thể có nhiều cửa hàng). Bạn thấy nó trong thông tin tài khoản trên trang GHN.

• Tài khoản staging vừa đăng ký thường có sẵn một cửa hàng nhưng chưa có địa chỉ — không sao, plugin gửi kho lấy hàng của bạn cho GHN (xem Phần 3).
• Nếu không tìm thấy ShopId, cứ nhập Token vào màn cấu hình (Phần 2) và gõ tạm một số bất kỳ ở ô ShopId rồi lưu. Thông báo "ShopId không thuộc tài khoản của token này" nghĩa là Token đúng, chỉ còn ShopId sai.

Phần 2 — Cài và cấu hình plugin trong admin

2.1. Cài đặt

1. Vào Phần mở rộng → Tiện ích.

2. Tìm Giao Hàng Nhanh (GHN), bấm Cài đặt, rồi Kích hoạt.

   Nếu thành công, menu Cửa hàng → Phương thức vận chuyển có thêm mục GHN.

2.2. Màn cấu hình GHN

Mở Cửa hàng → Phương thức vận chuyển → GHN (hoặc bấm ⚙ cạnh plugin ở màn Tiện ích). Nếu bạn dùng nhiều cửa hàng, chọn cửa hàng ở đầu màn trước khi nhập.

Bấm Lưu. Hệ thống tự kiểm tra kết nối với GHN và báo một trong các kết quả:

Phần 3 — Cấu hình cửa hàng cho vận chuyển

Vào Quản lý hệ thống → Cấu hình website → Cấu hình cửa hàng.

3.1. Tab Vận chuyển

1. Bật Bật vận chuyển khi đặt hàng.

2. Điền khối Kho lấy hàng (địa chỉ người gửi) — GHN đến đây lấy hàng và tính phí từ đây:

   • Tên người gửi / tên cửa hàng và Số điện thoại (shipper gọi số này).
   • Tỉnh/Thành phố, Phường/Xã theo tên đơn vị hành chính mới (từ 01/07/2025). Ví dụ: TP. Hồ Chí Minh và Phường Sài Gòn.
   • Địa chỉ chi tiết: số nhà, tên đường. Ví dụ: 12 Lê Lợi.
   • Quận/Huyện: bỏ trống nếu địa phương đã bỏ cấp huyện.

   Plugin chỉ dùng kho này khi có đủ Tỉnh/Thành phố, Phường/Xã và Địa chỉ chi tiết. Thiếu một ô, GHN dùng địa chỉ cửa hàng khai trên GHN — nếu cửa hàng GHN cũng chưa có địa chỉ, GHN không báo phí.

3. Khối lượng mặc định mỗi sản phẩm (gram): dùng cho sản phẩm chưa nhập khối lượng.

4. Tự ghi tiền thu hộ (COD) vào đơn khi hãng báo đã đối soát: chỉ bật nếu bạn đối chiếu tiền COD theo báo cáo của GHN. Mỗi vận đơn chỉ được ghi một lần.

5. Bấm Lưu. Khung cảnh báo ở đầu tab phải không còn dòng nào về kho lấy hàng hay địa chỉ khách.

3.2. Tab Khách hàng

Bật ô Tỉnh/Thành phố và Phường/Xã (nên để bắt buộc) cho địa chỉ khách. Không có hai ô này, GHN không biết giao đến đâu và không báo phí ở trang thanh toán.

3.3. Tiền tệ

Cửa hàng phải có đồng VND trong danh sách tiền tệ (GHN tính phí bằng VND). Đơn bằng đồng khác được quy đổi theo tỷ giá bạn khai.

Phần 4 — Webhook: để trạng thái tự cập nhật

Không có webhook, plugin vẫn chạy: trạng thái được hỏi lại GHN khi bạn mở đơn hoặc bấm Đồng bộ. Webhook giúp trạng thái cập nhật ngay khi GHN đổi.

1. Trên màn cấu hình GHN, khối Cập nhật trạng thái tự động (webhook), chép URL webhook (dạng https://<tên-miền>/shipping/webhook/ShippingGHN?hash=...).
2. Trên trang dành cho nhà phát triển của GHN (cùng môi trường với Token), mở menu tài khoản → Cấu hình webhook → tab Đơn hàng.
3. Dán URL, bấm Tạo webhook. GHN cần khoảng 15 phút để áp dụng.
4. Khi chuyển sang môi trường thật, làm lại bước 2–3 trên developer.ghn.vn — cấu hình staging không tự chuyển sang.

⚠️ URL webhook chứa mã bí mật. Không đăng công khai. Nếu lỡ lộ: tick Tạo lại mã bí mật webhook khi lưu, bấm Lưu, rồi dán URL mới vào GHN. GHN phải gọi được tới trang của bạn qua Internet: tên miền nội bộ (localhost, *.local) không nhận được webhook.

Phần 5 — Dùng hằng ngày trong admin

5.1. Khách đặt hàng

Ở bước Vận chuyển, khách thấy GHN — Hàng nhẹ hoặc GHN — Hàng nặng với phí và ngày giao dự kiến. Phí này là phí GHN báo cho đúng giỏ hàng và địa chỉ đó; cửa hàng trả phí cho GHN.

5.2. Tạo vận đơn

1. Mở đơn hàng, tới khung Vận chuyển, bấm Tạo vận đơn.

2. Kiểm lại người nhận, Khối lượng (gram) và — nếu đã đóng gói — Kích thước kiện (cm). Số liệu đúng giúp phí GHN thu khớp phí khách đã trả.

3. Kiểm Tiền thu hộ (COD): mặc định là số tiền khách còn phải trả.

4. Bấm tạo. Nếu thành công, khung hiện Mã vận đơn GHN (ví dụ L8RWHQ), phí hãng và trạng thái Chờ lấy hàng.

   Nếu khung báo "Phí hãng khác phí trên đơn", khối lượng hoặc kích thước đã khác lúc khách đặt — kiểm lại trước khi giao hàng cho shipper.

5.3. In nhãn

Bấm Tải nhãn: trình duyệt tải về một tệp .html do GHN tạo. Mở tệp đó, hộp thoại in tự hiện. Cần có mạng khi mở (ảnh mã vạch lấy từ GHN). Đổi khổ nhãn ở ô Khổ nhãn in của màn cấu hình.

5.4. Theo dõi, huỷ

• Đồng bộ: hỏi GHN trạng thái mới nhất; lịch sử hiện ở Lịch sử vận chuyển.
• Huỷ vận đơn: chỉ được khi GHN còn cho huỷ (thường là trước khi lấy hàng). Huỷ xong mới tạo được vận đơn mới cho cùng đơn.
• Trạng thái Đã giao, Đã hoàn hàng, Đã huỷ và tiền thu hộ luôn được hỏi lại trực tiếp GHN trước khi ghi nhận, nên thông báo giả không đổi được trạng thái tiền của đơn.

Điều kiện & ràng buộc (hiểu trước khi thao tác)

Khi báo phí ở trang thanh toán

• Tổng khối lượng tối đa 50 kg — GHN không nhận kiện nặng hơn, nên GHN không hiện ở trang thanh toán.
• Địa chỉ khách phải có Tỉnh/Thành phố và Phường/Xã khớp danh mục của GHN (không phân biệt dấu, bỏ qua tiền tố như "TP.", "Phường"). Địa chỉ cũ còn ghi Quận/Huyện được gửi nguyên văn theo kiểu cũ. Tên quá khác ⇒ không có phí GHN cho địa chỉ đó.
• Kho lấy hàng đã khai mà GHN không nhận ra tên Tỉnh/Phường ⇒ GHN không báo phí — sửa theo tên đơn vị hành chính mới.

Khi tạo vận đơn

• Bắt buộc tên và số điện thoại người nhận — shipper cần liên lạc.
• Tiền thu hộ tối đa 50.000.000đ mỗi đơn — giới hạn của GHN.
• Giá trị bảo hiểm tối đa 5.000.000đ — vượt mức này GHN chỉ bảo hiểm tới 5.000.000đ.
• Tạo lại sau khi lỗi mạng không sinh đơn trùng — GHN trả lại đúng vận đơn đã tạo.

Khi huỷ

• Chỉ huỷ được khi GHN còn cho phép; GHN từ chối thì admin thấy đúng lý do của GHN.

Môi trường

• Token, ShopId và webhook của staging không dùng được cho môi trường thật, và ngược lại.

Tài liệu API

Theo tài liệu công khai của GHN (developer.ghn.vn), đối chiếu và thử thật trên staging ngày 2026-10-18.

Giấy phép

Miễn phí, mã nguồn mở theo giấy phép của GP247.

Hỏi & Đáp (Q&A)

Câu 1: Không thấy GHN ở trang thanh toán?

→ Kiểm lần lượt: màn cấu hình GHN báo Kết nối thành công; tab Khách hàng đã bật Tỉnh/Phường; kho lấy hàng đủ Tỉnh, Phường, Địa chỉ chi tiết; có đồng VND; giỏ hàng không quá 50 kg; plugin đã được bật cho cửa hàng đang bán.

Câu 2: Token đúng nhưng GHN không báo phí, hoặc tạo vận đơn bị báo "Address convert from fail"?

→ GHN không biết lấy hàng ở đâu. Khai đủ Kho lấy hàng ở Cấu hình cửa hàng → Vận chuyển (Phần 3.1), hoặc khai địa chỉ cho cửa hàng trên GHN.

Câu 3: Tôi đổi từ staging sang thật cần làm gì?

→ Lấy Token và ShopId trên developer.ghn.vn, chọn Môi trường = Thật (production), dán Token mới, sửa ShopId, Lưu; rồi cấu hình lại webhook trên trang GHN thật (Phần 4).

Câu 4: Phí GHN thu khác phí khách đã trả?

→ Thường do khối lượng sản phẩm thiếu hoặc sai. Nhập khối lượng (và kích thước) cho sản phẩm; khi tạo vận đơn sửa khối lượng và kích thước kiện cho đúng hộp đã đóng gói.

Câu 5: Địa chỉ khách vẫn ghi theo kiểu cũ (có Quận/Huyện) thì sao?

→ Plugin gửi nguyên văn theo kiểu cũ và để GHN tự tìm. Nếu GHN vẫn không nhận, sửa địa chỉ theo tên đơn vị hành chính mới trước khi tạo vận đơn.

Câu 6: Trạng thái đơn không tự cập nhật?

→ Kiểm webhook đã dán đúng URL, đúng môi trường, và đã qua khoảng 15 phút. Trang chạy trên tên miền nội bộ thì GHN không gọi tới được — dùng nút Đồng bộ.

Câu 7: Tệp nhãn mở ra trắng hoặc thiếu mã vạch?

→ Máy đang mở tệp cần có Internet (ảnh mã vạch tải từ GHN). Nếu vẫn lỗi, bấm Tải nhãn lại để lấy tệp mới.

Câu 8: Một tài khoản GHN dùng cho nhiều cửa hàng được không?

→ Được. Nhập Token và ShopId ở phạm vi chung; mỗi cửa hàng khai kho lấy hàng riêng ở Cấu hình cửa hàng, GHN đến đúng kho đó. Cửa hàng nào cần tài khoản GHN riêng thì chọn cửa hàng đó trên màn cấu hình và nhập Token riêng.

Câu 9: Gặp lỗi thì xem thông báo ở đâu?

→ Khi tạo, huỷ hay tải nhãn, admin hiện câu nói rõ cần sửa gì (vd ô Địa chỉ chính ghi tên phường khác với Phường/Xã đã chọn, số điện thoại sai, tuyến chưa có dịch vụ), kèm nguyên văn của GHN trong ngoặc. Token bị GHN từ chối được ghi vào nhật ký hệ thống để bạn biết cần lấy Token mới.

Câu 10: Gỡ plugin có mất vận đơn đã tạo không?

→ Không. Vận đơn và lịch sử được lưu trong cửa hàng; gỡ plugin chỉ xoá cấu hình GHN.

_{📅 Cập nhật lần cuối: 2026-10-18 · ✍️ Tác giả (Author): GP247}