Tích hợp API Viettel Post và GHN vào website bán hàng

Để tích hợp api viettel post vào website bán hàng, bạn cần tài khoản được cấp quyền kết nối, thông tin xác thực và phần xử lý trên máy chủ. Với GHN, quy trình cũng đi từ chuẩn hóa địa chỉ đến tính phí, tạo vận đơn và đồng bộ trạng thái. Mình sẽ hướng dẫn cách chia từng bước để bạn có thể trao đổi rõ yêu cầu với người làm website.

Điều kiện cần trước khi bắt đầu

• Tài khoản hãng vận chuyển có quyền dùng API, thông tin cửa hàng và địa chỉ kho lấy hàng.
• Quyền quản trị website, quyền cấu hình máy chủ hoặc người phụ trách kỹ thuật hỗ trợ phần kết nối.
• Bản website thử nghiệm, bản sao lưu và dữ liệu đơn mẫu tách khỏi đơn khách đang mua.
• Thông tin sản phẩm đủ khối lượng, kích thước đóng gói; quy định người trả phí và tiền thu hộ.
• Người phụ trách xác nhận kết quả trước khi mở tính năng cho khách. Thời gian hoàn thành còn phụ thuộc việc cấp tài khoản và cấu trúc website, nên cần thống nhất sau khi kiểm tra các điều kiện trên.

Chọn cách kết nối phù hợp với website

Với website tự xây dựng, nên để máy chủ nhận địa chỉ từ giỏ hàng rồi gọi API của hãng. Trình duyệt chỉ nhận kết quả cần hiển thị. Cách tổ chức này giúp giữ khóa truy cập khỏi mã trang và cho phép xử lý riêng dữ liệu của từng hãng.

Với WooCommerce, bạn có thể dùng plugin hoặc viết phần kết nối riêng. Khi chọn plugin, cần xem lịch sử cập nhật, phiên bản API được hỗ trợ, khả năng tương thích với trang thanh toán và cách xử lý lỗi. Nên yêu cầu mô tả rõ plugin hỗ trợ tính phí, tạo đơn hay cả webhook; tên hãng trên trang giới thiệu chưa đủ để xác nhận mọi chức năng.

Cách tích hợp api viettel post: tài khoản và môi trường

1. 1Thiết lập thông tin xác thực của từng hãng trên máy chủ.

Viettel Post hướng dẫn đối tác liên hệ bộ phận kinh doanh hoặc chăm sóc khách hàng để đăng ký tài khoản Partner, sau đó lấy token theo tài liệu. Xem hướng dẫn kết nối Viettel Post. Với GHN, bạn lấy token qua cổng nhà phát triển và dùng ShopId cho API yêu cầu mã cửa hàng, theo hướng dẫn lấy token. Đã xong khi máy chủ có cấu hình riêng cho từng hãng, đúng tài khoản và kho hàng.

Nếu chưa có quyền hoặc không lấy được token, hãy xác nhận lại tài khoản với hãng trước khi làm tiếp. Không gửi khóa truy cập trong nội dung công khai; phần nhật ký lỗi cũng cần che thông tin này.

2. 2Kết nối website thử nghiệm với môi trường thử của hãng.

Nếu bạn đang tìm “viettel post api sandbox”, tài liệu Viettel Post gọi môi trường thử là Development, tại https://partnerdev.viettelpost.vn; Production là https://partner.viettelpost.vn. Xem môi trường và tham số chung. GHN dùng Staging tại https://dev-online-gateway.ghn.vn và Production tại https://online-gateway.ghn.vn, theo tổng quan API. Đã xong khi yêu cầu đọc dữ liệu trả về kết quả hợp lệ từ đúng môi trường thử.

Nếu xác thực thất bại, kiểm tra địa chỉ máy chủ và token trước. GHN tách tài khoản, token giữa môi trường thử và chính thức; không dùng chéo. Với Viettel Post, cần xác nhận quyền môi trường của tài khoản được cấp. Giữ tính năng tạo vận đơn tự động ở trạng thái tắt khi kết nối chưa ổn định.

Chuẩn hóa địa chỉ và tính phí trong giỏ hàng

3. 3Ánh xạ địa chỉ website sang danh mục của từng hãng.

Mỗi hãng có bộ mã riêng, vì vậy không lấy mã phường của GHN gửi sang Viettel Post dù tên địa phương giống nhau. Với danh mục có quận huyện, cần lấy tỉnh, rồi quận huyện thuộc tỉnh, rồi phường xã thuộc quận huyện. GHN còn có danh mục tỉnh theo mô hình địa chỉ mới; hãy dùng đúng danh mục mà API đích yêu cầu. Đã xong khi địa chỉ khách chọn được chuyển thành dữ liệu hợp lệ cho từng hãng.

Nếu hãng báo địa chỉ không hợp lệ, tải lại danh mục và kiểm tra quan hệ giữa các cấp. Khi khách đổi tỉnh hoặc đổi hãng vận chuyển, cần bỏ lựa chọn phụ thuộc đã cũ. Không tự ghép tên gần giống để gửi đơn khi chưa xác định đúng địa chỉ.

4. 4Gắn chức năng tính phí vào giỏ hàng.

