Quản lý đơn hàng

1. Thực thể

Đơn hàng: Được tạo sau khi thanh toán. 1 đơn hàng có thể chứa nhiều sản phẩm.

Kiện hàng: Được tạo sau khi đơn hàng được tạo. Đây là đơn vị để vận chuyển. 1 đơn hàng có thể được chia thành nhiều kiện hàng, và 1 kiện hàng có thể chứa nhiều sản phẩm.

Sản phẩm: Các sản phẩm riêng lẻ trong một đơn hàng, với số lượng và các chi tiết khác. Sản phẩm được đưa vào kiện hàng để vận chuyển.

2. Luồng trạng thái đơn hàng

3. Trạng thái thực hiện kiện hàng

4. Lấy danh sách và chi tiết đơn hàng

v2.order.get_order_list: Lấy danh sách đơn hàng theo trạng thái đơn hàng khác nhau.

v2.order.get_order_detail: Xem chi tiết đơn hàng.

5. Hủy đơn hàng

v2.order.cancel_order: Dùng cho người bán để hủy đơn hàng.

v2.order.handle_buyer_cancellation: Dùng để xử lý yêu cầu hủy đơn từ người mua.

6. Tách đơn hàng

6.1 Tách đơn

v2.order.split_order: Khi đơn hàng chứa nhiều sản phẩm, chức năng tách đơn có thể giúp bạn sắp xếp vận chuyển cho từng sản phẩm riêng theo mức độ sẵn sàng hoặc vị trí. Đơn hàng chỉ có thể được tách khi trạng thái đơn hàng là "READY_TO_SHIP"

Ví dụ yêu cầu API

Trong ví dụ này, đơn hàng chứa 6 sản phẩm và được chia thành hai kiện hàng

Json

{

    "order_sn": "2204215JYEEFW0",

    "package_list": [

        {

            "item_list": [

                {

                    "item_id": 1220089094,

                    "model_id": 0,

                    "order_item_id": 1220089094,

                    "promotion_group_id": 1051400341536827267

                }

            ]

        },

        {

            "item_list": [

                {

                    "item_id": 2436030646,

                    "model_id": 5074620257,

                    "order_item_id": 2436030646,

                    "promotion_group_id": 0

                },

                {

                    "item_id": 7348262532,

                    "model_id": 0,

                    "order_item_id": 7348262532,

                    "promotion_group_id": 0

                },

                {

                    "item_id": 13772515222,

                    "model_id": 0,

                    "order_item_id": 13772515222,

                    "promotion_group_id": 0

                },

                {

                    "item_id": 1229323224,

                    "model_id": 1434025516,

                    "order_item_id": 1229323224,

                    "promotion_group_id": 0

                },

                {

                    "item_id": 1229323224,

                    "model_id": 1434025517,

                    "order_item_id": 1229323224,

                    "promotion_group_id": 0

                }

            ]

        }

    ]

}

Lưu ý

Quyền tách đơn ở cấp shop. Nếu bạn nhận được lỗi "You don't have the permission to split order." khi gọi API v2.order.split_order, vui lòng liên hệ quản lý kinh doanh Shopee để đăng ký.
Các sản phẩm trong cùng chương trình Bundle deal và Add on deal không thể tách vào các kiện hàng khác nhau. Chỉ một số người bán được chọn mới có thể hỗ trợ tách Bundle deal hoặc chương trình Add on deal.
order_item_id của các sản phẩm trong API v2.order.get_order_detail giống nhau, nghĩa là chúng trong cùng Bundle deal, và add_on_deal_id giống nhau, nghĩa là chúng trong cùng Add on deal.
Nếu người mua mua nhiều hơn một sản phẩm có cùng item_id và model_id, đơn hàng không thể tách. Điều này có nghĩa là chúng tôi chỉ hỗ trợ tách ở cấp item và cấp model. Chỉ một số người bán được chọn mới có thể hỗ trợ tách các sản phẩm giống nhau.

Ví dụ: Nếu người mua mua điện thoại A (xanh) và điện thoại A (đỏ), đơn hàng có thể được tách thành hai kiện hàng. Nếu mua hai điện thoại A (xanh), bạn không thể tách chúng.

