Tích hợp API GHN, GHTK, Viettel Post cho website bán hàng

Tích hợp API giao hàng là nối website bán hàng với hệ thống của hãng vận chuyển để tự tính phí ship, tự tạo vận đơn khi khách đặt hàng và tự cập nhật trạng thái đơn. Cả GHN, GHTK và Viettel Post đều có API REST cho các việc này. Khác biệt lớn nhất khi lập trình nằm ở cách xác thực: GHN và GHTK dùng token cố định gắn vào header, còn Viettel Post dùng token lấy qua API đăng nhập.

Ba đơn vị giao hàng phổ biến cho website Việt

• GHN (Giao Hàng Nhanh): mạnh ở các thành phố lớn, tài liệu API tiếng Việt đầy đủ, cộng đồng lập trình dùng nhiều nên dễ tìm ví dụ.
• GHTK (Giao Hàng Tiết Kiệm): phổ biến với shop online bán đơn nhỏ, API gọn, có môi trường staging riêng.
• Viettel Post: mạng lưới bưu cục rộng tới vùng xa nhờ hạ tầng của Viettel, phù hợp khi khách ở nhiều tỉnh.

So sánh API GHN, GHTK và Viettel Post

Tích hợp API GHTK (Giao Hàng Tiết Kiệm) vào website

Theo tài liệu tại pro-docs.ghtk.vn, mọi yêu cầu gửi tới API GHTK cần header Token chứa API token của shop, và header X-Client-Source chứa mã đối tác (partner code). API nhận dữ liệu dạng JSON hoặc x-www-form-urlencoded.

1. Đăng ký tài khoản shop tại GHTK, khai báo thông tin và địa chỉ lấy hàng.
2. Lấy API token trong mục cấu hình API của tài khoản; nếu tích hợp dưới dạng đối tác (nền tảng phục vụ nhiều shop) thì cần thêm mã đối tác cho X-Client-Source.
3. Làm và test trên môi trường staging services-staging.ghtklab.com để không tạo đơn thật.
4. Gọi các API chính: tính phí vận chuyển theo địa chỉ và cân nặng, tạo đơn, huỷ đơn, tra trạng thái theo mã vận đơn.
5. Cung cấp cho GHTK một callback URL để nhận webhook mỗi khi trạng thái đơn thay đổi, thay vì tra cứu liên tục.
6. Với đơn giá trị cao, khai giá trị hàng trong payload tạo đơn để được bồi thường đúng mức khi có sự cố.

Tích hợp API Viettel Post

Viettel Post công bố tài liệu Open API tại cổng đối tác partner.viettelpost.vn, cho phép website, ERP, CRM tạo đơn, theo dõi hành trình và đồng bộ trạng thái. Khác hai hãng trên, bạn gọi API đăng nhập bằng tài khoản đối tác để nhận token, rồi gửi token đó trong header của các API cần xác thực.

1. Đăng ký tài khoản doanh nghiệp với Viettel Post, cung cấp thông tin pháp lý và kho hàng.
2. Đọc danh sách API và ví dụ cURL trong mục tài liệu của cổng đối tác.
3. Gọi API đăng nhập để lấy token; viết sẵn phần làm mới token khi hết hạn thay vì đợi lỗi xác thực mới xử lý.
4. Dùng token cho các API: lấy bảng giá dịch vụ, tạo đơn, huỷ đơn, tra hành trình theo mã vận đơn.
5. Với khách ở vùng xa, kiểm tra vùng phục vụ trước khi cho khách chọn Viettel Post ở bước thanh toán.

Tích hợp API GHN (Giao Hàng Nhanh)

GHN cấp API dạng REST, xác thực bằng header Token, và yêu cầu header ShopId khi tạo đơn.

