Đơn vị vận chuyển
Hướng dẫn cấu hình kết nối API và quản lý các đơn vị vận chuyển (GHTK, Viettel Post, J&T Express, Ahamove, Be, SPX, Tự giao hàng) trên hệ thống OVIRO.
Trang Đơn vị vận chuyển (#/shippingcarrier) quản lý toàn bộ danh mục các đối tác giao vận được tích hợp trong hệ thống OVIRO. Doanh nghiệp có thể kết nối API với các hãng chuyển phát toàn quốc, dịch vụ giao hàng hỏa tốc nội thành, cổng vận chuyển trung gian hoặc thiết lập đội ngũ giao hàng nội bộ.
Vị trí truy cập trong Admin
Vào menu Cửa hàng > Đơn vị vận chuyển (Đường dẫn: #/shippingcarrier).
Tổng quan các nhà cung cấp API hỗ trợ
Hệ thống OVIRO hỗ trợ 7 loại cấu hình kết nối API vận chuyển:
| Nhà cung cấp | Loại hình giao vận | Phương thức kết nối API | Tính năng nổi bật |
|---|---|---|---|
| Giao hàng tiết kiệm (GHTK) | Toàn quốc / Liên tỉnh | Token API | Bắn đơn tự động, đồng bộ trạng thái, lấy hàng tận nơi |
| Viettel Post | Toàn quốc / Bưu chính | API Key & Secret | Hỗ trợ nhiều mã dịch vụ (VCN, VTK...), mạng lưới bưu cục rộng |
| J&T Express | Toàn quốc / TMĐT | EC Company ID & Private Key | Tùy chọn cước người gửi/người nhận, gói hàng FAST/EXPRESS/SUPER |
| Ahamove | Hỏa tốc nội thành | API Key & Mobile | Đặt xe máy/xe tải tức thì, trừ ví Balance hoặc tiền mặt |
| Giao hàng BE | Hỏa tốc nội thành | Client ID & Client Secret | Định vị tọa độ GPS (Lat/Long), giao 2h/4h, tùy chọn giao tận tay |
| SPX (SuperAI Gateway) | Đa đối tác chuyển phát | SuperAI Token & Carrier ID | Cổng kết nối tích hợp SPX, GHN, J&T, Viettel Post, BEST Express... |
| Tự giao hàng | Nội bộ doanh nghiệp | Không sử dụng API | Dành cho đội ngũ shipper riêng của shop hoặc khách đến lấy hàng |
Quy trình thêm đơn vị vận chuyển mới
- Tại màn hình Đơn vị vận chuyển, nhấn nút Thêm ở góc trên bên phải.
- Cửa sổ modal Thêm mới hiển thị:
- Nhập các trường thông tin chung:
- Tên: Tên hiển thị của đơn vị vận chuyển (ví dụ: GHTK HCM, Ahamove Giao Nhanh, ViettelPost Chi Nhánh 1).
- Thứ tự: Thứ tự ưu tiên hiển thị khi nhân viên chọn đơn vị vận chuyển trên đơn hàng (số nhỏ hơn xếp trước).
- Trạng thái: Chọn Có hiệu lực (sử dụng ngay) hoặc Ngừng hoạt động.
- Kết nối API: Chọn 1 trong 7 nhà cung cấp tương ứng.
- Sau khi chọn nhà cung cấp, form cấu hình kỹ thuật riêng của đơn vị đó sẽ xuất hiện phía dưới.
Hướng dẫn chi tiết cấu hình 7 đơn vị vận chuyển
1. Giao hàng tiết kiệm (GHTK)
Tích hợp cổng GHTK cho phép tự động đẩy đơn hàng sang hệ thống GHTK, lấy mã vận đơn và in phiếu giao hàng.
Các trường thông số:
| Trường thông tin | Loại dữ liệu | Giải thích |
|---|---|---|
| Is Sandbox? | Bật/Tắt | Bật khi đang chạy thử nghiệm với tài khoản test GHTK; tắt khi chạy môi trường thật. |
| Token | Text | Mã API Token bí mật do GHTK cấp trong trang quản trị iGHTK (Cài đặt tài khoản > Thông tin tài khoản). |
| Tên người liên hệ | Text | Tên nhân viên phụ trách giao hàng cho bưu tá tại kho lấy hàng. |
| Số điện thoại | Text | Số điện thoại liên hệ khi bưu tá đến lấy hàng hoặc trả hàng. |
| Email liên hệ | Text | Email nhận thông báo giao vận. |
| Địa chỉ lấy và trả hàng | Text | Địa chỉ kho/cửa hàng nơi bưu tá GHTK tới lấy kiện hàng. |
| Khu vực (Tỉnh/Huyện/Xã) | Region Picker | Chọn đúng Tỉnh/Thành phố, Quận/Huyện, Phường/Xã để GHTK tính cước chính xác. |
2. Viettel Post
Kết nối hệ thống bưu chính Viettel Post phục vụ các đơn giao toàn quốc và tuyến huyện xã vùng xa.
Các trường thông số:
| Trường thông tin | Loại dữ liệu | Giải thích |
|---|---|---|
| Is Sandbox? | Bật/Tắt | Chế độ kiểm thử qua môi trường test ViettelPost. |
| API Key | Password (ẩn) | Khóa API được cấp từ cổng nhà phát triển ViettelPost. |
| API Secret | Password (ẩn) | Khóa bí mật dùng để tạo chữ ký xác thực đơn hàng. |
| Mã dịch vụ | Text | Mã gói cước ViettelPost (ví dụ: VCN - Chuyển phát nhanh đường bộ, VTK - Tiết kiệm). |
| Thông tin người gửi | Text / Picker | Tên người gửi, số điện thoại, địa chỉ chi tiết và địa bàn Tỉnh/Huyện/Xã của điểm gửi. |
3. Giao hàng J&T Express
Tích hợp chuyên sâu với mạng lưới J&T Express thông qua kết nối doanh nghiệp (B2C / VIP).
Các trường thông số:
| Trường thông tin | Loại dữ liệu | Giải thích |
|---|---|---|
| Is Sandbox? | Bật/Tắt | Môi trường kiểm thử hoặc production. |
| Tên khách hàng (EC Company ID) | Text | Mã định danh công ty do J&T cấp (ví dụ: EHB). |
| Mã khách hàng (Customer Code) | Text | Mã khách hàng doanh nghiệp ký hợp đồng với J&T (ví dụ: 084LC02435). |
| Password | Text | Mật khẩu xác thực tài khoản J&T cấp riêng cho tài khoản API. |
| API Account | Text | Tài khoản gọi API kết nối. |
| Private Key | Password (ẩn) | Khóa bí mật dùng ký request xác thực dữ liệu. |
| Địa chỉ & SĐT người gửi | Text / Region | Địa chỉ lấy hàng và số điện thoại liên hệ bưu tá. |
| Hình thức thanh toán | Lựa chọn | - PP_PM: Người gửi trả cước theo tháng (hợp đồng công nợ).- PP_CASH: Người gửi trả tiền mặt khi gửi.- CC_CASH: Người nhận trả tiền cước. |
| Loại hàng hóa | Lựa chọn | Chọn gói dịch vụ: EXPRESS (Chuyển phát nhanh tiêu chuẩn), FAST (Nhanh) hoặc SUPER (Siêu tốc). |
4. Ahamove
Dịch vụ giao hàng hỏa tốc nội thành bằng xe máy hoặc xe tải, đáp ứng các đơn cần giao ngay trong 1 - 2 giờ.
Các trường thông số:
| Trường thông tin | Loại dữ liệu | Giải thích |
|---|---|---|
| Is Sandbox? | Bật/Tắt | Chế độ thử nghiệm với tài khoản Ahamove Sandbox. |
| API Key | Password (ẩn) | Mã khóa API lấy từ cổng Ahamove Developers. |
| Số điện thoại đăng ký | Text | Số điện thoại tài khoản doanh nghiệp Ahamove (định dạng quốc tế, ví dụ: 84778667225). |
| Mã dịch vụ | Lựa chọn | Chọn phương tiện giao hàng: SGN-BIKE / HAN-BIKE (xe máy giao nhanh) hoặc các gói xe tải. |
| Phương thức thanh toán | Lựa chọn | Chọn CASH (Tài xế thu tiền người gửi) hoặc BALANCE (Trừ trực tiếp vào số dư ví trả trước Ahamove). |
[!NOTE] Địa chỉ lấy hàng của Ahamove sẽ tự động lấy theo địa chỉ của kho hàng được chọn trên phiếu giao hàng trong OVIRO.
5. Giao hàng BE
Tích hợp nền tảng vận chuyển Be Delivery phục vụ giao hàng nội thành theo giờ với định vị tọa độ chính xác.
Các trường thông số:
| Trường thông tin | Loại dữ liệu | Giải thích |
|---|---|---|
| Is Sandbox? | Bật/Tắt | Môi trường thử nghiệm / thực tế. |
| Client ID & Client Secret | Password (ẩn) | Cặp thông tin định danh ứng dụng do đối tác Be Group cấp. |
| Webhook Auth Token | Password (ẩn) | Token xác minh các cuộc gọi webhook cập nhật tài xế từ BE về OVIRO. |
| Vĩ độ & Kinh độ (Lat/Long) | Text | Tọa độ GPS chính xác của điểm lấy hàng (ví dụ: Lat 10.7645743, Long 106.5980143) giúp tài xế BE di chuyển đúng vị trí cửa hàng/kho. |
| Loại dịch vụ | Lựa chọn | DELIVERY_INSTANT (Giao ngay tức thì), DELIVERY_2H (Giao trong 2 giờ) hoặc DELIVERY_4H (Giao trong 4 giờ). |
| Tùy chọn bổ sung | Checkbox | - Hàng cồng kềnh: Đánh dấu nếu kiện hàng có kích thước lớn cần xe chuyên dụng. - Gửi SMS cho khách hàng: BE gửi tin nhắn hành trình cho người nhận. - Giao hàng tận tay: Yêu cầu tài xế mang lên tận phòng/căn hộ. |
6. SPX (SuperAI Gateway)
Cổng kết nối đa hãng vận chuyển thông qua trung gian SuperAI, hỗ trợ tự động định tuyến hoặc chỉ định chuyển phát nhanh qua SPX Express, GHN, Viettel Post...
Các trường thông số:
| Trường thông tin | Loại dữ liệu | Giải thích |
|---|---|---|
| Token | Text | Mã token truy cập dịch vụ SuperAI Gateway. |
| Webhook Partner Code | Text | Mã đối tác dùng xác thực webhook thông báo hành trình bưu gửi. |
| Chỉ định nhà vận chuyển | Lựa chọn | Chọn đối tác cụ thể: SPX Express (Mã 10), GHN (Mã 2), J&T Express (Mã 3), Viettel Post (Mã 4), BEST Express (Mã 6), Lazada Express (Mã 14) hoặc để Mặc định (0) để hệ thống tự tối ưu. |
| Mã Gói Dịch Vụ | Number | Mã dịch vụ (ví dụ: 1 - Gói Tốc Hành). |
| Tùy chọn xem hàng | Number | Quy định kiểm tra hàng khi giao: - 1: Cho xem nhưng không cho thử.- 2: Cho thử hàng.- 3: Không cho xem hàng. |
| Người trả phí | Number | 1: Người gửi trả cước; 2: Người nhận trả cước. |
| Tùy chọn Đổi/Lấy hàng về | Number | Cấu hình chiều lấy hàng hoàn/đổi trả (ví dụ: 1). |
7. Tự giao hàng (Không sử dụng API)
Dành cho các đơn hàng do doanh nghiệp tự vận hành giao hàng:
- Đặc điểm: Chọn Kết nối API là Không sử dụng (
APITYPE_EMPTY). Không yêu cầu bất kỳ thông số kết nối nào. - Ứng dụng:
- Giao hàng bằng đội ngũ Shipper nội bộ của cửa hàng (quản lý phân công qua module Quản lý shipper).
- Khách đặt hàng trực tuyến và chọn hình thức Đặt trước đến lấy tại cửa hàng.
- Sử dụng các đơn vị vận tải ngoài hợp đồng (xe khách, chành xe, xe ôm truyền thống) cần ghi nhận thủ công.
Ứng dụng đơn vị vận chuyển trong hệ sinh thái OVIRO
Sau khi thiết lập đơn vị vận chuyển, các đơn vị này sẽ tự động tham gia vào 3 luồng vận hành chính:
1. Cài đặt phí giao hàng (Shipping Profile)
Nhấn liên kết ⚙️ Cài đặt phí giao hàng trên đầu trang (hoặc vào menu Website & App > Cài đặt phí giao hàng) để gắn đơn vị vận chuyển vào từng khu vực địa lý (nội thành, liên tỉnh) và định nghĩa bảng giá cước hiển thị cho khách khi mua sắm trên Website/App.
2. Xử lý đơn hàng (OMS Order Fulfillment)
Khi duyệt đơn hàng trong Bán hàng > Đơn hàng, nhân viên xử lý chọn đơn vị vận chuyển tương ứng:
- Nếu đơn vị có kết nối API: Hệ thống cung cấp nút Bắn đơn sang hãng, tự động tạo vận đơn trên hệ thống đối tác và nhận về mã theo dõi (Tracking Number), mã vạch in phiếu giao hàng.
- Trạng thái bưu kiện (Đang lấy hàng, Đang giao, Giao thành công, Chuyển hoàn) được tự động cập nhật về OVIRO qua Webhook.
3. Bán hàng đa kênh (Marketplace / Omnichannel)
Trong chi tiết từng kênh bán hàng (TikTok Shop, Shopee, iPOS.vn), quản trị viên có thể gán Đơn vị vận chuyển mặc định để đơn hàng đổ về từ sàn tự động phân bổ đúng hãng vận chuyển tương ứng.
Xử lý sự cố thường gặp
| Hiện tượng lỗi | Nguyên nhân khả dĩ | Cách khắc phục |
|---|---|---|
| Bắn đơn báo lỗi Token không hợp lệ / Hết hạn | API Token hoặc Secret Key bị nhập sai hoặc đối tác đã đổi mã mới | Đăng nhập tài khoản nhà vận chuyển, cấp lại Token mới và cập nhật lại trong cửa sổ cấu hình đơn vị. |
| Báo lỗi địa chỉ lấy hàng không tìm thấy | Mã Tỉnh/Huyện/Xã của OVIRO chưa khớp với danh mục vùng của đối tác | Kiểm tra lại mục Khu vực (Region Picker) trong cấu hình lấy hàng của hãng, đảm bảo chọn đủ 3 cấp Tỉnh - Huyện - Xã. |
| Giao hàng BE báo lỗi thiếu tọa độ | Thiếu Vĩ độ (Latitude) hoặc Kinh độ (Longitude) | Mở Google Maps, tìm địa chỉ kho/cửa hàng, copy cặp tọa độ GPS và điền vào 2 ô pickup_lat và pickup_long. |
| Trạng thái giao hàng không tự động nhảy | Webhook chưa được kích hoạt hoặc sai Auth Token | Kiểm tra cấu hình Webhook Token trên hệ thống đối tác đã trỏ đúng về địa chỉ tiếp nhận webhook của OVIRO. |