Khi tách đơn hàng, phải có ít nhất hai kiện trong một đơn hàng, tức là ít nhất hai yêu cầu item_list. Bạn có thể tách đơn hàng thành tối đa 30 kiện ở TW và tối đa 5 kiện ở các khu vực khác.
Khi tách đơn hàng, yêu cầu phải chứa tất cả sản phẩm trong đơn hàng.

6.2 Hủy tách đơn

v2.order.unsplit_order: Trạng thái đơn hàng phải là "READY_TO_SHIP" trước khi có thể hủy tách đơn. Nếu bất kỳ kiện hàng nào đã được giao, đơn hàng không thể tách nữa.

7. Lấy danh sách và chi tiết kiện hàng để vận chuyển

v2.order.search_package_list: Tìm kiếm danh sách kiện hàng chưa được SHIPPED để sắp xếp vận chuyển, với các bộ lọc và trường sắp xếp khác nhau. API này được ưu tiên để lấy kiện hàng để vận chuyển.

v2.order.get_package_detail: Xem chi tiết kiện hàng.

8. Luồng gọi API vận chuyển

8.1 Logic vận chuyển cơ bản

Lấy danh sách kiện hàng cần vận chuyển với package_status là 2 (ToProcess) thông qua API v2.order.search_package_list.
Gọi API v2.logistics.get_shipping_parameter để lấy tham số vận chuyển cho kiện hàng đơn (hoặc gọi API v2.logistics.get_mass_shipping_parameter để lấy hàng loạt tham số vận chuyển cho nhiều kiện hàng trong cùng kênh logistics và kho hàng). Người bán chọn một trong các phương thức vận chuyển pickup/dropoff/non_integrated để giao hàng. Gọi v2.logistics.ship_order để vận chuyển kiện hàng đơn (hoặc gọi v2.logistics.mass_ship_order để vận chuyển hàng loạt nhiều kiện hàng trong cùng kênh logistics và kho hàng). Đối với đơn hàng kênh non_integrated, nhà phát triển cần chuẩn bị mã theo dõi và tải lên trong body yêu cầu. Sau khi gọi API thành công, trạng thái thực hiện kiện hàng của chế độ pickup/dropoff sẽ tự động cập nhật từ LOGISTICS_READY thành LOGISTICS_REQUEST_CREATED. Đối với chế độ non_integrated, trạng thái thực hiện kiện hàng sẽ được cập nhật ngay lập tức thành LOGISTICS_PICKUP_DONE.
Sau khi vận chuyển thành công bằng kênh tích hợp Shopee, bạn có thể gọi API v2.logistics.get_tracking_number để lấy mã theo dõi cho kiện hàng đơn (hoặc gọi API v2.logistics.get_mass_tracking_number để lấy hàng loạt mã theo dõi cho nhiều kiện hàng).
Sau khi lấy mã theo dõi, bạn có thể in vận đơn. Bạn có thể chọn hai cách: tự in hoặc do Shopee tạo. Vận đơn chỉ có thể được in sau khi kiện hàng đã được sắp xếp vận chuyển thành công và trước khi trạng thái thực hiện kiện hàng là LOGISTICS_PICKUP_DONE.
Để lấy vận đơn do Shopee tạo, bạn cần gọi bốn API này theo thứ tự: v2.logistics.get_shipping_document_parameter，v2.logistics.create_shipping_document，v2.logistics.get_shippping_document_result，v2.logistics.download_shipping_document.
Logic vận chuyển đặc biệt tại TW:

a. Khi gọi API v2.logistics.get_shipping_parameter để lấy tham số vận chuyển, tham số slug được trả về, và tham số slug phải được tải lên khi gọi API v2.logistics.ship_order, nếu không việc vận chuyển sẽ thất bại.

b. Đối với kênh 黑猫宅急便(30001), không cần in vận đơn. 3PL sẽ cung cấp vận đơn và hoàn tất việc lấy hàng. Gọi v2.logistics.create_shipping_document sẽ báo lỗi: "The package can not print now."

