Webhook và đồng bộ trạng thái
Không có webhook thì website không biết đơn đã giao hay chưa. Khai xong một đường dẫn, VNPost chủ động báo về và đơn tự đổi trạng thái — kèm một lớp xác thực chữ ký RSA-2048 để không ai giả mạo được.
Lấy đường dẫn Webhook
Vào WooCommerce → Cài đặt VNPost, tab Cài đặt VNPost, mục con Webhook.
- Webhook — mục con thứ năm.
- Thay đổi key — sinh lại đoạn khoá ở cuối đường dẫn. Bấm là đường dẫn cũ hết hiệu lực ngay.
- Xác thực chữ ký — kiểm tra chữ ký RSA-2048 của webhook trước khi xử lý, sai thì từ chối. Xem cảnh báo bên dưới trước khi bật.
Chép nguyên Đường dẫn Webhook rồi khai vào tài khoản VNPost của bạn — liên kết đường dẫn sau ngay trên đó đưa bạn tới đúng trang cần khai.
Chính plugin cũng ghi rõ điều này: bật xác thực khi webhook chưa chạy thông thì bạn chặn nhầm toàn bộ và không biết lỗi nằm ở khâu nào. Trình tự đúng: khai đường dẫn → chờ VNPost bắn về được → thấy trạng thái tự đổi → lúc đó mới tích ô xác thực.
Bấm Thay đổi key thì đường dẫn cũ hết hiệu lực lập tức, còn VNPost vẫn gọi vào địa chỉ cũ. Thay xong phải khai lại đường dẫn mới bên VNPost.
Ánh xạ trạng thái
VNPost 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 VNPost đẩy đơn của bạn sang trạng thái WooCommerce nào.
- Trạng thái trên VNPost — mã và mô tả do VNPost quy định, ví dụ (6) Lấy hàng thành công, (8) Lấy hàng thất bại. 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 VNPost | Trạng thái WooCommerce nên chọn |
|---|---|
| Lấy hàng thành công | Trạng thái riêng kiểu Đang giao hàng nếu bạn có, hoặc Đang xử lý. |
| Phát 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. Chỉ ánh xạ mốc phát thành công vào đó.
Cách kiểm tra đã chạy đúng chưa
- Bật Ghi log (debug) ở mục Cài đặt chung.
- Khai đường dẫn webhook bên VNPost, chưa bật xác thực chữ ký.
- Đăng một đơn thử và chờ VNPost đổi trạng thái.
- Mở đơn trên website — ô VNPost phải hiện Trạng thái đơn trên VNPost, và trạng thái đơn đổi theo bảng ánh xạ.
- Chạy thông rồi mới tích Xác thực chữ ký, sau đó thử lại một lần nữa.
Lỗi thường gặp
| Hiện tượng | Cách xử lý |
|---|---|
| Trạng thái không bao giờ tự đổi | VNPost chưa khai webhook, hoặc khai sai đường dẫn. Chép lại nguyên vẹn và khai lại. |
| Bật xác thực chữ ký xong là mất hết cập nhật | Đúng như cảnh báo — tắt xác thực đi, cho webhook chạy thông đã, rồi mới bật lại. |
| Trước có chạy, giờ dừng hẳn | Bạn vừa bấm Thay đổi key mà chưa khai lại đường dẫn mới bên VNPost, hoặc website đổi tên miền. |
| Đơ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. |
| 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 phát thành công trỏ vào đó. |
| Website chặn webhook | Tường lửa hoặc plugin bảo mật chặn REST API. Nhờ hosting mở cho đường dẫn /wp-json/vnpost/. |
Tiếp theo: email báo vận đơn.