Chuyển tới nội dung chính

Shopee Xpress - Hướng dẫn tích hợp không đóng gói

1. Thuật ngữ​

  • Shopee Xpress - Không đóng gói: ID kênh logistics 30029
  • Unpackage sku id: Mã định danh mặt hàng duy nhất được dùng cho kênh logistics này.
  • Nhãn vận chuyển không đóng gói (Unpackage shipment label): Nhãn được dán lên mặt hàng khi vận chuyển qua kênh logistics này.
  • Nhãn TO (TO label): Nhãn được dán lên thùng carton vận chuyển khi giao hàng qua kênh logistics này.
  • Nhóm phân loại (Sorting group): Giá trị dùng để người bán đóng gói các mặt hàng lại với nhau khi vận chuyển qua kênh logistics này.

2. Logic hoạt động nghiệp vụ​

2.1 Tự động chia gói hàng

Đối với các đơn hàng có kênh logistics 30029, khi trạng thái đơn hàng chuyển thành "READY_TO_SHIP", hệ thống sẽ tự động chia đơn hàng thành nhiều gói dựa trên số lượng từng mặt hàng (cấp số lượng).

Ví dụ, nếu một đơn hàng gồm 3 chai trà sữa và 2 chai trà đen, hệ thống sẽ tự động chia thành 5 gói, mỗi gói chứa 1 đơn vị.

2.2 Quy trình sắp xếp giao hàng

Khi sử dụng kênh logistics 30029 để giao hàng, người bán không cần đóng gói theo cấp đơn hàng nữa. Các bước thực hiện là:

  1. Dán nhãn vận chuyển không đóng gói lên từng mặt hàng

  2. Đóng gói các mặt hàng vào thùng carton theo sorting_group và dán Nhãn TO lên thùng carton

Vui lòng tham khảo phần

3. Truy vấn Unpackaged SKU ID của mặt hàng​

Unpackaged SKU ID là mã định danh duy nhất cho mặt hàng trong kênh logistics này. Bạn có thể lấy thông tin qua API sau khi mặt hàng bật kênh logistics 30029:

4. Lấy thông tin và chi tiết đơn hàng​

Lưu ý: Kênh logistics 30029 tự động chia đơn hàng. Hãy đảm bảo lấy thông tin cấp gói hàng khi dùng các API sau để tránh bỏ sót chi tiết.

*Khi PackageFulfillmentStatus của các gói hàng có kênh logistics này chuyển thành "LOGISTICS_REQUEST_CREATED" (sau khi sắp xếp giao hàng), bạn có thể lấy giá trị trong trường "sorting_group".

5. Logic giao hàng cơ bản​

5.1 Luồng gọi API giao hàng

Lưu ý: Kênh logistics 30029 tự động chia đơn hàng, hãy đảm bảo "package_number" được đưa vào tham số yêu cầu cho các API sau.

  1. Lấy tham số giao hàng: Gọi API "v2.logistics.get_shipping_parameter" hoặc "v2.logistics.get_mass_shipping_parameter"
  2. Sắp xếp giao hàng: Gọi API "v2.logistics.ship_order" hoặc "v2.logistics.mass_ship_order"
  3. Lấy số tracking: Gọi API "v2.logistics.get_tracking_number"

5.2 Luồng lấy nhãn vận chuyển không đóng gói

Gọi các API sau theo thứ tự để lấy nhãn vận chuyển không đóng gói tương ứng với gói hàng:

  1. v2.logistics.get_shipping_document_parameter
  2. v2.logistics.create_shipping_document
  3. v2.logistics.get_shipping_document_result
  4. v2.logistics.download_shipping_document

Đơn hàng của kênh logistics này chỉ hỗ trợ "THERMAL_UNPACKAGED_LABEL" làm "shipping_document_type".

5.3 Luồng lấy Nhãn TO

Sau khi hoàn tất đóng gói theo nhóm phân loại, bạn có thể lấy tệp Nhãn TO qua API sau:

Lưu ý rằng mỗi Nhãn TO là duy nhất. Hãy đảm bảo mỗi Nhãn TO được lấy bằng cách gọi API này độc lập, vì danh sách đóng gói trùng lặp sẽ ảnh hưởng đến quá trình drop-off.

