Dịch vụ vận chuyển là cầu nối giữa cửa hàng và đơn vị giao hàng (GHTK, Viettel Post, SPX, 247 Express...). Sau khi được cấu hình, dịch vụ vận chuyển được dùng để tính phí vận chuyển tối thiểu cho đơn hàng, gửi vận đơn sang đơn vị giao hàng và nhận lại trạng thái giao hàng qua đường dẫn gọi lại.
Bài viết đi theo thứ tự thiết lập: tìm trang quản lý dịch vụ vận chuyển trong admin, chọn dịch vụ mặc định, cấu hình thông tin kết nối, rồi nhân bản dịch vụ khi cần nhiều tài khoản với cùng một đơn vị giao hàng.

Dịch vụ vận chuyển đến từ đâu

E-Commerce không tự kết nối với đơn vị giao hàng nào. Mỗi dịch vụ vận chuyển là một phần mã được plugin cài thêm cung cấp, ví dụ plugin EzyDelivery cung cấp các dịch vụ GHTK, VIETTEL_POST, SPX, 247_EXPRESS. Vì vậy:
  • Danh sách dịch vụ gốc trong admin chính là các dịch vụ mà các plugin đã cài cung cấp, quản trị viên không tạo dịch vụ gốc từ giao diện.
  • Quản trị viên cấu hình thông tin kết nối (khoá, tài khoản, đường dẫn, phí tối thiểu...), bật/tắt từng dịch vụ và chọn một dịch vụ làm mặc định.
  • Muốn dùng cùng một đơn vị giao hàng với nhiều tài khoản khác nhau, quản trị viên nhân bản dịch vụ đó (xem phần Nhân bản dịch vụ vận chuyển).
Dịch vụ mặc định là dịch vụ hệ thống dùng khi không chỉ định dịch vụ nào khác:
  • Phí vận chuyển tối thiểu của dịch vụ mặc định là phí vận chuyển của đơn hàng trên website (quy đổi sang loại tiền của đơn hàng). Nếu ô Công thức tính chi phí vận chuyển đơn hàng trong menu Cài đặt có nội dung, phí được tính theo công thức đó, với phí tối thiểu là một tham số đầu vào.
  • Vận đơn được gửi sang dịch vụ mặc định khi tạo vận đơn mà không chọn dịch vụ.
  • Địa chỉ người nhận được ghép theo cấu hình Ánh xạ giữa kiểu và tiền tố địa giới hành chính của dịch vụ mặc định.

Mở trang quản lý dịch vụ vận chuyển

Trong admin, chọn E-Commerce > Các dịch vụ vận chuyển. Con số bên cạnh menu là số dịch vụ gốc đang có.
Menu Các dịch vụ vận chuyển
  1. Menu Các dịch vụ vận chuyển trong nhóm E-Commerce.

Danh sách dịch vụ vận chuyển gốc

Bảng đầu tiên của trang liệt kê các dịch vụ gốc do plugin cung cấp, sắp xếp theo mã. Dịch vụ chưa được cấu hình lần nào vẫn có trong bảng với trạng thái Chưa kích hoạt.
Danh sách dịch vụ vận chuyển gốc
  1. Mã và Tên của dịch vụ. Mã do plugin đặt và không đổi được. Bấm vào mã hoặc tên để xem chi tiết.
  2. Mặc định: dịch vụ mặc định hiển thị Đúng, các dịch vụ khác có liên kết Lựa chọn để đặt làm mặc định. Tại một thời điểm chỉ có một dịch vụ mặc định (tính cả dịch vụ nhân bản).
  3. Trạng thái của dịch vụ: Đã kích hoạt hoặc Chưa kích hoạt.
  4. Các hành động: xem chi tiết (biểu tượng con mắt), kích hoạt (biểu tượng máy bay giấy) hoặc ngừng kích hoạt (biểu tượng ngắt liên kết), và sửa. Nút kích hoạt/ngừng kích hoạt chỉ xuất hiện khi dịch vụ đã được lưu cấu hình ít nhất một lần.
Ô Tìm kiếm phía trên bảng lọc nhanh các dòng đang hiển thị.

Cấu hình một dịch vụ vận chuyển