8.2 Các API liên quan đến vận chuyển đơn hàng

API	Mô tả
v2.order.search_package_list	Lấy danh sách kiện hàng chưa vận chuyển
v2.order.get_package_detail	Lấy chi tiết kiện hàng
v2.logistics.get_shipping_parameter v2.logistics.get_mass_shipping_parameter	Lấy tham số vận chuyển
v2.logistics.ship_order v2.logistics.mass_ship_order	Sắp xếp vận chuyển
v2.logistics.get_tracking_number v2.logistics.get_mass_tracking_number	Lấy mã theo dõi
v2.logistics.get_shipping_document_data_info	Lấy thông tin cần thiết để tự in vận đơn
v2.logistics.get_shipping_document_parameter	Truy cập các loại vận đơn có thể chọn và được đề xuất
v2.logistics.create_shipping_document	Tạo tác vụ vận đơn
v2.logistics.get_shippping_document_result	Lấy kết quả tác vụ vận đơn
v2.logistics.download_shipping_document	Tải xuống vận đơn do Shopee tạo

8.3 Ví dụ yêu cầu API

8.3.1 v2.logistics.get_shipping_parameter

Ví dụ phản hồi:

Json

{

    "error": "",

    "message": "",

    "response": {

        "info_needed": {

            "dropoff": [],

            "pickup": [

                "address_id",

                "pickup_time_id"

            ]

        },

        "dropoff": {

            "branch_list": null

        },

        "pickup": {

            "address_list": [

                {

                    "address_id": 2826,

                    "region": "TH",

                    "state": "จังหวัดบึงกาฬ",

                    "city": "อำเภอเมืองบึงกาฬ",

                    "district": "",

                    "town": "",

                    "address": "222/58",

                    "zipcode": "38000",

                    "address_flag": [

                        "default_address",

                        "pickup_address",

                        "return_address"

                    ],

                    "time_slot_list": [

                        {

                            "date": 1639472400,

                            "pickup_time_id": "1639472400"

                        },

                        {

                            "date": 1639558800,

                            "pickup_time_id": "1639558800"

                        }

                    ]

                },

                {

                    "address_id": 3019,

                    "region": "TH",

                    "state": "จังหวัดกระบี่",

                    "city": "อำเภอคลองท่อม",

                    "district": "",

                    "town": "",

                    "address": "home 1234",

                    "zipcode": "81120",

                    "address_flag": [],

                    "time_slot_list": [

                        {

                            "date": 1639472400,

                            "pickup_time_id": "1639472400"

                        },

                        {

                            "date": 1639558800,

                            "pickup_time_id": "1639558800"

                        }

                    ]

                }

            ]

        }

    },

    "request_id": "33d8460efcd7313ac5b8337b54ff4b07"

}

Lưu ý: Trường info_needed chỉ ra phương thức vận chuyển được hỗ trợ bởi đơn hàng và các tham số cần tải lên khi bạn vận chuyển đơn hàng. Ví dụ này, đơn hàng hỗ trợ phương thức dropoff hoặc pickup. Nếu chọn phương thức dropoff, không cần tải lên tham số liên quan. Nếu chọn pickup, bạn cần tải lên tham số address_id và pickup_time_id. Nếu info_needed chỉ trả về dropoff, nghĩa là đơn hàng chỉ hỗ trợ dropoff.

8.3.2. v2.logistics.ship_order

Chọn phương thức pickup:

Khi tham số pickup được trả về bởi info_needed trong v2.logistics.get_shipping_parameter chứa address_id và pickup_time_id.

Json

{

    "order_sn": "2112132KQ1MK9N",

    "pickup": {

        "address_id": 2826,

        "pickup_time_id": "1639472400"

    }

}

Chọn phương thức dropoff

Khi tham số dropoff được trả về bởi info_needed trong v2.logistics.get_shipping_parameter là rỗng

Json

{

    "order_sn": "220301QQY0WASP",

    "dropoff": {}

}

Lưu ý: một số kênh dùng phương thức drop off trả về trực tiếp các trường rỗng, bạn cần truyền vào trường rỗng như ví dụ. Nếu có tham số khác được trả về, hãy tải lên các tham số đó, ví dụ:

