Webhook và đồng bộ trạng thái
Webhook là đường dây để SPX tự báo về website mỗi khi vận đơn đổi trạng thái. Tab này cũng là nơi đồng bộ dữ liệu địa chỉ chuẩn SPX — thứ mà thiếu nó thì ô Tỉnh/Phường trống trơn.
Đồng bộ dữ liệu địa chỉ — làm trước tiên
SPX dùng bộ dữ liệu Tỉnh/Phường của riêng họ. Website phải có đúng bộ đó thì mới tính được phí và tạo được đơn.
- Đồng bộ ngay — tải dữ liệu địa chỉ thẳng từ SPX. Đây là cách nên dùng, chạy một lần sau khi kết nối API xong.
- Tải file lên & nhập — dùng khi hosting chặn kết nối hoặc SPX gửi bạn file danh sách riêng.
Ô Tỉnh/Phường ở trang thanh toán và ở khai báo kho sẽ trống, phí không tính được, đơn không tạo được. Nếu bạn vừa cài xong mà thấy mấy triệu chứng đó cùng lúc, hãy bấm Đồng bộ ngay trước khi đi tìm nguyên nhân khác.
Sau các đợt sáp nhập đơn vị hành chính, hãy đồng bộ lại để danh sách khớp với SPX.
Đăng ký webhook
- Webhook & Đồng bộ — mục thứ sáu trên thanh tab.
- Tạo token mới — sinh mã mới. Chỉ dùng khi bạn lỡ để lộ đường dẫn cũ; đổi xong phải gửi lại đường dẫn mới cho SPX, không thì trạng thái ngừng cập nhật.
Chép nguyên đường dẫn (có nút Sao chép bên cạnh) rồi gửi cho nhân viên SPX phụ trách shop, đề nghị đăng ký webhook trạng thái vận đơn cho website. Việc bật là do SPX làm, bạn không tự bật được.
Ánh xạ trạng thái SPX sang WooCommerce
| Trạng thái SPX | Nên đặt gì |
|---|---|
| 1001 — Chờ lấy hàng | Thường để Không đổi, hoặc chuyển sang trạng thái riêng nếu bạn muốn lọc đơn đã đẩy. |
| 2001 — Đang vận chuyển | Để Không đổi, hoặc một trạng thái tự tạo như Đang giao. |
| 2006 — Đang giao hàng | Như trên. Đây là lúc shipper đang trên đường tới khách. |
| 4001 — Đã giao hàng | Đặt Đã hoàn thành. Đây là dòng quan trọng nhất — nhờ nó mà giao xong đơn tự đóng và doanh thu vào báo cáo. |
| 6003 — Đã hoàn hàng | Đặt Đã huỷ hoặc Đã hoàn lại tiền tuỳ cách bạn hạch toán. |
| 7001 — Đã hủy | Đặt Đã huỷ. |
Chọn Không đổi ở dòng nào thì SPX vẫn báo về, plugin vẫn ghi lại trạng thái vận đơn trong hộp SPX của đơn, nhưng trạng thái đơn WooCommerce giữ nguyên.
Kiểm tra webhook đã chạy
- Tạo một đơn lên SPX.
- Chờ SPX cập nhật trạng thái (thường là khi shipper nhận đơn).
- Mở đơn ra xem dòng Trạng thái trong hộp SPX có đổi không, mà bạn không bấm Cập nhật TT lần nào. Đó là dấu hiệu webhook đang chạy.
- Xem thêm Nhật ký — mỗi lần webhook về đều có một dòng.
Lỗi thường gặp
| Tình huống | Nguyên nhân và cách xử lý |
|---|---|
| Trạng thái không bao giờ tự đổi | SPX chưa bật webhook cho shop. Gửi lại đường dẫn và hỏi nhân viên phụ trách. |
| Website chạy trên máy nội bộ hoặc tên miền thử | SPX phải gọi vào được website từ Internet. Máy local thì webhook không bao giờ tới. |
| Có tường lửa hoặc Cloudflare | Yêu cầu của SPX bị chặn trước khi tới WordPress. Cho phép đường dẫn webhook đi qua. |
| Vừa bấm Tạo token mới thì ngừng cập nhật | Đúng như vậy — mã cũ hết hiệu lực. Gửi đường dẫn mới cho SPX. |
| Đơn tự chuyển sang trạng thái không mong muốn | Xem lại bảng ánh xạ, có thể một mốc trung gian đang bị gán sang Đã hoàn thành. |
Tiếp theo: Trang tra cứu vận đơn.