Máy chủ cần gửi địa chỉ lấy hàng, địa chỉ nhận và thông tin kiện hàng theo yêu cầu của hãng. Chẳng hạn, API tính phí GHN yêu cầu Token, ShopId, khối lượng và dữ liệu tuyến giao; weight dùng đơn vị gram. Đã xong khi giỏ hàng hiển thị phí tương ứng với địa chỉ, kiện hàng và dịch vụ đang chọn, đồng thời cập nhật lại sau khi khách thay đổi dữ liệu.

Nếu không lấy được phí, hãy hiển thị trạng thái cần xác nhận vận chuyển và kiểm tra đầu vào. Không biến lỗi kết nối thành miễn phí giao hàng. Với Viettel Post, lỗi tính cước có thể liên quan dịch vụ không áp dụng cho tuyến hoặc tài khoản; cần đối chiếu mô tả lỗi chính thức trước khi sửa cấu hình.

Tạo vận đơn và tra cứu trạng thái

5. 5Gửi đơn đã đủ điều kiện xử lý sang hãng vận chuyển.

Bạn cần thống nhất thời điểm gửi: sau khi nhân viên xác nhận hoặc sau khi đơn đạt điều kiện thanh toán của cửa hàng. Đã xong khi website lưu mã vận đơn hãng trả về cùng đơn mua hàng và có thể đối chiếu thông tin người nhận. Với GHN, client_order_code giúp nhận lại mã vận đơn đã tạo khi gửi lại cùng mã tham chiếu, theo tài liệu tạo đơn. Khi tích hợp api giao hàng nhanh, nên tận dụng cơ chế này để hạn chế đơn trùng.

Nếu yêu cầu bị ngắt giữa chừng, tra cứu xem hãng đã nhận đơn chưa trước khi gửi lại. Chưa nhận được phản hồi không đồng nghĩa với chưa tạo đơn. Với Viettel Post, cần đối chiếu cơ chế tạo và tra cứu đơn của hãng, không mặc định hãng dùng cùng tham số với GHN.

6. 6Liên kết chức năng tra cứu với mã vận đơn đã lưu.

Website nên giữ cả trạng thái gốc của hãng và trạng thái dễ hiểu cho khách. API tra cứu GHN nhận order_code là mã vận đơn GHN; đơn phải thuộc cửa hàng mà tài khoản có quyền truy cập. Đã xong khi phần quản trị mở được thông tin của đúng kiện hàng và khách xem được tiến trình tương ứng với đơn mua.

Nếu không tìm thấy đơn, kiểm tra mã vận đơn, tài khoản và môi trường. Đừng dùng mã đơn nội bộ thay cho mã hãng nếu API không hỗ trợ. Trạng thái giao thành công cũng cần được quản lý riêng với trạng thái thanh toán hoặc đối soát tiền thu hộ.

Nhận webhook và chuyển sang vận hành

7. 7Cấu hình địa chỉ nhận webhook trên website.

Webhook là thông báo hãng chủ động gửi về máy chủ khi đơn thay đổi. GHN cho phép đăng ký địa chỉ nhận trong cổng nhà phát triển; xem hướng dẫn webhook GHN. Viettel Post cũng hướng dẫn cấu hình webhook trong hệ thống Partner. Đã xong khi thông báo nhận được cập nhật đúng đơn, và việc nhận lại cùng sự kiện không khiến website xử lý lặp.

Nếu chưa nhận được thông báo, kiểm tra địa chỉ nhận có truy cập được từ bên ngoài và cấu hình có đúng môi trường không. Cần kiểm tra cơ chế xác thực thông báo theo tài liệu từng hãng. Trong lúc khắc phục, có thể dùng chức năng tra cứu để đối chiếu trạng thái; không suy đoán đơn đã giao chỉ vì webhook đến chậm.

8. 8Chuyển cấu hình đã kiểm tra sang môi trường chính thức.

Phần chuyển đổi cần bao gồm địa chỉ API, thông tin xác thực, kho hàng và webhook tương ứng. GHN yêu cầu cấu hình webhook riêng cho môi trường chính thức. Đã xong khi đơn bán hàng hợp lệ xuất hiện đúng tài khoản hãng, website giữ được mã vận đơn và các cập nhật khớp nhau. Nên có người theo dõi các đơn đầu tiên trước khi mở rộng tự động hóa.

Nếu kết quả không khớp, tạm dừng tự động tạo vận đơn và chuyển đơn chờ sang quy trình xác nhận thủ công. Giữ lại mã vận đơn đã tạo để tiếp tục theo dõi; việc khôi phục cấu hình website không tự hủy đơn bên hãng.

Kiểm lại

• Thông tin xác thực được giữ trên máy chủ, đúng hãng và đúng môi trường.
• Địa chỉ, khối lượng và dịch vụ được kiểm tra trước khi tính phí.
• Đơn mua hàng liên kết đúng mã vận đơn, có cách xử lý yêu cầu gửi lại.
• Tra cứu và webhook cập nhật đúng đơn; trạng thái thanh toán được quản lý riêng.
• Có người tiếp nhận lỗi và phương án xử lý thủ công khi kết nối gián đoạn.

Nếu cần đưa quy trình tích hợp api viettel post vào một website mới hoặc nâng cấp cửa hàng hiện tại, bạn có thể xem dịch vụ thiết kế website bán hàng của hstation để trao đổi phạm vi kết nối phù hợp.