1. Nhân viên tạo đơn giao hàng trong EzyDelivery với phương thức giao hàng Chuyển phát nhanh và chọn dịch vụ SPX.
2. EzyDelivery hỏi SPX khung giờ lấy hàng sớm nhất còn trống, gửi đơn sang SPX, nhận về mã vận đơn SPX và in tem.
3. Trong quá trình giao, SPX gọi lại (webhook) về hệ thống, EzyDelivery cập nhật trạng thái đơn theo thời gian thực.

Chuẩn bị

Cấu hình dịch vụ SPX

• Nếu đúng: lưu thành công.
• Nếu sai: hiện lỗi ở ô Tên đăng nhập và Mật khẩu. Kiểm tra lại user_id, user_secret, app-id, app-secret, và Đường dẫn API dịch vụ có đúng môi trường hay không (thông tin của môi trường thử nghiệm không dùng được với môi trường thật và ngược lại).

Tài khoản người gửi (user_id, user_secret)

1. Điền Khoá máy khách (app-id) và Khoá bí mật (app-secret).
2. Ở ô Tên đăng nhập, nhập số điện thoại của cửa hàng. Để trống ô Mật khẩu.
3. Bấm Lưu.

• Nếu số điện thoại đã có tài khoản trên SPX, hệ thống không tạo được tài khoản mới và cũng không tự điền gì. Khi đó cần liên hệ SPX để lấy user_id, user_secret của tài khoản đó rồi làm theo cách 1.
• Nếu SPX từ chối tạo tài khoản (ví dụ số điện thoại không hợp lệ, hoặc sai app-id, app-secret), hệ thống báo lỗi ở ô Khoá bí mật.

Đặt làm dịch vụ mặc định (tuỳ chọn)

Ánh xạ tiền tố đơn vị hành chính

[
  { "type": "CITY", "prefix": "Thành Phố" },
  { "type": "DISTRICT_IN_CITY", "prefix": "Quận" },
  { "type": "DISTRICT_IN_PROVINCE", "prefix": "Huyện" },
  { "type": "TOWN_IN_PROVINCE", "prefix": "Thị Xã" },
  { "type": "WARD", "prefix": "Xã" },
  { "type": "WARD_IN_CITY", "prefix": "Phường" },
  { "type": "TOWN", "prefix": "Thị Trấn" }
]

• type: loại đơn vị hành chính, khớp với loại bạn chọn khi tạo tỉnh/thành phố, quận/huyện, phường/xã trên trang quốc gia.
• prefix: tiền tố được thêm trước tên đơn vị khi gửi sang SPX. Ví dụ phường Bến Nghé có loại WARD_IN_CITY sẽ thành Phường Bến Nghé.

Cấu hình webhook với SPX

https://<tên-miền-web-của-bạn>/callback/SPX

https://shop.example.com/callback/SPX

• Đường dẫn trên thuộc trang web (web plugin), không phải trang quản trị. Tên miền phải truy cập được từ Internet và nên dùng https.
• SPX ký mỗi lần gọi webhook bằng app-secret, gửi kèm trong các header app-id, check-sign, timestamp, random-num. EzyDelivery tự tính lại chữ ký bằng ô Khoá bí mật để xác thực:
  • Thiếu header check-sign sẽ bị từ chối với lỗi check-sign: required.
  • Thiếu một trong các header còn lại, hoặc chữ ký không khớp, sẽ bị từ chối với lỗi check-sign: invalid.
  • Nếu chưa điền Khoá bí mật mà SPX vẫn gọi webhook, hệ thống sẽ báo lỗi no spx secret key.
• Dữ liệu SPX gửi về phải có tracking_no, nếu thiếu sẽ bị từ chối (tracking_no: required).
• EzyDelivery chỉ chấp nhận cập nhật cho đơn mà nó đã tạo và có mã vận đơn khớp với tracking_no SPX gửi về. Các đơn tạo trực tiếp trên trang SPX sẽ bị bỏ qua (trả về deliveryOrder: notFound).
• SPX yêu cầu phản hồi trong vòng 3 giây. Nếu webhook liên tục bị từ chối hoặc quá thời gian, SPX có thể ngừng gửi webhook, khi đó trạng thái đơn sẽ không còn tự cập nhật. Vì vậy cần đảm bảo cấu hình đúng trước khi gửi đơn thật.

Tạo đơn giao hàng qua SPX

1. Vào Các yêu cầu giao hàng (/ezydelivery/shipping-requests) và mở yêu cầu cần giao.
2. Bấm Tạo vận đơn, kiểm tra Tổng số cân (kg).
3. Ở ô Dịch vụ vận chuyển, chọn SPX (chỉ hiện khi phương thức giao hàng là chuyển phát nhanh).
4. Bấm Tạo hoặc Tạo và hoàn thành.

Giới hạn kiện hàng của SPX

Kết quả gửi đơn

• Thành công: đơn chuyển sang trạng thái Đã gửi yêu cầu, mã vận đơn SPX (tracking_no) được lưu làm mã vận đơn của đơn, và tem được in ngay. Các thông tin SPX trả về (đường dẫn tra cứu, mã phân loại, phí vận chuyển dự kiến, phí cơ bản, phí thu hộ, phí hàng giá trị cao, VAT, ...) được lưu kèm đơn.
• Thất bại: đơn chuyển sang trạng thái Gửi yêu cầu thất bại, nội dung lỗi SPX trả về (mã lỗi, thông báo, thông tin gỡ lỗi) được lưu vào đơn để xem lại. Sau khi sửa nguyên nhân có thể gửi lại.

Cập nhật trạng thái đơn

https://spx.vn/track?<mã-vận-đơn>

Xử lý sự cố thường gặp