Json

{
    "order_sn": "220301QQY0WASP",
    "dropoff": {
          "sender_real_name": "ABC"
  }
}

Chọn phương thức non_integrated

Khi tham số non_integrated được trả về bởi info_needed trong v2.logistics.get_shipping_parameter là tracking_number

Json

{
    "order_sn": "220301QQY0WASP",
    "non_integrated": {
        "tracking_number": "AK224200239740W"
    }
}

8.3.3 v2.logistics.update_shipping_order

Json

{
    "order_sn": "2112132KQ1MK9N",
    "pickup": {
        "address_id": 11178,
        "pickup_time_id": "1658563200"
    }
}

Dùng cho đơn hàng pickup để cập nhật address_id và pickup_time_id. Áp dụng cho đơn hàng ở trạng thái RETRY_SHIP.

9.

Liên quan đến đơn hàng

Q: Gọi API v2.order.get_order_detail và báo lỗi "Wrong parameters, detail: the order is not found."

A: Có thể kiểm tra FAQ này.

Q: Gọi API v2.order.get_order_detail, nhiều trường phản hồi bị thiếu, tôi phải làm gì?

A: Vui lòng kiểm tra xem trường response_optional_fields có được chọn để tải lên trường tương ứng không. Vui lòng tham khảo tài liệu API để biết chi tiết.

Liên quan đến vận chuyển

Q: Tại sao tôi không lấy được khung thời gian?

A: Nếu không lấy được, đơn hàng có thể đã được vận chuyển hoặc ship_by_day đã qua.

Q: Tôi nhận được lỗi "logistic status not ready to ship". Cần kiểm tra như thế nào?

A: Vui lòng gọi API v2.order.get_order_detail để lấy trạng thái đơn hàng. Chỉ đơn hàng có trạng thái READY_TO_SHIP mới có thể được vận chuyển.

Q: Gọi API v2.logistics.get_tracking_number nhưng không trả về first_mile_tracking_number, tôi cần làm gì?

A: Vui lòng kiểm tra xem trường response_optional_fields có được chọn để tải lên trường tương ứng không. Vui lòng tham khảo tài liệu API để biết chi tiết.

Liên quan đến vận đơn

Q: Gọi API v2.logistics.create_shipping_document, xuất hiện lỗi "Order status does not support awb printing".

A: Vui lòng gọi API v2.order.get_order_detail để lấy order_status. Chỉ hỗ trợ lấy khi order_status là PROCESSED.

Q: Gọi API v2.logistics.get_shipping_document_result và nhận trạng thái "PROCESSING", phải xử lý như thế nào?

A: Chúng tôi khuyến nghị gọi API theo vòng lặp cho đến khi nhận được trạng thái "READY".

Q: Có bao nhiêu loại tệp vận đơn?

A: Có ba định dạng：

Hầu hết vận đơn đơn hàng là tệp PDF.
Tất cả kênh C2C ở TW trả về vận đơn định dạng html. Kênh B2C ngoại trừ 7-ELEVEN (channel_id: 30005), Family Family (channel_id: 30006), Lai Erfu (channel_id: 30007), Family Family Frozen Super Pickup (không giao đến các đảo xa) (channel_id: 30011), OK Mart (channel_id: 30014) được in định dạng pdf, các kênh còn lại trả về html.
Nếu phương thức in được đặt trong seller center là in nhiệt, thư mục định dạng zip được trả về.

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

Trạng thái đơn hàng

UNPAID: Đơn hàng được tạo, người mua chưa thanh toán.
READY_TO_SHIP: Người bán có thể sắp xếp vận chuyển.
PROCESSED: Người bán đã sắp xếp vận chuyển trực tuyến và nhận mã theo dõi từ 3PL.
SHIPPED: Kiện hàng đã được giao cho 3PL hoặc được 3PL lấy.
TO_CONFIRM_RECEIVE: Đơn hàng đã được người mua nhận.
COMPLETED: Đơn hàng đã hoàn thành.
RETRY_SHIP: 3PL lấy hàng thất bại. Cần sắp xếp lại vận chuyển.
IN_CANCEL: Việc hủy đơn hàng đang được xử lý.
CANCELLED: Đơn hàng đã bị hủy.
TO_RETURN: Người mua yêu cầu trả hàng và việc trả hàng đang được xử lý.