Bấm biểu tượng sửa ở cột Các hành động để mở form Sửa dịch vụ vận chuyển. Ảnh dưới đây là form của dịch vụ VIETTEL_POST.
Form sửa dịch vụ vận chuyển
  1. Tên (bắt buộc, không trùng với dịch vụ khác): tên hiển thị của dịch vụ trong admin.
  2. Loại tiền phí vận chuyển và Phí vận chuyển tối thiểu (không được âm). Nếu dịch vụ này là mặc định, phí tối thiểu là phí vận chuyển của đơn hàng như mô tả ở phần đầu, được quy đổi theo tỉ giá khi đơn hàng dùng loại tiền khác.
  3. Giá trị hàng hoá mặc định và Dịch vụ giao hàng mặc định: các giá trị mặc định mà plugin cung cấp dịch vụ dùng khi tạo vận đơn, ví dụ giá trị hàng khai báo với đơn vị giao hàng hoặc mã gói dịch vụ của đơn vị giao hàng (giao nhanh, giao tiêu chuẩn...). Ý nghĩa cụ thể phụ thuộc vào từng đơn vị, hãy xem tài liệu của plugin cung cấp dịch vụ.
  4. Đường dẫn dịch vụ, Đường dẫn API dịch vụ và Đường dẫn gọi lại. Đường dẫn gọi lại mặc định là /delivery/callback/<mã dịch vụ>, dòng bên dưới là đường dẫn đầy đủ theo tên miền website. Bấm biểu tượng sao chép và khai báo đường dẫn này ở trang quản trị của đơn vị giao hàng để nhận cập nhật trạng thái vận đơn.
  5. Thông tin xác thực với đơn vị giao hàng:
    • Khoá máy khách và Khoá bí mật (token, API key... tuỳ đơn vị). Nút Ngẫu nhiên sinh một chuỗi 32 ký tự. Khoá bí mật được lưu riêng và hiển thị dạng che; khi lưu, hệ thống thử đăng nhập vào đơn vị giao hàng bằng khoá này và báo lỗi nếu khoá không hợp lệ.
    • Tên đăng nhập và Mật khẩu chỉ xuất hiện với các dịch vụ xác thực bằng tài khoản (như VIETTEL_POST, SPX, 247_EXPRESS). Khi lưu, hệ thống đăng nhập thử bằng tài khoản này và báo lỗi nếu sai.
  6. Ánh xạ giữa kiểu và tiền tố địa giới hành chính: danh sách JSON dạng [{"type": "PROVINCE", "prefix": "T."}, ...]. Mỗi phần tử gắn một tiền tố vào trước tên đơn vị hành chính có kiểu tương ứng khi ghép địa chỉ gửi sang đơn vị giao hàng, phù hợp với cách đơn vị đó nhận địa chỉ. Để trống nếu không cần.
  7. Trạng thái của dịch vụ.
Các trường còn lại:
  • Phiên bản: phiên bản API của đơn vị giao hàng, nếu đơn vị yêu cầu.
  • Logo và Băng rôn: ảnh đại diện của dịch vụ, chọn từ thư viện media. Khi chưa có logo, cột Logo của danh sách hiển thị ###.
Bấm Lưu để lưu cấu hình.

Nhân bản dịch vụ vận chuyển

Mỗi dịch vụ gốc chỉ có một bộ thông tin xác thực. Khi cửa hàng cần dùng cùng một đơn vị giao hàng với nhiều tài khoản, ví dụ mỗi kho hàng một tài khoản GHTK, hãy tạo dịch vụ nhân bản. Dịch vụ nhân bản dùng lại cách xử lý của một dịch vụ gốc (gọi là Dịch vụ xử lý) nhưng có mã, tên, khoá, tài khoản và trạng thái riêng.

Danh sách dịch vụ đã nhân bản

Bảng Các dịch vụ vận chuyển đã nhân bản nằm ngay dưới bảng dịch vụ gốc, trên cùng trang.
Danh sách dịch vụ vận chuyển đã nhân bản
  1. Thêm mới: mở form tạo dịch vụ nhân bản.
  2. Bộ lọc: Tìm kiếm theo từ khoá (mã, tên, dịch vụ xử lý), lọc theo Dịch vụ xử lý, Trạng thái và số dòng mỗi trang (Giới hạn).
  3. Dịch vụ xử lý: dịch vụ gốc mà dịch vụ nhân bản dùng lại.
Các cột và hành động còn lại giống bảng dịch vụ gốc, kể cả liên kết Lựa chọn để đặt dịch vụ nhân bản làm mặc định. Bảng có phân trang ở cuối.

Thêm dịch vụ nhân bản

