订单管理

订单 (Order)：买家下单后生成的订单，1 个订单可以包含多个商品。

包裹 (Package)：订单生成后创建的发货单元，作为物流配送的实体。1 个订单可以拆分成多个包裹，1 个包裹也可以包含多个商品。

商品 (Item)：订单中的具体商品，包含数量及其他信息，商品会随包裹一起发货。

v2.order.get_order_list: 获取不同订单状态下的订单列表。

v2.order.get_order_detail: 查看订单详情。

v2.order.cancel_order: 用于卖家取消订单。

v2.order.handle_buyer_cancellation: 用于处理买家取消订单的申请。

6.1 拆单

v2.order.split_order：当一笔订单中包含多个商品的时候，拆单功能可以帮助您根据每个商品的准备情况和货物位置，分别安排发货。订单状态为"READY_TO_SHIP"才可以拆单。

请求体示例如下，在这个例子中，订单包含6个商品，被分成了两个包裹。

{
    "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
                }
            ]
        }
    ]
}

Tips

• 拆单权限为店铺维度，如果调用v2.order.split_order，提示"You don’t have the permission to split order.",请联系Shopee业务经理申请。
• 在同一个Bundle deal及add on deal活动下的商品不可拆分到不同的包裹。目前，只有部分白名单店铺支持拆分同一个Bundle deal及add on deal活动下的商品。v2.order.get_order_detail API中item的order_item_id 相同，表示在同一个Bundle deal，add_on_deal_id相同，表示在同一个add on deal。
• 如果买家购买多个相同规格的商品，则订单不能拆分。仅支持item level及model level的拆单。目前，只有部分白名单店铺支持拆分多个相同规格的商品至不同的包裹。 eg：可以拆分同一商品下不同的规格。例如：买家购买了手机A（蓝色）和手机A（红色）,则可以拆分为两个包裹。如购买两个手机A（蓝色）则不可拆。
• 拆单时，一个订单内需要至少有两个包裹，即至少有两个item_list。在TW地区，最多可以拆分为30个包裹，在TW以外的其他地区，最多可以拆分为5个包裹。
• 5.在请求拆单接口时，请求的item必须包含订单内所有的item，不可以将订单内的item分批请求。

6.2 取消拆单

v2.order.unsplit_order：订单状态为"READY_TO_SHIP"才可以取消拆单，如果有任一包裹已安排出货，则本次拆单无法取消。

v2.order.search_package_list：获取未发货的包裹列表，用于安排发货，支持多种筛选和排序条件。推荐使用此接口获取待发货包裹。

v2.order.get_package_detail：查看包裹详情。

8.1 基本步骤

1.调用v2.order.search_package_list，通过package_status为2 (ToProcess) 获取待发货包裹列表。

2.调用v2.logistics.get_shipping_parameter获取单个包裹的发货参数 (或调用v2.logistics.get_mass_shipping_parameter批量获取同一物流渠道和仓库下多个包裹的发货参数)，卖家可以选择pickup/dropoff/non_intergrated中的任一种发货方式发货。调用v2.logistics.ship_order对单个包裹进行发货 (或调用v2.logistics.mass_ship_order批量对同一物流渠道和仓库下的多个包裹进行发货)，对于非集成渠道的订单，卖家应该准备好运单号，并在请求体中输入。接口调用成功后，选择pickup/dropoff的包裹履约状态会自动从LOGISTICS_READY更新为LOGISTICS_REQUEST_CREATED。非集成渠道的包裹履约状态将立即更新为LOGISTICS_PICKUP_DONE。

3.使用Shopee集成渠道发货成功后，可轮询v2.logistics.get_tracking_number获取单个包裹的运单号 (或调用v2.logistics.get_mass_tracking_number批量获取多个包裹的运单号)。

4.获取到运单号后，即可打印面单。可选择自画面单或Shopee生成的面单两种方式，面单仅可在包裹发货成功后至包裹履约状态为LOGISTICS_PICKUP_DONE之前打印。

5.打印系统面单，需按顺序依次调用v2.logistics.get_shipping_document_parameter，v2.logistics.create_shipping_document，v2.logistics.get_shippping_document_result，v2.logistics.download_shipping_document这四个接口。

6.TW地区发货特殊逻辑

a.当调用v2.logistics.get_shipping_parameter API 取得发货参数时返回了slug参数，则调用v2.logistics.ship_order API时必须上传slug参数，否则发货会失败。

b.对于TW黑猫宅急便(30001)这条渠道，不需要打印面单。3PL将提供面单并完成取货。您调用v2.logistics.create_shipping_document会报错:"The package can not print now."

8.2 相关API

8.3 发货接口调用范例

8.3.1 v2.logistics.get_shipping_parameter

返参示例如下：

{
    "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"
}

Note: info_needed字段表示订单支持的发货方式，该示例订单支持dropoff或pickup发货，若选择dropoff方式，则无需传相关参数，若选择pickup方式，则需要传address_id和pickup_time_id参数。如果info_needed只返回了dropoff ，表示订单只支持dropoff。

8.3.2 v2.logistics.ship_order

1. 选择pickup发货：

当v2.logistics.get_shipping_parameter中info_needed返回的pickup参数中包含address_id以及pickup_time_id.

{
    "order_sn": "2112132KQ1MK9N",
    "pickup": {
        "address_id": 2826,
        "pickup_time_id": "1639472400"
    }
}

2. 选择dropoff发货：

当v2.logistics.get_shipping_parameter中info_needed返回的dropoff参数为空

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