Trạng thái kiện hàng

All: Lấy tất cả kiện hàng đang Pending, ToProcess hoặc Processed, giá trị 0.
Pending: Lấy kiện hàng chưa sẵn sàng để vận chuyển, giá trị 1.
ToProcess: Lấy kiện hàng cần sắp xếp vận chuyển, giá trị 2.
Processed: Lấy kiện hàng đã được sắp xếp vận chuyển, giá trị 3.

Lưu ý:

Trạng thái kiện hàng có tác dụng tương tự như bộ lọc Trạng thái đơn hàng trong tab To Ship trong Seller Center. Bảng ánh xạ giữa Trạng thái kiện hàng, Trạng thái thực hiện kiện hàng và bộ lọc Trạng thái đơn hàng trong Seller Center như sau:

Trạng thái kiện hàng	Trạng thái thực hiện kiện hàng	Bộ lọc trạng thái đơn hàng trong tab To Ship ở Seller Center
All (0)	LOGISTICS_NOT_START, LOGISTICS_READY, LOGISTICS_PICKUP_RETRY hoặc LOGISTICS_REQUEST_CREATED	All
Pending (1)	LOGISTICS_NOT_START	Pending
ToProcess (2)	LOGISTICS_READY hoặc LOGISTICS_PICKUP_RETRY	To Process
Processed (3)	LOGISTICS_REQUEST_CREATED	Processed

Trạng thái thực hiện kiện hàng / Trạng thái logistics

LOGISTICS_NOT_START: Trạng thái ban đầu, kiện hàng chưa sẵn sàng để thực hiện
LOGISTICS_READY: Kiện hàng sẵn sàng để thực hiện từ góc độ thanh toán. Đối với non-COD: đã thanh toán; đối với COD: đã qua kiểm tra COD
LOGISTICS_REQUEST_CREATED: Kiện hàng đã được sắp xếp vận chuyển
LOGISTICS_PICKUP_DONE: Kiện hàng đã được bàn giao cho 3PL
LOGISTICS_DELIVERY_DONE: Kiện hàng đã được giao thành công
LOGISTICS_INVALID: Đơn hàng bị hủy khi kiện hàng ở trạng thái LOGISTICS_READY
LOGISTICS_REQUEST_CANCELED: Đơn hàng bị hủy khi kiện hàng ở trạng thái LOGISTICS_REQUEST_CREATED
LOGISTICS_PICKUP_FAILED: Đơn hàng bị hủy bởi 3PL do lấy hàng thất bại hoặc đã lấy nhưng không thể tiếp tục giao hàng
LOGISTICS_PICKUP_RETRY: Kiện hàng đang chờ 3PL thử lấy hàng lại
LOGISTICS_DELIVERY_FAILED: Đơn hàng bị hủy do 3PL giao hàng thất bại
LOGISTICS_LOST: Đơn hàng bị hủy do 3PL làm mất kiện hàng

Lưu ý: Do logic cũ, trạng thái logistics kiện hàng trong get_order_detail sẽ trả về thêm 2 giá trị:

LOGISTICS_PENDING_ARRANGE: Logistics đơn hàng đang chờ sắp xếp
LOGISTICS_COD_REJECTED: Logistics tích hợp COD: Đơn hàng bị từ chối COD

Lý do hủy đơn hàng

OUT_OF_STOCK
UNDELIVERABLE_AREA

Lý do hủy

Out of Stock
Buyer Request to Cancel
Undeliverable Area
COD Unsupported
Parcel is Lost
Game Completed
Unpaid Order
Underpaid Order
Unsuccessful / Rejected Payment
Logistics Request is Cancelled
3PL pickup Fail
Failed Delivery
COD Rejected
Seller did not Ship
Transit Warehouse Cancelled
Other
Inactive Seller
Seller did not Ship
Auto Cancel
Logistic Issue
Your approver did not approve order on time.
You are unable to place order at the moment.
TBC

