stable本次发布有变化全部展示
来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Launch Instant Mart for Shopee Brazil Market
Dear Developers,
Please find below the OpenAPI updates released this time. These changes aim to enhance functionality, improve flexibility, and provide better integration support.
§2 1. Project Background
1. Project Background
Shopee Brazil officially launched the Instant Mart project, enabling sellers to operate with the Mart Shop and Outlet Shop structure, and introduced the Entrega Turbo (Channel ID: 90026) logistics channel to provide minute-level fulfillment for sellers capable of instant delivery.
Note: Other markets have already supported the Instant Mart model. ISVs can refer to the Instant Mart Integration Guide to understand the overall business model and API logic.
§3 2. Open API Updates Overview
2. Open API Updates Overview
To support this business model, the Open API has been updated as follows:
§4 2.1 Shop Information & Qualification Management
2.1 Shop Information & Qualification Management
| Update Type | API | API Function |
|---|---|---|
| New API | v2.shop.get_br_shop_onboarding_info | Retrieve KYC registration and qualification information for Outlet Shop |
| New API | v2.logistics.update_address | Update the address of a shop |
§5 2.2 Shop Service Area Settings
2.2 Shop Service Area Settings
| Update Type | API | API Function |
|---|---|---|
| New API | v2.logistics.upload_serviceable_polygon | Upload a KML file to set the delivery service area for Outlet Shop Note: Multiple Outlet Shops under the same Mart Shop cannot have overlapping service areas |
| New API | v2.logistics.check_polygon_update_status | Query the processing status and validation results of the uploaded KML file |
§6 2.3 Operating Hours & Holiday Settings
2.3 Operating Hours & Holiday Settings
| Update Type | API | API Function / Update Details |
|---|---|---|
| New API | v2.shop.get_shop_holiday_mode | Check whether a shop has enabled holiday mode |
| New API | v2.shop.set_shop_holiday_mode | Enable or disable holiday mode for a shop |
| Existing API Updates | v2.logistics.get_operating_hour_restrictions | The existing instant_operating_hour_restrictions response parameter supports Outlet Shops to get operating hour restrictions for instant delivery |
| Existing API Updates | v2.logistics.get_operating_hours | The existing instant_operating_hour response parameter supports Outlet Shops to get the current instant delivery operating hours |
| Existing API Updates | v2.logistics.update_operating_hours | The existing instant_operating_hour request parameter supports Outlet Shops to set instant delivery operating hours |
§7 2.4 Order Fulfillment & Logistics Tracking
2.4 Order Fulfillment & Logistics Tracking
| Update Type | API | API Function |
|---|---|---|
| Existing API Updates | v2.order.get_order_detail | 1) Update existing shipping_carrier response parameter logic for 90021 and 90026 channels to include service_code, e.g., Entrega Turbo - M1020 2) Add geolocation response parameter including latitude and longitude for buyer address coordinates |
| Existing API Updates | v2.order.get_package_detail | Same as above: Update existing shipping_carrier response parameter logic and add geolocation response parameters |
| Existing API Updates | v2.logistics.update_tracking_status | Add failed_reason request parameter, required when updating to logistics_delivery_failed. Applicable values: - buyer_unreachable - buyer_unresponsive - no_delivery_location_consensus |
| Existing API Updates | v2.logistics.ship_order v2.logistics.update_tracking_status | Update the Llogistics Status flow for 90021 and 90026 channels: Before: After arranging shipment, the Logistics Status was directly changed to LOGISTICS_PICKUP_DONE. Subsequently, when calling v2.logistics.update_tracking_status with logistics_status = logistics_pickup_done the Logistics Status remained unchanged as LOGISTICS_PICKUP_DONE. After: After arranging shipment, the Logistics Status will first update to LOGISTICS_REQUEST_CREATED. Only after calling v2.logistics.update_tracking_status with logistics_status = logistics_pickup_done will the Logistics Status be updated to LOGISTICS_PICKUP_DONE. Note: Please use v2.order.get_package_detail for more accurate tracking of package fulfillment status changes. |
§8 2.5 Product APIs Updates
2.5 Product APIs Updates
| Update Type | API | API Function |
|---|---|---|
| Existing API Updates | v2.product.add_item | Add new request parameters purchase_limit_info for sellers to set the maximum and minimum purchase quantities of products. purchase_limit_info >>min_purchase_limit >>max_purchase_limit >>purchase_limit Note: Currently, the maximum purchase quantity in the Open API only supports per-order settings, which is setting the maximum quantity that each buyer can purchase in a single order. |
| Existing API Updates | v2.product.update_item | Same as above: add purchase_limit_info request parameter |
| Existing API Updates | v2.product.get_item_base_info | Add new response parameters purchase_limit_info purchase_limit_info >>min_purchase_limit >>max_purchase_limit >>purchase_limit |
§9 3. Quotation API Updates Overview
3. Quotation API Updates Overview
For the Entrega Turbo (Channel ID: 90026) logistics channel, Shopee will call the seller’s API at order placement to obtain shipping fee quotes and delivery times. Sellers are required to return quotation information according to the new protocol.
Note: The Quotation API workflow has been previously supported in Brazil. ISVs can refer to the Quotation API (Entrega Expressa) Developer Guide to understand the business model and API logic.
Request Parameters (New):
| Name | Type | Required | Description | Update Type |
|---|---|---|---|---|
| channel_id | int | True | Logistics Channel ID in Shopee | New Param |
| destination_lat_long | object | True | Buyer address coordinates | New Param |
| >>latitude | float | True | Buyer address latitude | New Param |
| >>longitude | float | True | Buyer address longitude | New Param |
| items | object[] | True | List of items | Existing Param |
| >>model_sku | string | False | Model SKU | New Param |
Response Parameters (New/Updated):
| Name | Type | Description | Update Type |
|---|---|---|---|
| channel_id | int64 | Logistics Channel ID in Shopee | New Param |
| destination_lat_long | object | Buyer address coordinates | New Param |
| >>latitude | float | Buyer address latitude | New Param |
| >>longitude | float | Buyer address longitude | New Param |
| packages | object[] | List of packages | Existing Param |
| >>items | object[] | List of items | Existing Param |
| >>model_sku | string | Model SKU | New Param |
| >>category_id | int | Item Category ID | New Param |
| >>quotations | object[] | Shipping fee and delivery time info | Existing Param |
| >>handling_time | timestamp | Order preparation time in minutes | Existing Param, but format need update to minutes |
| >>shipping_time | timestamp | Order delivery time in minutes | Existing Param, but format need update to minutes |
| >>promise_time | timestamp | Total preparation + delivery time in minutes | Existing Param, but format need update to minutes |
| fallback_promise_time | timestamp | Average total preparation + delivery time in minutes as fallback | New Param |
尊敬的开发者，
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§10 1. 项目背景
1. 项目背景
Shopee 巴西市场正式推出 Instant Mart 项目，支持卖家建立 Mart Shop 与 Outlet Shop 结构的运营模式，并新增 Entrega Turbo (Channel ID: 90026) 物流渠道，为具备即时配送能力的卖家提供分钟级履约支持。
补充：其他地区已支持 Instant Mart 模式，可参考Instant Mart Integration Guide，了解整体的业务模式与接口逻辑。
§11 2. Open API 更新概览
2. Open API 更新概览
为支持该业务模式，现对 Open API 进行以下更新：
§12 2.1 店铺信息与资质管理
2.1 店铺信息与资质管理
| 更新类型 | 接口 | 接口功能 |
|---|---|---|
| 新增接口 | v2.shop.get_br_shop_onboarding_info | 获取 Outlet Shop 的 KYC 注册与资质信息 |
| 新增接口 | v2.logistics.update_addres | 更新店铺的地址信息 |
§13 2.2 店铺服务区域设置
2.2 店铺服务区域设置
| 更新类型 | 接口 | 接口功能 |
|---|---|---|
| 新增接口 | v2.logistics.upload_serviceable_polygon | 上传 KML 文件以设置 Outlet Shop 的配送服务区域 注：同一 Mart Shop 下的多个 Outlet Shop 不允许出现服务区域重叠 |
| 新增接口 | v2.logistics.check_polygon_update_status | 查询 KML 文件处理状态与校验结果 |
§14 2.3 运营时间与假期设置
2.3 运营时间与假期设置
| 更新类型 | 接口 | 接口功能 / 更新内容 |
|---|---|---|
| 新增接口 | v2.shop.get_shop_holiday_mode | 查询店铺是否开启假期模式 |
| 新增接口 | v2.shop.set_shop_holiday_mode | 设置店铺的假期模式开启/关闭状态 |
| 更新接口 | v2.logistics.get_operating_hour_restrictions | 已有的 instant_operating_hour_restrictions 响应参数，支持 Outlet Shop 获取即时配送的运营时间限制 |
| 更新接口 | v2.logistics.get_operating_hours | 已有的 instant_operating_hour 响应参数，支持 Outlet Shop 获取店铺当前设置的即时配送运营时间 |
| 更新接口 | v2.logistics.update_operating_hours | 已有的 instant_operating_hour 请求参数，支持 Outlet Shop 设置即时配送的运营时间 |
§15 2.4 订单履约与物流追踪
2.4 订单履约与物流追踪
| 更新类型 | 接口 | 更新内容 |
|---|---|---|
| 更新接口 | v2.order.get_order_detail | 1) 更新已有的 shipping_carrier 响应参数逻辑，对于 90021 和 90026 渠道包含 service_code，例如Entrega Turbo - M1020 2) 新增 geolocation 响应参数，包括 latitude 与 longitude，用于返回买家地址的地理坐标 |
| 更新接口 | v2.order.get_package_detail | 同上，更新已有的 shipping_carrier 响应参数逻辑，以及新增 geolocation 响应参数 |
| 更新接口 | v2.logistics.update_tracking_status | 新增 failed_reason 请求参数，用于配送失败时填写原因，更新为 logistics_delivery_failed 时必填，可选值如下： - buyer_unreachable - buyer_unresponsive - no_delivery_location_consensus |
| 更新接口 | v2.logistics.ship_order v2.logistics.update_tracking_status | 针对 90021 和 90026 渠道，更新 Logistics Status 状态机： 调整前：包裹在安排发货后，Logistics Status 直接变为 LOGISTICS_PICKUP_DONE，随后调用 v2.logistics.update_tracking_status 并传入 logistics_status = logistics_pickup_done 时，Logistics Status 将保持 LOGISTICS_PICKUP_DONE 不变。 调整后：包裹在安排发货后，Logistics Status 先变为 LOGISTICS_REQUEST_CREATED，随后调用 v2.logistics.update_tracking_status 并传入 logistics_status = logistics_pickup_done 时，Logistics Status 才会更新为 LOGISTICS_PICKUP_DONE。 注：请使用 v2.order.get_package_detail 以更准确地追踪包裹履约状态变化。 |
§16 2.5 商品接口更新
2.5 商品接口更新
| 更新类型 | 接口 | 更新内容 |
|---|---|---|
| 更新接口 | v2.product.add_item | 新增 purchase_limit_info 请求参数，用于卖家设置商品的最大和最小购买量。 purchase_limit_info >>min_purchase_limit >>max_purchase_limit >>purchase_limit 注：最大购买量在 Open API 目前仅支持依订单-即设置每个买家在每一笔订单中最多可购买的数量。 |
| 更新接口 | v2.product.update_item | 同上，新增 purchase_limit_info 请求参数 |
| 更新接口 | v2.product.get_item_base_info | 新增 purchase_limit_info 响应参数 purchase_limit_info >>min_purchase_limit >>max_purchase_limit >>purchase_limit |
§17 3. Quotation API 更新概览
3. Quotation API 更新概览
针对 Entrega Turbo (Channel ID: 90026) 物流渠道，Shopee 将在买家下单时回调卖家接口以获取即时配送运费与时效，卖家需按新协议返回相关报价信息。
补充说明：巴西地区此前已支持 Quotation API 流程，可参考Quotation API (Entrega Expressa) Developer Guide，了解整体的业务模式与接口逻辑。
请求参数 (新增)：
| 字段 | 类型 | 是否必填 | 说明 | 更新类型 |
|---|---|---|---|---|
| channel_id | int | True | Shopee 物流渠道 ID | 新增参数 |
| shop_id | int | True | 店铺 ID | 新增参数 |
| destination_lat_long | object | True | 买家地址的地理坐标 | 新增参数 |
| >>latitude | float | True | 买家地址纬度 | 新增参数 |
| >>longitude | float | True | 买家地址经度 | 新增参数 |
| items | object[] | True | 商品列表 | 已有参数 |
| >>model_sku | string | False | 商品变体 SKU | 新增参数 |
响应参数 (新增/变更)：
| 字段 | 类型 | 说明 | 更新类型 |
|---|---|---|---|
| channel_id | int64 | Shopee 物流渠道 ID | 新增参数 |
| destination_lat_long | object | 买家地址的地理坐标 | 新增参数 |
| >>latitude | float | 买家地址纬度 | 新增参数 |
| >>longitude | float | 买家地址经度 | 新增参数 |
| packages | object[] | 包裹列表 | 已有参数 |
| >>items | object[] | 商品列表 | 已有参数 |
| >>model_sku | string | 商品变体 SKU | 新增参数 |
| >>category_id | int | 商品类目 ID | 新增参数 |
| >>quotations | object[] | 配送运费与时效信息 | 已有参数 |
| >>handling_time | timestamp | 订单准备时长，单位为分钟 | 已有参数，但格式需更新为分钟 |
| >>shipping_time | timestamp | 订单准备时长，单位为分钟 | 已有参数，但格式需更新为分钟 |
| >>promise_time | timestamp | 订单准备与配送总时长 (handling_time + shipping_time)，单位为分钟 | 已有参数，但格式需更新为分钟 |
| fallback_promise_time | timestamp | 平均的订单准备与配送总时长，单位为分钟，作为备用值 | 新增参数 |