1. Đăng ký tài khoản cửa hàng trên GHN, khai báo địa chỉ lấy hàng.
2. Lấy Token API và ShopId trong trang quản lý (một tài khoản có thể có nhiều ShopId nếu có nhiều kho, chi nhánh).
3. Dùng domain sandbox của GHN khi phát triển để không tạo đơn thật, chỉ đổi sang domain production khi go-live.
4. Các nhóm API chính: danh sách tỉnh, huyện, xã để chuẩn hoá địa chỉ; tính phí; tạo vận đơn; tra trạng thái theo mã vận đơn.
5. Đăng ký webhook trong trang quản lý để nhận trạng thái tự động.

Tích hợp nhiều hãng trong một website: logic chọn hãng

Khi dùng từ hai hãng trở lên, website cần một lớp trung gian (dispatcher) chọn hãng cho từng đơn. Ví dụ quy tắc hay dùng:

• Đơn nhẹ, nội tỉnh, khách chọn giao tiết kiệm: gọi API tính phí của các hãng rồi chọn hãng rẻ nhất.
• Khách cần giao nhanh trong thành phố lớn: ưu tiên hãng có dịch vụ nhanh ở khu vực đó.
• Địa chỉ vùng xa: ưu tiên hãng có vùng phục vụ tới xã đó.
• Đơn thu hộ (COD) giá trị cao: ưu tiên hãng có chính sách bảo hiểm phù hợp, và luôn khai giá trị hàng.

Quy trình tích hợp

1. Đăng ký tài khoản doanh nghiệp tại từng hãng.
2. Nhận thông tin xác thực (token, mã đối tác, ShopId tuỳ hãng).
3. Làm trên môi trường test của từng hãng.
4. Viết lớp bọc (wrapper) chung trong mã nguồn để đổi hãng không phải sửa luồng đặt hàng.
5. Dựng endpoint nhận webhook trạng thái, xác thực nguồn gửi trước khi cập nhật đơn.
6. Go-live với một hãng trước, mở rộng dần.

Website bán hàng cần tích hợp giao hàng nhiều hãng, liên hệ ALODEV qua trang /lien-he để được tư vấn.

Câu hỏi thường gặp về API GHTK

API GHTK lấy token ở đâu?

Trong mục cấu hình API của tài khoản shop GHTK. Token gửi trong header Token của mọi yêu cầu. Nếu bạn là nền tảng tích hợp cho nhiều shop, cần thêm mã đối tác gửi trong header X-Client-Source.

Tích hợp Giao Hàng Tiết Kiệm vào website gồm những bước nào?

Đăng ký shop, lấy token, làm trên staging services-staging.ghtklab.com, gọi các API tính phí, tạo đơn, huỷ đơn, tra trạng thái, cung cấp callback URL để nhận webhook, rồi chuyển sang production.

GHTK có môi trường test không?

Có. Tài liệu GHTK dùng services-staging.ghtklab.com làm môi trường staging để thử trước khi dùng production.

Câu hỏi thường gặp về API Viettel Post

Viettel Post API xác thực thế nào?

Gọi API đăng nhập bằng tài khoản đối tác để lấy token, rồi gửi token trong header của các API cần xác thực. Token có thời hạn nên mã nguồn phải có phần làm mới token.

Tài liệu API Viettel Post ở đâu?

Ở cổng đối tác partner.viettelpost.vn, mục tài liệu, gồm danh sách API, mô tả tham số và ví dụ cURL. Kênh hỗ trợ đối tác được công bố ngay trên cổng này.

Câu hỏi thường gặp về API GHN

API GHN cần những thông tin gì?

Token API và ShopId, lấy trong trang quản lý của tài khoản GHN. Token đi trong header Token; ShopId đi trong header ShopId khi tạo đơn.

Có nên tích hợp cả GHN, GHTK và Viettel Post không?

Chỉ khi lượng đơn đủ lớn và khách trải rộng nhiều vùng. Shop mới nên bắt đầu với một hãng, viết sẵn lớp bọc chung, khi cần thì thêm hãng thứ hai mà không phải sửa luồng đặt hàng.