来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Logistics, Order, and Payment
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. [Only For BR]Add Inbound Pickup Address Type
1. [Only For BR]Add Inbound Pickup Address Type
To simplify the FBS inbound process for sellers on the Brazil (BR) marketplace, the platform has introduced a new Inbound Pickup Address (INBOUND_PICKUP_ADDRESS) type. Eligible sellers can configure this address type, allowing the platform to arrange logistics to pick up items from the specified address and deliver them to the warehouse.
This update enables sellers to manage this address type via Open API, including adding, updating, and deleting operations, ensuring a smooth FBS inbound process.
- New Address Type and Applicable Scope
(1) New Address Type: INBOUND_PICKUP_ADDRESS
(2) Applicable Sellers: This feature only applies to FBS sellers on the Brazilian site who have completed FBS invoicing settings and whose invoice type is Branch, allowing them to use their seller branch as an online pickup point for FBS inbound.
(3) API Updates and Parameter Details：
● Add Address: In the v2.logistics.set_address_config API, the address_type request parameter now includes a new enum value INBOUND_PICKUP_ADDRESS, allowing sellers to add an address of this type.
○ Example：
{
"address_type_config": [
{
"address_id": 123456,
"address_type": "INBOUND_PICKUP_ADDRESS"
}
]
}
● Query Address: In the v2.logistics.get_address_list API, the address_type response parameter now includes the INBOUND_PICKUP_ADDRESS enum value, allowing sellers to retrieve addresses of this type that have already been configured.
○ Example
{
"address_list": [
{
"address_id": 123456,
"address_type": "INBOUND_PICKUP_ADDRESS"
}
]
}
● Update Address: Support calling v2.logistics.update_address to update an existing address of type INBOUND_PICKUP_ADDRESS.
● Delete Address: Support calling v2.logistics.delete_address to delete an existing address of type INBOUND_PICKUP_ADDRESS.
- Related API Error Code Updates
To ensure correct configuration and usage of inbound pickup addresses, additional validation error codes are introduced for the related APIs.
| API | Error Message |
|---|---|
| v2.logistics.set_address_config v2.logistics.update_address | Cannot set inbound pickup address for this address. |
| Same as above | Inbound pickup address cannot be the same as Shopee warehouse address. |
| Same as above | Inbound pickup address invalid state & city, state&city must be the same as kyc.billing_address state&city or fbs_branch.billing_address state&city. |
Related APIs
v2.logistics.set_address_config
v2.logistics.get_address_list
v2.logistics.set_address_config
v2.logistics.update_address
v2.logistics.delete_address
Effective Date on Live
March 26, 2026
§3 2.[For ID]Support for Prescription Order Processing
2.[For ID]Support for Prescription Order Processing
- Background
To comply with the Ministry of Health regulations in the ID region regarding prescription drug operations, Shopee has fully upgraded the handling process for prescription orders and introduced buyer self-collection (Buyer Self-Collection) capabilities, and ensures that the full lifecycle of prescription orders from prescription approval to order fulfillment is compliant and fully traceable.
This document explains how to use Open API to query prescription order information, approve prescriptions, update self-collection status, and configure self-collection operating hours, including API call specifications, key parameter definitions, and business operation logic.
- Complete Prescription Order Handling Process
2.1 Retrieve Prescription Order List
Call v2.order.get_order_list to retrieve the list of orders.
2.2 Retrieve Order and Prescription Details
Call v2.order.get_order_detailor v2.order.get_package_detail to obtain detailed order information. The following fields are related to prescription drugs:
| Parameter | Description |
|---|---|
| is_prescription_item | Indicates whether the product is a prescription product (Only returned in v2.order.get_order_detail) |
| prescription_check_status | Prescription approval status, enumerated values: 0: NONE (Unapproved) 1: PASSED (Approved) 2: FAILED (Approved Rejected) (Only returned in v2.order.get_order_detail) |
| pharmacist_name | Name of the pharmacist who approved the prescription |
| prescription_images | Links to prescription images |
| prescription_approval_time | Timestamp when the prescription was approved |
| prescription_rejection_time | Timestamp when the prescription was rejected |
| prescription_reject_reason | Specific reasons for prescription rejection (Only returned in v2.order.get_order_detail) |
| consultation_id | Associated online consultation ID |
| is_buyer_shop_collection | Indicate whether the order is in the "buyer self-collection" mode |
| buyer_proof_of_collection | Link to the proof of purchase for in-shop pickup |
2.3 Prescription Approval Operation
Call the v2.order.handle_prescription_check API to perform manual approval for prescription orders.
All prescription orders must be approved before entering the fulfillment stage.
● When approving a prescription order, the pharmacist’s name (pharmacist_name) and the corresponding items information (items) must be provided.
● Approval rules:
○ is_approved = true: Prescription approved
○ is_approved = false: Prescription rejected, a rejection reason (reject_reason_code) must be provided:
-
Invalid prescription (forged / incorrect format)
-
Incorrect dosage
-
No prescription required for this medicine
-
Prescription image unclear
-
Other (Note: if reject_reason_code = 5, the free_text field is required to provide a detailed rejection reason)
2.4 Order Fulfillment & Delivery Management
Once the prescription is approved, the order enters the fulfillment stage.
Prescription orders support two fulfillment modes: standard delivery and pharmacy buyer self-collection.
The mode can be identified by the is_buyer_shop_collection field returned from v2.order.get_order_detail or v2.order.get_package_detail. Operation rules for each mode are as follows:
● Standard delivery mode: When is_buyer_shop_collection = false, operations follow the same logic as regular non-prescription orders.
● Pharmacy buyer self-collection mode: When is_buyer_shop_collection = true, the order fulfillment must be completed according to the self-pickup process. The seller needs to call the v2.logistics.update_self_collection_order_logistics to update the self-pickup order status. The corresponding status updates must be completed at both the ready_for_collection and order_collected stages. The core parameters are explained below:
| Parameter | Description |
|---|---|
| self_collection_logistics_action | Self-collection order status: ● ready_for_collection: items are ready for pickup ● order_collected: buyer has completed pickup |
| epoc_image_list | A list of image IDs for the buyer's pickup receipt. This is required when updating self_collection_logistics_action to order_collected. Note: A maximum of 3 image IDs can be passed. You can upload images using v2.media.upload_image with the parameters business = 1 and scene = 1 to obtain the corresponding image_id. |
| pin | The PIN code required for buyer pickup is mandatory when updating self_collection_logistics_action to order_collected. The seller must verify the buyer's PIN code before delivering the items and completing the status update. |
Additional information: For orders with buyer self-collection in the shop, the regular shipping interface cannot be used to arrange logistics. The fulfillment status must be updated through the v2.logistics.update_self_collection_order_logistics.
2.5 Configure Shop Self-Collection Operating Hours
To support pharmacy buyer self-collection, sellers can query and update shop operating hours through the following APIs:
● v2.logistics.get_operating_hour_restriction: The shop_collection_operating_hour_restrictions response parameter retrieves the platform-configured restrictions for store self-collection operating hours.
● v2.logistics.get_operating_hours: The shop_collection_operating_hour response parameter retrieves the currently active store self-collection operating hours configuration.
● v2.logistics.update_operating_hours: The shop_collection_operating_hour request parameter allows sellers to customize and update the store self-collection operating hours.
§4 3.[SG Only] BCRS Deposit Field Added to Payment APIs
3.[SG Only] BCRS Deposit Field Added to Payment APIs
Background
Starting 1 April 2026, Singapore’s National Environment Agency (NEA) will implement the Beverage Container Return Scheme (BCRS).
Under this scheme, all eligible pre-packaged beverages sold in plastic bottles and metal cans must include a refundable deposit of S$0.10 per container in the selling price. Buyers can get the deposit refunded by returning empty containers at designated return points.
Local SG sellers are required to include this deposit in product pricing, ensure proper labeling, and declare eligible products to NEA. As a regulated marketplace in Singapore, Shopee will support sellers in complying with these requirements and ensure pricing transparency.
Applicable Scope
SG local sellers only
Endpoints:
v2.payment.get_escrow_detail v2.payment.get_escrow_detail_batch
New Fields
| Field Path | Description | Value Type |
|---|---|---|
| order_income.bcrs_deposit | Total BCRS deposit paid by buyer (S$0.10 per container) | Final value, may be updated after return/refund or cancellation |
| order_income.items.bcrs_deposit | Item-level BCRS deposit (S$0.10 per container) | Initial value, will not be updated after return/refund or cancellation |
| buyer_payment_info.bcrs_deposit | BCRS deposit paid by buyer (S$0.10 per container) | Initial value, will not be updated after return/refund or cancellation |
Updated Fields
order_income.escrow_amount / order_income.buyer_total_amount now includes the BCRS deposit amount.
Effective Date
Lived
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§5 1. [Only For BR] 新增入库取货地址类型
1. [Only For BR] 新增入库取货地址类型
为了简化巴西站点 FBS 卖家的入库操作，平台新增了入库取货地址（INBOUND_PICKUP_ADDRESS） 类型，支持符合条件的卖家配置该类型的地址，以便平台安排物流从该地址取货并运送至仓库。
此次更新支持卖家通过 Open API 管理该类地址，包括新增、更新和删除操作，确保 FBS 入库流程顺畅。
- 新增地址类型及适用范围
（1）新增地址类型： INBOUND_PICKUP_ADDRESS
（2）适用卖家范围：仅适用于巴西站点已完成 FBS 发票设置，且发票开具类型为 Branch 的 FBS 卖家，允许他们将自己的卖家分支机构用作 FBS 入库的在线提货点。
（3）接口更新及参数说明：
● 新增地址：v2.logistics.set_address_config 接口里的 address_type 请求参数，新增 INBOUND_PICKUP_ADDRESS 枚举值，支持卖家新增该类型的地址
○ 示例：
{
"address_type_config": [
{
"address_id": 123456,
"address_type": "INBOUND_PICKUP_ADDRESS"
}
]
}
● 查询地址：v2.logistics.get_address_list 接口里的 address_type 响应参数，新增 INBOUND_PICKUP_ADDRESS 枚举值，支持卖家获取已配置的该类型地址
○ 示例：
{
"address_list": [
{
"address_id": 123456,
"address_type": "INBOUND_PICKUP_ADDRESS"
}
]
}
● 更新地址：支持调用 v2.logistics.update_address 更新已配置的 INBOUND_PICKUP_ADDRESS 类型地址
● 删除地址：支持调用 v2.logistics.delete_address 删除已配置的 INBOUND_PICKUP_ADDRESS 类型地址
- 相关功能 API 调用错误码更新
针对入库取货地址的设置与管理，相关功能 API 新增以下错误码校验。
| API | Error Message |
|---|---|
| v2.logistics.set_address_config v2.logistics.update_address | Cannot set inbound pickup address for this address. |
| Same as above | Inbound pickup address cannot be the same as Shopee warehouse address. |
| Same as above | Inbound pickup address invalid state & city, state&city must be the same as kyc.billing_address state&city or fbs_branch.billing_address state&city. |
影响的 API
v2.logistics.set_address_config
v2.logistics.get_address_list
v2.logistics.update_address
v2.logistics.delete_address
上线时间
2026 年 3 月 26 日
§6 2. [For ID] 处方药订单处理流程说明
2. [For ID] 处方药订单处理流程说明
- 背景与目标
为符合 ID 卫生部对处方药经营的监管合规要求，Shopee 对处方药订单的处理流程进行了全面升级，同时上线买家到店自提 (Buyer Self-Collection) 的履约配套能力，保障处方药订单从处方审批到履约完成的全流程合规、可追溯。
本文档将介绍如何通过 Open API 完成处方药订单的信息查询、处方审批、自提状态更新、自提营业时间配置等全流程操作，包括接口调用规范、关键参数说明及业务操作逻辑。
- 处方药订单完整处理流程
2.1 获取处方药订单列表
调用 v2.order.get_order_list，获取订单列表数据。
2.2 查询订单与处方药详情
调用 v2.order.get_order_detail、v2.order.get_package_detail接口，获取订单详细信息，其中与处方药相关的字段如下：
| 字段 | 说明 |
|---|---|
| is_prescription_item | 标识商品是否为处方商品 (仅 v2.order.get_order_detail 返回) |
| prescription_check_status | 处方审批状态，枚举值： 0: NONE (未审核) 1: PASSED (审批通过) 2: FAILED (审批驳回) (仅 v2.order.get_order_detail 返回) |
| pharmacist_name | 执行处方审批的药剂师姓名 |
| prescription_images | 处方凭证图片链接 |
| prescription_approval_time | 处方审批通过的具体时间 |
| prescription_rejection_time | 处方审批驳回的具体时间 |
| prescription_reject_reason | 处方审批驳回的具体原因 (仅 v2.order.get_order_detail 返回) |
| consultation_id | 关联的线上问诊单号 |
| is_buyer_shop_collection | 标识订单是否为“买家到店自提”模式 |
| buyer_proof_of_collection | 买家到店取货的凭证图片链接 |
2.3 处方审批操作
调用 v2.order.handle_prescription_check 接口，完成处方药订单的人工审批，所有处方药订单均需完成审批后，才能进入履约阶段。
● 审核处方药订单时，需同步传入药剂师姓名 (pharmacist_name) 及对应审批商品信息 (items)
● 审批规则：
○ is_approved = true：处方审批通过
○ is_approved = false：处方审批驳回，需传入拒绝原因 (reject_reason_code)，枚举值如下：
1: 无效处方 (伪造/格式错误)
2: 用量剂量不符
3: 该药品无需处方
4: 处方图片模糊不清
5: 其他原因 (注意：当 reject_reason_code = 5 时，free_text 字段必填，需补充详细的驳回原因)
2.4 订单履约与发货管理
处方审批通过后，订单进入履约发货环节。
处方药订单支持普通配送、药房到店自提两种模式，可以通过 v2.order.get_order_detail / v2.order.get_package_detail返回的 is_buyer_shop_collection 字段区分，不同模式操作规则如下：
● 普通配送模式：当 is_buyer_shop_collection = false 时，操作逻辑与平台常规非处方药订单一致
● 药房到店自提模式：当 is_buyer_shop_collection = true 时，需按自提流程完成订单履约，卖家需调用 v2.logistics.update_self_collection_order_logistics 接口更新自提订单状态，货品备好及买家完成取货两个节点，均需完成对应状态更新，核心参数说明如下：
| 参数 | 说明 |
|---|---|
| self_collection_logistics_action | 自提订单状态，枚举值说明： ● ready_for_collection：货品已备好，待买家取件 ● order_collected：买家已完成到店取货 |
| epoc_image_list | 买家取货凭证的图片 ID 列表，当更新 self_collection_logistics_action 为 order_collected 时必填 注意：最多支持传入 3 张图片 ID，可通过 v2.media.upload_image，传参 business = 1 和 scene = 1 上传图片，获取对应的 image_id |
| pin | 买家取件时需提供的 PIN 码，当更新 self_collection_logistics_action 为 order_collected 时必填 卖家需核实买家提供的 PIN 码无误后，才能交付货品并完成该状态更新 |
补充：对于“买家到店自提”的订单，不支持调用常规发货接口安排物流，必须通过 v2.logistics.update_self_collection_order_logistics接口完成履约状态更新。
2.5 配置门店自提营业时间
为配合药房到店自提流程，卖家可通过以下接口完成门店自提营业时间的查询与更新：
● v2.logistics.get_operating_hour_restriction：通过 shop_collection_operating_hour_restrictions 响应参数，查询门店自提营业时间的平台配置限制
● v2.logistics.get_operating_hours：通过 shop_collection_operating_hour 响应参数，获取店铺当前已生效的门店自提营业时间配置
● v2.logistics.update_operating_hours：通过 shop_collection_operating_hour 请求参数，自定义修改/更新店铺的门店自提营业时间
§7 3.[SG Only]Payment 接口新增 BCRS 押金字段
3.[SG Only]Payment 接口新增 BCRS 押金字段
背景
自 2026 年 4 月 1 日起，新加坡国家环境局（NEA）将正式实施饮料容器回收计划（BCRS）。
根据该政策，所有以塑料瓶及金属罐形式销售的符合条件的预包装饮料，需在售价中包含每个容器 S$0.10 的可退还押金。买家可通过指定回收点退回空容器以取回押金。
本地新加坡卖家需将该押金计入商品价格、完成标签标识，并向 NEA 申报相关商品。Shopee 作为本地合规平台，将支持卖家满足相关监管要求，并确保价格透明。
适用范围
仅限 SG 本地卖家
接口： v2.payment.get_escrow_detail v2.payment.get_escrow_detail_batch
新增字段
| 字段路径 | 字段说明 | 数值类型 |
|---|---|---|
| order_income.bcrs_deposit | 买家支付的 BCRS 总押金（每个容器S$0.10） | 最终值，可能在退货退款或取消后更新 |
| order_income.items.bcrs_deposit | 商品维度 BCRS 押金（每个容器S$0.10） | 初始值，退货退款或取消后不更新 |
| buyer_payment_info.bcrs_deposit | 买家支付的 BCRS 押金（每个容器S$0.10） | 初始值，退货退款或取消后不更新 |
变更字段
order_income.escrow_amount/buyer_total_amount已包含BCRS 押金金额。
生效日期
已上线