Bấm Thêm mới để mở form Thêm dịch vụ vận chuyển. Ví dụ dưới đây tạo dịch vụ viettel-post-hn dùng lại cách xử lý của VIETTEL_POST với một tài khoản Viettel Post khác.
Form thêm dịch vụ vận chuyển
  1. Mã (bắt buộc, không trùng với mã của dịch vụ gốc hay dịch vụ nhân bản khác), Dịch vụ xử lý (bắt buộc, chọn một dịch vụ gốc) và Tên (bắt buộc, không trùng).
  2. Loại tiền phí vận chuyển và Phí vận chuyển tối thiểu riêng của dịch vụ nhân bản.
  3. Tên đăng nhập và Mật khẩu của tài khoản thứ hai. Hai ô này chỉ hiện ra khi Dịch vụ xử lý là dịch vụ xác thực bằng tài khoản.
Các trường còn lại giống form sửa ở phần trên. Bấm Lưu để tạo. Sau khi tạo, mã được giữ nguyên, còn Dịch vụ xử lý và các trường khác sửa được qua biểu tượng sửa.

Dùng dịch vụ vận chuyển với vận đơn

Sau khi dịch vụ được cấu hình và kích hoạt, vận đơn của các đơn hàng có sản phẩm cần vận chuyển được quản lý ở menu E-Commerce > Các vận đơn. Hệ thống không tự gửi vận đơn sang đơn vị giao hàng: quản trị viên chủ động gửi từ trang vận đơn, sau đó đơn vị giao hàng gọi Đường dẫn gọi lại để cập nhật trạng thái giao hàng. Chi tiết các thao tác xem ở bài Mô tả chi tiết tính năng quản lý vận đơn.

Tích hợp đơn vị giao hàng mới bằng lập trình

Khi cần một đơn vị giao hàng chưa có plugin, lập trình viên viết một plugin cung cấp dịch vụ vận chuyển mới. Phần này tóm tắt các bước, để dịch vụ mới xuất hiện tự động trong danh sách dịch vụ gốc ở trên.
  1. Thêm thư viện ecommerce-sdk vào plugin và viết một lớp cài đặt interface DeliveryService.
  2. Cài đặt các phương thức chính:
    • getCode(): mã dịch vụ, ví dụ MY_SHIPPING. Đây là mã hiển thị trong admin và là phần cuối của đường dẫn gọi lại mặc định.
    • deliver(...): gửi vận đơn sang đơn vị giao hàng từ cấu hình của dịch vụ và thông tin đơn hàng, trả về kết quả (mã vận đơn của đơn vị...).
    • cancelDeliveryOrderById(...): huỷ vận đơn ở đơn vị giao hàng, nếu đơn vị hỗ trợ.
    • verifyDeliveryCallbackParameters(...), extractDeliveryOrder(...) và verifyDeliveryResult(...): kiểm tra yêu cầu đơn vị giao hàng gửi về đường dẫn gọi lại, lấy thông tin vận đơn và trạng thái mới.
    • getTrackingDeliveryOrderUrl(...): đường dẫn tra cứu vận đơn trên trang của đơn vị giao hàng.
    • loginWithSecretKey(...), hoặc isAuthenticatedByUsernamePassword() trả về true cùng login(...): kiểm tra thông tin xác thực khi quản trị viên lưu cấu hình.
    • clone(newCode): trả về một bản sao của dịch vụ với mã mới. Chỉ khi cài đặt phương thức này, dịch vụ mới dùng được làm Dịch vụ xử lý cho dịch vụ nhân bản.
  3. Đăng ký lớp như một singleton của plugin. Khi plugin được cài và khởi động lại, dịch vụ xuất hiện trong danh sách với trạng thái Chưa kích hoạt.
  4. Cấu hình, kích hoạt và chạy thử với tài khoản thử nghiệm của đơn vị giao hàng trước khi đặt dịch vụ làm mặc định.

Lưu ý

  • Luôn có một dịch vụ vận chuyển mặc định đã cấu hình Phí vận chuyển tối thiểu nếu website bán sản phẩm cần vận chuyển, vì phí vận chuyển của đơn hàng lấy từ dịch vụ này.
  • Kiểm tra kỹ thông tin xác thực và Đường dẫn gọi lại với cấu hình ở trang quản trị của đơn vị giao hàng. Sai đường dẫn gọi lại, vận đơn vẫn được tạo nhưng trạng thái giao hàng không được cập nhật về website.
  • Không chia sẻ khoá bí mật và mật khẩu. Khi đổi mật khẩu ở đơn vị giao hàng, cập nhật lại trong admin ngay.
  • Dùng Ngừng kích hoạt thay vì xoá thông tin khi muốn tạm dừng một dịch vụ.