来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 [Important] Enhance package-level API capabilities to improve shipping efficienc
Dear Developer,
To address seller pain points in order fulfillment processes, such as shipment status identification, urgency assessment, and exception handling, we have upgraded our core order fulfillment APIs. The specific updates are as follows:
§2 1. Package Shipment Status Identification
1. Package Shipment Status Identification
v2.order.search_package_list and v2.order.get_package_detail add the is_shipment_arranged response parameter to identify whether a package has had shipment arranged, preventing duplicate processing or missed packages.
| Name | Type | Description |
|---|---|---|
| is_shipment_arranged | boolean | Only effective when the package's logistics_status/fulfillment_status is LOGISTICS_READY. This parameter further distinguishes between two scenarios: - true: Package shipment has been arranged (Seller has processed shipment, system is generating tracking number, not yet updated to LOGISTICS_REQUEST_CREATED, no duplicate action needed) - false: Package awaiting shipment arrangement (Seller hasn't processed shipment yet, shipping arrangement required) |
§3 2. Multi-dimensional Package Filtering
2. Multi-dimensional Package Filtering
v2.order.search_package_list adds the order_type, is_pre_order, and shipping_priority request parameters to filter packages, helping sellers process packages of different urgency levels more efficiently.
| Name | Type | Description |
|---|---|---|
| order_type | int32 | Filter packages by order type, applicable values below (default is 0: All): 0: All 1: Regular Order 2: Instant Order Note: For VN shops, using 2: Instant Order will return both Instant Delivery and Same-day Delivery packages. |
| is_pre_order | int32 | Filter packages by pre-order status, applicable values below (default is 0: All): 0: All 1: Non Pre-Order 2: Pre-Order |
| shipping_priority | int32 | Filter packages by shipping priority, applicable values below (default is 0: All): - For MY/PH/TW/TH shops, and VN Preferred/Preferred Plus/Shopee Mall shops: 0: All 1: Overdue 2: Ship by Today 3: Ship by Tomorrow - For other shops: 0: All 1: Overdue 2: Within 24h 3: Beyond 24h |
§4 3. Enhanced Package Detail Information
3. Enhanced Package Detail Information
v2.order.get_package_detail adds status_info_tag, can_split_order, can_unsplit_order, and is_pre_order response parameters to provide more package detail information, helping sellers plan shipping workflows more precisely.
| Name | Type | Description |
|---|---|---|
| status_info_tag | object | Package shipping urgency tag information |
| >tag_id | int32 | Shipping urgency tag type, applicable values below: 0: No tag 1: Will be cancelled within 1 day 2: Must ship before the specified timestamp 3: Shipment delayed 4: Must ship within the current hour 5: Will be cancelled at the specified timestamp |
| >timestamp | timestamp | When tag_id is 2 or 5, returns specific timestamp (e.g., cancel time, shipment deadline); otherwise returns 0 |
| can_split_order | boolean | Indicates whether the order supports splitting: - true: Support splitting, can call v2.order.split_order to execute - false: Does not support splitting |
| can_unsplit_order | boolean | Indicates whether the order supports unsplitting: - true: Support unsplitting, can call v2.order.unsplit_order to execute - false: Does not support unsplitting |
| is_pre_order | boolean | Indicates whether the order is a pre-order: - true: Pre-order - false: Non pre-order |
§5 4. Logistic Channel Service Type Identification
4. Logistic Channel Service Type Identification
v2.logistics.get_channel_list adds the service_type_identifier response parameter to identify logistics channel service types, helping sellers recognize Instant Delivery and Same-day Delivery for quick identification and processing of high-priority orders.
| Name | Type | Description |
|---|---|---|
| service_type_identifier | string | Logistics channel delivery service type identifier, applicable values below: - instant: Instant Delivery - same_day: Same-day Delivery |
§6 5. Package Information Update Push
5. Package Information Update Push
Add package_info_push notification mechanism automatically pushes updates when critical package information such as Ship By Date or Logistics Channel changes, ensuring sellers can respond promptly to changes and reduce fulfillment risks.
| Name | Type | Description |
|---|---|---|
| shop_id | int64 | Shop unique identifier |
| code | int32 | Push notification unique identifier |
| timestamp | timestamp | Message send time |
| data | object | Main push data |
| >order_sn | string | Order unique identifier |
| >package_number | string | Package unique identifier under order |
| >changed_fileds | string[] | Changed fields, applicable values below: - ship_by_date - logistics_channel_id Note: If both fields are updated, both values will be returned |
| >old | object | Original package Ship By Date and Logistics Channel information |
| >logistics_channel_id | int64 | Original Logistics Channel unique identifier |
| >ship_by_date | timestamp | Original Ship By Date |
| >new | object | New package Ship By Date and Logistics Channel information |
| >logistics_channel_id | int64 | New Logistics Channel unique identifier |
| >ship_by_date | timestamp | New Ship By Date |
| >update_time | timestamp | Change occurrence time |
§7 6. API Error Message Optimization
6. API Error Message Optimization
The following shipping-related APIs have been optimized with clearer error messages. Common failure scenarios now return specific error reasons to help sellers quickly identify issues and improve resolution efficiency.
| API | Issue | Error Message |
|---|---|---|
| v2.logistics.get_shipping_parameter v2.logistics.get_mass_shipping_parameter | Package not in LOGISTICS_READY status (Details reference: https://open.shopee.com/announcements/1303?category=3&is_top=false) | Shipping parameters can only be obtained when package is ready to be shipped |
| Same as above | No available pickup address | No supported addresses |
| Same as above | No available drop-off branch | No supported drop-off branch |
| Same as above | No available pickup timeslot (Request time exceeds Ship By Date, or no available pickup time before Ship By Date) | No available timeslot |
| Same as above | No valid shipping parameters available | No valid shipping parameters. Please contact support |
| v2.logisics.ship_order v2.logistics.mass_ship_order | Order contains multiple packages but request doesn't include package_number | Please request with package_number for this split order |
| Same as above | Insufficient stock at seller's pickup address | Failed to assign a warehouse with sufficient stock |
§8 7. Important Notice: Recommended to Prioritize Package-Level Status Management for Shipping Workflows
7. Important Notice: Recommended to Prioritize Package-Level Status Management for Shipping Workflows
Some developers still use order-level status to manage shipping workflows. However, in multi-package order scenarios, order-level status cannot accurately reflect the actual shipping progress of each package, potentially leading to missed shipments, incorrect shipments, or SLA calculation errors.
This Open API update's fulfillment capabilities are all designed based on the package level. To ensure shipping accuracy, we strongly recommend developers:
- Use package-level status (logistics_status/fulfillment_status) as the basis for determining the actual shipping progress of each package
- Manage the entire shipping workflow at the package level, from status checking, priority handling to exception monitoring—packages should be the minimum operational unit
If you haven't completed the package-level API and status integration yet, please refer to our previous announcement to complete the upgrade and avoid shipping issues caused by status misidentification.
尊敬的开发者，
为解决卖家在履约过程中的发货状态识别、紧急度判断、异常情况排查等痛点，提升卖家的发货效率与体验，我们对订单履约核心接口进行了升级优化。具体更新内容如下：
§9 1. 包裹发货状态识别
1. 包裹发货状态识别
v2.order.search_package_list和v2.order.get_package_detail新增is_shipment_arranged响应参数，用于标识包裹是否已安排发货，避免重复处理或遗漏。
| Name | Type | Description |
|---|---|---|
| is_shipment_arranged | boolean | 仅当包裹的logistics_status/fulfillment_status为LOGISTICS_READY时生效，用于进一步区分该状态下的两种场景： - true：表示包裹已安排发货 (卖家已操作发货，系统正在生成运单号，暂未更新为LOGISTICS_REQUEST_CREATED，无需重复操作) - false：表示包裹待安排发货 (卖家尚未操作发货，需执行发货安排流程) |
§10 2. 包裹多维度筛选
2. 包裹多维度筛选
v2.order.search_package_list新增order_type、is_pre_order、shipping_priority请求参数，支持按订单类型、预售状态、发货优先级进行筛选，帮助卖家更高效地处理不同紧急程度的包裹。
| Name | Type | Description |
|---|---|---|
| order_type | int32 | 按订单类型筛选包裹，枚举值如下 (默认值为0: All)： 0: All 1: Regular Order 2: Instant Order 注意：对于VN地区的店铺，使用2: Instant Order筛选包裹时，接口将会同时返回即时配送与当日达包裹 |
| is_pre_order | int32 | 按预售状态筛选包裹，枚举值如下 (默认值为0: All)： 0：All 1：Non Pre-Order 2：Pre-Order |
| shipping_priority | int32 | 按发货优先级筛选包裹，枚举值如下 (默认值为0: All)： - 对于MY/PH/TW/TH地区的店铺，以及VN地区的Preferred/Preferred Plus/Shopee Mall店铺，枚举值为： 0: All 1: Overdue 2: Ship by Today 3: Ship by Tomorrow - 对于其他店铺，枚举值为： 0: All 1: Overdue 2: Within 24h 3: Beyond 24h |
§11 3. 包裹详情信息补充
3. 包裹详情信息补充
v2.order.get_package_detail新增status_Info_tag、can_split_order、can_unsplit_order、is_pre_order响应参数，返回包裹的发货紧急度标签、拆分/取消拆分支持、预售标识等信息，帮助卖家更精准地规划发货流程。
| Name | Type | Description |
|---|---|---|
| status_info_tag | object | 包裹的发货紧急度标签信息 |
| >tag_id | int32 | 发货紧急度标签类型，枚举值如下： 0: 无标签 1: 将在1天内取消 2: 需在指定时间前发货，具体时间参见timestamp 3: 发货已延迟 4: 需在当前小时内发货 5: 将在指定时间取消，具体时间参见timestamp |
| >timestamp | timestamp | 当tag_id为2或5时，返回具体的时间戳 (如取消时间、发货截止时间)，其他情况返回0 |
| can_split_order | boolean | 标识订单是否支持拆分，枚举值如下： - true：支持拆分，可调用v2.order.split_order执行拆分操作 - false：不支持拆分 |
| can_unsplit_order | boolean | 标识订单是否支持取消拆分，枚举值如下： - true：支持取消拆分，可调用v2.order.unsplit_order执行取消拆分操作 - false：不支持取消拆分 |
| is_pre_order | boolean | 标识订单是否为预售订单，枚举值如下： - true：预售订单 - false：非预售订单 |
§12 4. 渠道服务类型标识
4. 渠道服务类型标识
v2.logistics.get_channel_list新增service_type_identifier响应参数，返回物流渠道的服务类型，帮助卖家识别即时配送、当日达等特殊服务类型，快速识别并处理高紧急度订单。
| Name | Type | Description |
|---|---|---|
| service_type_identifier | string | 物流渠道的配送服务类型标识，枚举值如下： - instant：即时配送 - same_day：当日达 |
§13 5. 包裹信息变更推送
5. 包裹信息变更推送
新增package_info_push推送，当包裹的发货截止时间或物流渠道等关键信息发生变更时，系统将主动推送更新，确保卖家能够及时响应变更，减少履约风险。
| Name | Type | Description |
|---|---|---|
| shop_id | int64 | 店铺的唯一标识 |
| code | int32 | 推送通知的唯一标识 |
| timestamp | timestamp | 消息发送的时间 |
| data | object | 主要推送数据 |
| >order_sn | string | 订单的唯一标识 |
| >package_number | string | 订单下包裹的唯一标识 |
| >changed_fields | string[] | 发生变更的字段，枚举值如下： - ship_by_date - logistics_channel_id 注意：若两个字段均更新，则同时返回两个值 |
| >old | object | 包裹原有的发货截止时间与物流渠道信息 |
| >logistics_channel_id | int64 | 原分配的物流渠道的唯一标识 |
| >ship_by_date | timestamp | 原有的发货截止时间 |
| >new | object | 包裹新的发货截止时间与物流渠道信息 |
| >logistics_channel_id | int64 | 新分配的物流渠道的唯一标识 |
| >ship_by_date | timestamp | 新的发货截止时间 |
| >update_time | timestamp | 发生变更的时间 |
§14 6. API错误提示优化
6. API错误提示优化
优化以下发货相关接口的错误提示，针对常见的失败场景返回明确的错误原因，帮助卖家快速定位问题，提升问题解决效率。
| API | Issue | Error Message |
|---|---|---|
| v2.logistics.get_shipping_parameter v2.logistics.get_mass_shipping_parameter | 包裹不处于待发货状态 (详情参考：https://open.shopee.com/announcements/1303?category=3&is_top=false) | Shipping parameters can only be obtained when package is ready to be shipped |
| Same as above | 无可用的取件地址 | No supported addresses |
| Same as above | 无可用的配送网点 | No supported drop-off branch |
| Same as above | 无可用的取件时段 (请求时已超过Ship By Date，或在Ship By Date时间前无可用的取件时间) | No available timeslot |
| Same as above | 无有效的发货参数 | No valid shipping parameters. Please contact support |
| v2.logisics.ship_order v2.logistics.mass_ship_order | 订单包含多个包裹，但请求未包含package_number | Please request with package_number for this split order |
| Same as above | 卖家使用的取件地址库存不足 | Failed to assign a warehouse with sufficient stock |
§15 7. 重要提示：建议优先采用包裹维度状态管理发货流程
7. 重要提示：建议优先采用包裹维度状态管理发货流程
目前仍有部分开发者使用订单维度的状态管理发货流程，但在多包裹订单场景下，订单维度的状态无法准确反映每个包裹的实际发货进度，可能导致漏发、误发或SLA判断错误等问题。
本次 Open API 更新的多项履约能力均基于包裹维度设计，为确保发货准确性，我们强烈建议开发者：
- 以包裹维度状态 (logistics_status/fulfillment_status) 作为每个包裹的实际发货进度判断依据
- 基于包裹维度管理发货全流程，从状态判断、优先级处理到异常监控，均应以包裹为最小操作单元
若您尚未完成包裹维度的接口与状态对接，可参考此前公告完成升级，避免因状态误判导致的发货问题。