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 gửi cho 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.
Chép cả hai rồi liên hệ bộ phận IT của ViettelPost nhờ khai vào tài khoản của bạn và kích hoạt. Đây là việc phải nhờ ViettelPost làm, không tự bật được từ website.
Bấm Tạo tham số bí mật thì giá trị cũ hết hiệu lực lập tức, và ViettelPost vẫn gửi kèm giá trị cũ nên website từ chối hết. Đổi xong phải báo lại ViettelPost giá trị mới. Đừng bấm nút đó chỉ vì tò mò.
Á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.
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 |
|---|---|
| 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ý. |
| Giao hàng thành công | Hoàn thành. |
| Huỷ đơn / khách từ chối nhận | Đã huỷ. |
| Chuyển hoàn về người gửi | Một trạng thái riêng để bạn nhận ra hàng đang quay về. |
| 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.
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 ViettelPost xác nhận đã bật webhook, tạo một vận đơn thử.
- Chờ vận đơn đổi trạng thái bên ViettelPost (hoặc nhờ ViettelPost bắn thử một sự kiện).
- Mở đơn trên website — trạng thái phải đổi theo đúng bảng ánh xạ, và Đặt hàng ghi chú có ghi lại lần cập nhật đó.
Lỗi thường gặp
| Hiện tượng | Cách xử lý |
|---|---|
| Trạng thái không bao giờ tự đổi | ViettelPost chưa bật webhook cho tài khoản của bạn. Gửi lại hai giá trị ở khối Cài đặt Webhook và hỏi IT ViettelPost đã kích hoạt chưa. |
| Trước có chạy, giờ dừng hẳn | Bạn vừa đổi Tham số bí mật mà chưa báo ViettelPost, hoặc website vừa đổi tên miền nên đường dẫn cũ không còn đú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.