注意：有些渠道的dropoff方法有直接返回空字段，需要传入空字段，如示例。如果返回了其他参数，则上传其他参数即可，例如

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

3. 选择非集成发货：

当v2.logistics.get_shipping_parameter中info_needed返回的non_integrated参数为tracking_number

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

8.3.3 logistics.update_shipping_order

用于pickup发货更新address_id以及pickup_time_id，适用于RETRY_SHIP状态的订单。

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

订单相关

1.调用v2.order.get_order_detail报错 "Wrong parameters, detail: the order is not found."需要怎么处理？

答：查看FAQ。

2.调用v2.order.get_order_detail接口返参，很多字段缺失，需要怎么处理？

答：请检查response_optional_fields字段是否选择上传对应字段，具体可参考API文档

发货相关

1.获取发货参数接口获取不到time slot怎么处理？

答：如获取不到，那该订单可能已过ship_by_day无法发货，只能联系买家重新下单。

2.发货提示"logistic status not ready to ship"。如何排查？

答:请调用v2.order.get_order_detail API获取订单状态。只有READY_TO_SHIP状态下的订单可发货。

3.调用v2.logistics.get_tracking_number接口，没有返回first_mile_tracking_number，需要怎么处理？

答：请检查response_optional_fields字段是否选择上传对应字段，具体可参考API文档

面单相关

1.调用v2.logistics.create_shipping_document API，提示"Order status does not support awb printing."需要怎么处理？

答：请调用v2.order.get_order_detail API获取order_status,仅支持order_status为PROCESSED下打印。

2.调用v2.logistics.get_shipping_document_result API获取到"PROCESSING"的result status怎么处理？

答：建议循环调用该接口，直到获取到"READY"状态。

3.Shopee系统面单打印有哪些格式？

答: 系统面单有三种格式。

• 大部分面单直接返回pdf文件
• TW C2C渠道均通过html返回面单，B2C渠道除了7-ELEVEN(channel_id:30005) ,全家(channel_id:30006) ,萊爾富(channel_id:30007)，全家冷凍超取(不寄送離島地)(channel_id:30011),OK Mart(channel_id:30014)打印格式为pdf,其他均通过html返回面单。
• 若在卖家中心设置的打印方式为热敏打印，则返回zip格式的文件夹。

订单状态 (Order Status)

• UNPAID：订单未支付
• READY_TO_SHIP：订单待发货
• PROCESSED: 卖家已经操作发货
• RETRY_SHIP：3pl揽收失败，需要重新重新发货
• SHIPPED：3pl揽收成功
• TO_CONFIRM_RECEIVE：等待买家确认签收
• IN_CANCEL：买家提交取消申请待处理
• CANCELLED：订单已取消
• TO_RETURN：买家提交退货申请待处理
• COMPLETED：订单已完成

包裹状态 (Package Status)

• All：获取所有处于 Pending、ToProcess 或 Processed 状态的包裹，值为 0。
• Pending：获取尚未准备好发货的包裹，值为 1。
• ToProcess：获取需要安排发货的包裹，值为 2。
• Processed：获取已完成发货安排的包裹，值为 3。

说明： 包裹状态与卖家中心“To Ship”标签页中的Order Status筛选效果一致。包裹状态 (Package Status)、包裹履约状态 (Package Fulfillment Status) 与卖家中心Order Status筛选之间的对应关系如下：

包裹履约状态 (Fulfillment Status) / 物流状态 (Logistics Status)

• LOGISTICS_NOT_START：初始状态，包裹尚未准备好履约
• LOGISTICS_READY：包裹从支付层面已准备好履约，即：非货到付款 (non-COD)：已支付；货到付款 (COD)：已通过货到付款审核
• LOGISTICS_REQUEST_CREATED：包裹已安排发货
• LOGISTICS_PICKUP_DONE：包裹已交由第三方物流（3PL）揽收
• LOGISTICS_DELIVERY_DONE：包裹已成功送达
• LOGISTICS_INVALID：订单在 LOGISTICS_READY 状态下被取消
• LOGISTICS_REQUEST_CANCELED：订单在 LOGISTICS_REQUEST_CREATED 状态下被取消
• LOGISTICS_PICKUP_FAILED：订单因 3PL 揽收失败或虽已揽收但无法继续配送而被取消
• LOGISTICS_PICKUP_RETRY：订单待 3PL 重新尝试揽收
• LOGISTICS_DELIVERY_FAILED：订单因 3PL 配送失败被取消
• LOGISTICS_LOST：订单因 3PL 丢失而被取消

注意：

由于历史逻辑原因，调用 get_order_detail 接口时，包裹的logistics_status还可能返回以下两个状态值：

• LOGISTICS_PENDING_ARRANGE：订单待分配物流
• LOGISTICS_COD_REJECTED：集成物流货到付款 (COD)：COD 审核未通过

订单取消原因-卖家

• OUT_OF_STOCK：缺货
• UNDELIVERABLE_AREA：无法配送

订单取消原因-订单

• 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

订单取消原因-买家

• 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

面单格式类型

• NORMAL_AIR_WAYBILL：普通
• THERMAL_AIR_WAYBILL：热敏
• NORMAL_JOB_AIR_WAYBILL：普通，仅针对某些特殊渠道
• THERMAL_JOB_AIR_WAYBILL：热敏，仅针对某些特殊渠道

包裹物流轨迹状态

（get_tracking_info API 的物流状态）

• 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