6. Các quy trình khác​

6.1 In trước nhãn vận chuyển không đóng gói trước khi tạo đơn hàng

Chúng tôi hỗ trợ in trước nhãn vận chuyển không đóng gói cho các mặt hàng ngay cả trước khi tạo đơn hàng, để dán nhãn và chuẩn bị trước.

Bạn có thể lấy tệp bằng cách gọi các API sau theo thứ tự:

  1. v2.logistics.create_shipping_document_job: Tạo tác vụ in
  2. v2.logistics.get_shipping_document_job_status: Lấy trạng thái tác vụ
  3. v2.logistics.download_shipping_document_job: Tải xuống các tệp nhãn

Lưu ý rằng mặt hàng phải bật kênh logistics 30029 để sử dụng quy trình gọi API này.

(*Kể từ ngày 12/01/2026, các shop phải sử dụng chế độ nhãn vận chuyển "Unpackaged sku id" để sử dụng quy trình này. Nếu shop đang sử dụng chế độ nhãn vận chuyển "Tracking Number", quy trình này sẽ không cung cấp nhãn sử dụng được.)

6.2 Tự thiết kế nhãn vận chuyển không đóng gói

Trong tùy chọn logistics này, chúng tôi khuyến nghị bạn thiết kế nhãn vận chuyển không đóng gói theo sở thích của người bán. Bạn có thể tham khảo thông số kỹ thuật phần "custom fields" trong tệp đính kèm của FAQ để tạo nhãn phù hợp với nhu cầu của từng người bán.

  • v2.logistics.get_shipping_document_data_info: Đối với các đơn hàng sử dụng logistics B2C, bạn có thể lấy các trường "unpackaged_sku_id" và "unpackaged_sku_id_qrcode" qua API này.

  • Hướng dẫn (chỉ để tham khảo, thông số kỹ thuật chính thức có trong FAQ trên trang web Open Platform)

  • Quy tắc tạo QR Code:

  • Không được phép dùng chế độ ECI.

  • Tránh nhúng khai báo UTF-8 hoặc mã hóa khác vào QR code.

  • Quy tắc hiển thị khu vực tùy chỉnh:

  • Đã bỏ giới hạn cỡ chữ và ngắt dòng.

  • Đảm bảo các khu vực tùy chỉnh không ảnh hưởng đến hiển thị hoặc bố cục của các khu vực không tùy chỉnh.

7. Luồng gọi API được đề xuất​

7.1 In nhãn vận chuyển không đóng gói sau khi tạo đơn hàng

7.2 In trước nhãn vận chuyển không đóng gói trước khi tạo đơn hàng

*Nếu shop đang sử dụng chế độ nhãn vận chuyển "Tracking Number", quy trình này không thể sử dụng được.

8.​

Q: Đối với các đơn hàng trong kênh logistics này có nhiều gói hàng, khi trạng thái logistics của các gói khác nhau, trạng thái đơn hàng sẽ hiển thị như thế nào?

Đ: Vui lòng xem FAQ này để biết chi tiết: https://open.shopee.com/faq/510

—-—-—-—-—-—-

Q: Tại sao trường "shipping_carrier" ở cấp ngoài lại trống khi tôi lấy chi tiết đơn hàng qua API "v2.order.get_order_detail"?

Đ: Các đơn hàng trong kênh logistics này sẽ được tự động chia, và trường "shipping_carrier" ở cấp ngoài của API "v2.order.get_order_detail" sẽ không hiển thị giá trị. Vui lòng lấy trường "shipping_carrier" từ từng gói hàng trong "package_list".

—-—-—-—-—-—-

Q: Tại sao hệ thống trả về thông báo lỗi khi tôi gọi API Giao hàng hoặc API nhãn vận chuyển không đóng gói?

Đ: Kênh logistics này sẽ tự động chia đơn hàng. Hãy đảm bảo tham số trường "package_number" được đưa vào yêu cầu khi gọi các API liên quan đến logistics.

9. Định nghĩa dữ liệu

Vui lòng tham khảo trang Định nghĩa dữ liệu V2.0.