Lý do người mua hủy

Seller is not Responsive to buyer's Inquires
Seller ask Buyer to Cancel
Modify Existing Order
Product has Bad Reviews
Seller Takes too Long to Ship The Order
Seller is Untrustworthy
Others
Forgot to Input Voucher Code
Need to change delivery address
Need to Change Delivery Address
Need to input / Change Voucher Code
Need to Modify Order
Payment Procedure too Troublesome
Found Cheaper Elsewhere
Don't Want to Buy Anymore
Your approver rejected the order.
You are unable to place order at the moment.
Need to change delivery address
Too long delivery time
Modify existing order (color, size, voucher, etc)
Change of mind / others

Loại tài liệu vận chuyển

NORMAL_AIR_WAYBILL
THERMAL_AIR_WAYBILL
NORMAL_JOB_AIR_WAYBILL
THERMAL_JOB_AIR_WAYBILL

Trạng thái theo dõi logistics kiện hàng

（dành cho API get_tracking_info）

INITIAL
ORDER_INIT
ORDER_SUBMITTED
ORDER_FINALIZED
ORDER_CREATED
PICKUP_REQUESTED
PICKUP_PENDING
PICKED_UP
DELIVERY_PENDING
DELIVERED
PICKUP_RETRY
TIMEOUT
LOST
UPDATE
UPDATE_SUBMITTED
UPDATE_CREATED
RETURN_STARTED
RETURNED
RETURN_PENDING
RETURN_INITIATED
EXPIRED
CANCEL
CANCEL_CREATED
CANCELED
FAILED_ORDER_INIT
FAILED_ORDER_SUBMITTED
FAILED_ORDER_CREATED
FAILED_PICKUP_REQUESTED
FAILED_PICKED_UP
FAILED_DELIVERED
FAILED_UPDATE_SUBMITTED
FAILED_UPDATE_CREATED
FAILED_RETURN_STARTED
FAILED_RETURNED
FAILED_CANCEL_CREATED
FAILED_CANCELED

1. Thực thể

2. Luồng trạng thái đơn hàng

3. Trạng thái thực hiện kiện hàng

4. Lấy danh sách và chi tiết đơn hàng

5. Hủy đơn hàng

6. Tách đơn hàng

6.1 Tách đơn​

6.2 Hủy tách đơn​

7. Lấy danh sách và chi tiết kiện hàng để vận chuyển

8. Luồng gọi API vận chuyển

8.1 Logic vận chuyển cơ bản​

8.2 Các API liên quan đến vận chuyển đơn hàng​

8.3 Ví dụ yêu cầu API​

8.3.1 v2.logistics.get_shipping_parameter​

8.3.2. v2.logistics.ship_order​

8.3.3 v2.logistics.update_shipping_order​

9.

Liên quan đến đơn hàng​

Liên quan đến vận chuyển​

Liên quan đến vận đơn​

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

Trạng thái đơn hàng​

Trạng thái kiện hàng​

Trạng thái thực hiện kiện hàng / Trạng thái logistics​

Lý do hủy đơn hàng​

Lý do hủy​

Lý do người mua hủy​

Loại tài liệu vận chuyển​

Trạng thái theo dõi logistics kiện hàng​

6.1 Tách đơn

6.2 Hủy tách đơn

8.1 Logic vận chuyển cơ bản

8.2 Các API liên quan đến vận chuyển đơn hàng

8.3 Ví dụ yêu cầu API

8.3.1 v2.logistics.get_shipping_parameter

8.3.2. v2.logistics.ship_order

8.3.3 v2.logistics.update_shipping_order

Liên quan đến đơn hàng

Liên quan đến vận chuyển

Liên quan đến vận đơn

Trạng thái đơn hàng

Trạng thái kiện hàng

Trạng thái thực hiện kiện hàng / Trạng thái logistics

Lý do hủy đơn hàng

Lý do hủy

Lý do người mua hủy

Loại tài liệu vận chuyển

Trạng thái theo dõi logistics kiện hàng