Giao hàng đơn sàn
Sắp xếp vận chuyển, in phiếu giao hàng và tra cứu vận đơn cho đơn Shopee, Lazada, TikTok Shop
Đơn sàn được giao bằng logistics của sàn (sàn gán đơn vị vận chuyển), không đi qua module Vận chuyển của Hubport. Sau mỗi thao tác, Hubport đồng bộ lại đơn để cập nhật trạng thái và mã vận đơn; kết quả đồng bộ trả trong trường sync (cùng cấu trúc với kết quả đồng bộ một đơn).
Đơn phải đã được nhập vào Hubport. Quyền: order.edit cho các thao tác giao hàng, setting.sale cho tra cứu vận đơn.
Shopee
Sắp xếp vận chuyển
POST /v1/ecomshopee/shiporder/:channelid/:ordersn
Hubport đọc tham số vận chuyển Shopee yêu cầu cho đơn và tự chọn: lấy hàng tận nơi (địa chỉ lấy hàng mặc định, khung giờ đầu tiên) hoặc gửi tại bưu cục. Body tuỳ chọn để chọn cụ thể:
| Trường | Kiểu | Mô tả |
|---|---|---|
method | string | dropoff để gửi tại bưu cục khi Shopee cho phép cả hai cách |
address_id | string | ID địa chỉ lấy hàng trên Shopee |
pickup_time_id | string | ID khung giờ lấy hàng |
branch_id | string | ID bưu cục (gửi tại bưu cục) |
sender_real_name | string | Tên người gửi (khi Shopee yêu cầu) |
tracking_number | string | Mã vận đơn (khi Shopee yêu cầu nhập tay) |
Response (HTTP 200), method là pickup, dropoff hoặc non_integrated:
{
"order_sn": "251013ABCDEF01",
"method": "pickup",
"tracking": { "tracking_number": "<TRACKING_NUMBER>", "hint": "", "pickup_code": "" },
"sync": { "order_sn": "251013ABCDEF01", "action": "updated", "order_id": 88010 }
}Lỗi riêng: error_shopee_pickup_address_not_found, error_shopee_pickup_time_slot_not_found, error_shopee_dropoff_branch_not_found (HTTP 422).
Mã vận đơn
GET /v1/ecomshopee/tracking/:channelid/:ordersn — trả { tracking_number, hint, pickup_code }.
Lazada
Đóng gói (pack)
POST /v1/ecomlazada/pack/:channelid/:orderid
Đóng gói các dòng hàng đang chờ của đơn rồi tải phiếu giao hàng (AWB) của các gói vừa tạo. Body tuỳ chọn: order_item_ids (array) để chỉ đóng gói một số dòng.
Response: { order_id, packed, failed, awb, sync } — HTTP 200 khi có ít nhất một dòng đóng gói được, ngược lại HTTP 422.
Sẵn sàng giao (ready to ship)
POST /v1/ecomlazada/rts/:channelid/:orderid
Báo sẵn sàng giao cho các gói đã đóng gói. Response: { order_id, ok, failed, sync } (HTTP 422 nếu không gói nào thành công). Lỗi error_lazada_no_packed_package nếu đơn chưa có gói đã đóng gói.
Phiếu giao hàng (AWB)
GET /v1/ecomlazada/awb/:channelid/:orderid
Trả trực tiếp file phiếu giao hàng (application/pdf hoặc text/html), header X-Package-Id cho biết gói. Đơn nhiều gói: query package_id để chọn gói (mặc định gói đầu). Lỗi: error_lazada_no_printable_package, error_lazada_awb_unavailable (HTTP 422).
TikTok Shop
Khung giờ bàn giao
GET /v1/ecomtiktokshop/handoverslots/:channelid/:orderid
Trả { package_id, can_pickup, can_drop_off, drop_off_point_url, pickup_slots: [{ start_time, end_time, avaliable }] }.
Giao gói hàng (ship package)
POST /v1/ecomtiktokshop/shiporder/:channelid/:orderid
| Trường | Kiểu | Mô tả |
|---|---|---|
package_id | string | Gói cần giao (mặc định gói đầu của đơn) |
method | string | drop_off để gửi tại điểm nhận; mặc định lấy hàng tận nơi |
pickup_start_time | string | Khung giờ lấy hàng (theo khung giờ bàn giao) |
tracking_number + shipping_provider_id | string | Người bán tự giao bằng đơn vị vận chuyển riêng |
method trả về: pickup, drop_off hoặc self_shipment.
Response:
{
"order_id": "<TIKTOK_ORDER_ID>",
"package_id": "<PACKAGE_ID>",
"method": "pickup",
"already_shipped": 0,
"tracking_number": "<TRACKING_NUMBER>",
"sync": { "channel_order_id": "<TIKTOK_ORDER_ID>", "action": "updated", "order_id": 88020, "exception": "" }
}Hubport chặn trước khi gọi TikTok: error_tiktokshop_order_not_ready_to_ship_unpaid / error_tiktokshop_order_not_ready_to_ship_on_hold (đơn chưa thanh toán / đang trong thời gian chờ), error_order_cancelled, error_tiktokshop_cancel_requested (người mua đang yêu cầu huỷ), error_tiktokshop_fbt_order (đơn do TikTok giao), error_tiktokshop_package_not_found (HTTP 422). Shop không có cách bàn giao khả dụng: error_tiktokshop_no_handover_method.
Phiếu giao hàng
GET /v1/ecomtiktokshop/shippingdocument/:channelid/:orderid
| Query | Mô tả |
|---|---|
document_type | SHIPPING_LABEL (mặc định), PACKING_SLIP, SHIPPING_LABEL_AND_PACKING_SLIP, SHIPPING_LABEL_PICTURE, HAZMAT_LABEL |
document_size | A6 (mặc định) hoặc A5 |
Hubport tải phiếu về, lưu vào kho file của công ty và trả: { order_id, package_id, tracking_number, file_id, file_path, file_url, size }.
Hành trình
GET /v1/ecomtiktokshop/tracking/:channelid/:orderid — trả { order_id, tracking_number, tracking: [{ description, update_time_millis, update_time, action_code }] }.
Error Codes chung
| Mã lỗi | Mô tả |
|---|---|
error_order_sn_invalid / error_order_id_invalid | Mã đơn không hợp lệ (HTTP 422) |
error_remote_order_not_found | Không tìm thấy đơn trên sàn (HTTP 422) |
error_not_found | Kênh (hoặc với TikTok Shop: đơn chưa nhập vào Hubport) không tồn tại / không thuộc công ty của bạn (HTTP 404) |
error_channel_disabled | Kênh đang tắt (HTTP 422) |
error_feature_requires_plan | Gói chưa có tính năng kết nối sàn (HTTP 402) |
error_shopee_api / error_lazada_api / error_tiktokshop_api | Lỗi do sàn trả về (HTTP 422) |
error_role_not_available | Không có quyền order.edit / setting.sale (HTTP 403) |