Webhook và đồng bộ trạng thái
Không có webhook thì website không bao giờ biết đơn đã giao hay chưa — bạn phải tự vào ViettelPost tra rồi đổi trạng thái bằng tay. Khai xong webhook, ViettelPost chủ động báo về và đơn trên website tự đổi theo.
Lấy hai giá trị cần khai trên ViettelPost
Vào WooCommerce → ViettelPost, tab ViettelPost, mục con Cấu hình, kéo xuống khối Cài đặt Webhook.
- Đường dẫn API/Webhook — địa chỉ ViettelPost sẽ gọi về. Plugin sinh sẵn, bạn chỉ chép, không sửa gì.
- Tham số bí mật — mật khẩu của webhook, để không ai giả mạo ViettelPost bắn dữ liệu vào website bạn. Bấm Tạo tham số bí mật nếu muốn đổi giá trị mới.
Tham số bí mật chỉ có hiệu lực sau khi bấm Lưu thay đổi ở cuối trang. Lần đầu mở khối này, ô đã có sẵn một giá trị ngẫu nhiên nhưng chưa được lưu — tải lại trang là nó đổi sang giá trị khác. Nên bấm Lưu thay đổi trước, rồi mới chép sang Partner.
Khai webhook trên hệ thống Partner
Việc này bạn tự làm, không phải chờ ViettelPost bật giúp. Dòng chữ trong plugin vẫn ghi "liên hệ với IT bên ViettelPost để kích hoạt" — hiện bạn tự khai được trên Partner như dưới đây.
- Đăng nhập partner.viettelpost.vn bằng chính tài khoản đã điền ở bước đăng nhập.
- Vào Bảng điều khiển → Thông tin tài khoản → Cấu hình webhook.
- Dán Đường dẫn API/Webhook vào ô Webhook Endpoints, và Tham số bí mật (đã lưu) vào ô Secret parameter.
- Bấm Kiểm tra kết nối và chờ báo thành công.
Mỗi tài khoản ViettelPost chỉ khai được một đường dẫn webhook. Một tài khoản dùng cho hai website thì website khai sau sẽ chiếm chỗ website khai trước. Kiểm tra kết nối báo lỗi mà không rõ nguyên nhân thì liên hệ đội hỗ trợ của ViettelPost.
Bấm Tạo tham số bí mật chỉ điền giá trị mới vào ô. Tới lúc bấm Lưu thay đổi, giá trị mới có hiệu lực và mọi dữ liệu ViettelPost gửi kèm giá trị cũ bị website bỏ qua. Lưu xong phải vào Partner cập nhật lại giá trị mới. Đừng đổi chỉ vì tò mò.
Dữ liệu Viettel Post gửi về, yêu cầu phản hồi và mã trạng thái chi tiết có ở bài webhook Viettel Post.
Ánh xạ trạng thái
ViettelPost có rất nhiều trạng thái, WooCommerce chỉ có vài cái. Bảng này quyết định mỗi trạng thái ViettelPost sẽ đẩy đơn của bạn sang trạng thái WooCommerce nào.
- Trạng thái ViettelPost — mã và mô tả do ViettelPost quy định, ví dụ (101) ViettelPost yêu cầu huỷ đơn hàng, (105) Bưu tá đã nhận hàng. Cột này chỉ để đọc.
Ở cột phải, mỗi dòng chọn một trạng thái WooCommerce. Để Không đồng bộ trạng thái nghĩa là bỏ qua mốc đó — và đó là mặc định hợp lý cho phần lớn các dòng.
Mới cài, plugin đã đặt sẵn:
- 501 Thành công - Phát thành công → Hoàn thành.
- -15, 101 ViettelPost yêu cầu hủy đơn hàng, 107 Đối tác yêu cầu hủy qua API, 503 Hủy - Theo yêu cầu khách hàng → Đã huỷ.
- 102 Đơn hàng chờ xử lý → Đang xử lý.
- Mọi mã khác → Không đồng bộ trạng thái.
Webhook đưa đơn sang Đã huỷ thì plugin xoá mã vận đơn trên đơn đó, để bạn tạo lại vận đơn mới được. Từ lúc đó, cập nhật sau của vận đơn cũ không về đơn nữa. Vì vậy chỉ trỏ Đã huỷ cho các mốc huỷ thật, đừng trỏ cho mốc chuyển hoàn.
Thực tế chỉ nên ánh xạ vài mốc quan trọng:
| Mốc ViettelPost | Trạng thái WooCommerce nên chọn |
|---|---|
| (105) Bưu tá đã nhận hàng | Trạng thái riêng kiểu Đang giao hàng nếu bạn có, hoặc Đang xử lý. |
| (501) Phát thành công | Hoàn thành (mặc định đã đặt sẵn). |
| Các mốc huỷ (101, 107, 503) | Đã huỷ (mặc định đã đặt sẵn). |
| Chuyển hoàn, ví dụ (504) Thành công - Chuyển trả người gửi | Một trạng thái riêng để bạn nhận ra hàng đang quay về. Đừng chọn Đã huỷ. |
| Các mốc trung gian còn lại | Không đồng bộ trạng thái — ánh xạ hết chỉ làm đơn nhảy loạn xạ. |
Chỉnh xong bấm Lưu thay đổi ở cuối trang.
Dù mốc có được ánh xạ hay không, mỗi lần webhook về plugin đều lưu trạng thái và lịch sử hành trình lên đơn. Ô ViettelPost trong trang đơn hiện Trạng thái trên VTP hiện tại, và trang tra cứu dùng lịch sử này để hiện dòng thời gian cho khách.
Trong WooCommerce, chuyển sang Hoàn thành thường kéo theo email cảm ơn gửi cho khách, cộng điểm thưởng, trừ kho. Ánh xạ một mốc trung gian vào Hoàn thành là khách nhận email "đã giao hàng" trong lúc hàng còn ở kho. Chỉ ánh xạ mốc giao thành công vào đó.
Cách kiểm tra đã chạy đúng chưa
- Sau khi Kiểm tra kết nối trên Partner báo thành công, tạo một vận đơn thử.
- Chờ vận đơn đổi trạng thái bên ViettelPost.
- Mở đơn trên website — dòng Trạng thái trên VTP trong ô ViettelPost phải cập nhật.
- Nếu mốc đó có ánh xạ, trạng thái đơn đổi theo bảng. Ghi chú đơn hàng chỉ có dòng mới khi trạng thái WooCommerce thật sự đổi (ghi chú đổi trạng thái của WooCommerce) — mốc không ánh xạ, hoặc đơn đã sẵn ở trạng thái đó, thì không có ghi chú.
Lỗi thường gặp
| Hiện tượng | Cách xử lý |
|---|---|
| Trạng thái không bao giờ tự đổi | Chưa khai webhook trên Partner, khai sai, hoặc chưa bấm Lưu thay đổi cho tham số bí mật. Vào Cấu hình webhook trên Partner, so đường dẫn và tham số bí mật với khối Cài đặt Webhook (sau khi đã lưu), rồi bấm Kiểm tra kết nối. Hai giá trị phải giống hệt nhau, nên so tận mắt từng ký tự. |
| Dòng Trạng thái trên VTP có đổi nhưng trạng thái đơn đứng yên | Mốc đó đang để Không đồng bộ trạng thái. Chọn trạng thái cho mốc đó nếu bạn cần. |
| Trước có chạy, giờ dừng hẳn | Bạn vừa lưu Tham số bí mật mới mà chưa cập nhật trên Partner, website vừa đổi tên miền nên đường dẫn cũ không còn đúng, hoặc một website khác vừa khai đè đường dẫn của cùng tài khoản. |
| Đơn bị huỷ vận đơn xong không nhận cập nhật nữa | Đúng như thiết kế: chuyển sang Đã huỷ thì mã vận đơn bị xoá khỏi đơn. Tạo vận đơn mới nếu vẫn gửi hàng. |
| Đơn nhảy trạng thái liên tục | Ánh xạ quá nhiều mốc. Đặt lại phần lớn về Không đồng bộ trạng thái, chỉ giữ vài mốc thật cần. |
| Khách nhận email "hoàn thành" quá sớm | Một mốc trung gian đang trỏ vào Hoàn thành. Chỉ để mốc giao thành công trỏ vào đó. |
| Website chặn webhook | Tường lửa hoặc plugin bảo mật chặn admin-ajax.php. Nhờ hosting mở cho đường dẫn webhook. |
Tiếp theo: email báo mã và trang tra cứu.