来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Logistics
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. [ID Only] Support OTP Retrieval and Push Notification for Return to Seller Scenarios
1. [ID Only] Support OTP Retrieval and Push Notification for Return to Seller Scenarios
In the current return refund flow, when a parcel needs to be returned to the seller due to buyer rejection or failed delivery, the driver will initiate the Return to Seller (RTS) process. During this process, the driver is required to verify an OTP with the seller to complete the return confirmation.
Previously, the OTP was sent to the seller via SMS by default. However, in practice, some sellers were unable to receive the SMS due to invalid or outdated phone numbers, resulting in long waiting times for drivers and delays in the return process.
To improve the return experience for both sellers and drivers, Shopee now supports online retrieval of the return OTP. After this update, once a parcel enters the RTS process and the system generates the OTP, the OTP will be automatically pushed by the system. Sellers can also proactively retrieve the OTP via API, without relying on SMS, allowing them to provide the OTP to the driver more quickly, complete the return confirmation, and improve overall return handling efficiency.
Applicable scope: This feature only applies to orders under SPX Instant and SPX Sameday channel in the ID region.
The API updates are as follows:
- v2.logistics.get_tracking_info adds a new response field: return_code
When calling the v2.logistics.get_tracking_info API, sellers can retrieve the return_code field under the tracking_info object. This field is used to obtain the OTP required for return confirmation in RTS scenarios.
| Name | Type | Description |
|---|---|---|
| return_code | string | The OTP generated after the parcel enters the RTS process. Sellers need to provide this OTP to the driver to complete the return confirmation. Note: This field is only returned when the driver has initiated the return process to the seller. If the driver has not initiated the return process for the parcel, this field will be empty. |
2）package_info_push supports return_code field generation push notification
The change_fields in package_info_push notification adds the return_code enum value. The return_code field is also added under both the old and new objects to return the generated OTP information, helping sellers promptly detect that the OTP has been generated.
When a parcel triggers the RTS process and the system generates the OTP, the platform will proactively push a notification. At this time, the changed_fields array will contain "return_code", the return_code under the old object will be an empty string, and the return_code under the new object will be the generated OTP.
Example:
{
"order_sn": "260313ABC1234",
"package_number": "OFG111111111111",
"changed_fields": ["return_code"],
"old": {
"return_code": ""
},
"new": {
"return_code": "1234"
},
"update_time": 1773390722
}
Related APIs
v2.logistics.get_tracking_info
package_info_push
Effective Date on Live
April 24, 2026
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§3 1. [ID Only] 退货场景支持验证码查询与推送通知
1. [ID Only] 退货场景支持验证码查询与推送通知
在当前的退货流程中，若包裹由于买家拒收或无法完成交付导致需要退回给卖家时，司机将会发起退件 (Return to Seller，RTS) 流程，此时司机需要与卖家核实验证码以完成退件确认。
此前，该验证码默认通过短信发送至卖家手机号，但实际运行中发现，部分卖家因手机号不可用或未更新等原因无法接收短信，导致司机长时间等待、退件流程受阻。
为改善卖家与司机的退货体验，Shopee 已支持退货验证码的线上化获取。更新后，系统将在订单触发退件且系统生成验证码后自动推送验证码，卖家也可主动调用接口查询，无需依赖短信接收，从而更快地将验证码提供给司机，完成退件确认，提升退件流转效率。
适用范围：此功能仅适用于 ID 地区的SPX Instant和SPX Sameday渠道下的订单。
接口更新内容如下：
1）v2.logistics.get_tracking_info 接口新增 return_code 响应字段
卖家调用 v2.logistics.get_tracking_info 接口时，可在 tracking_info 对象下获取 return_code 字段，用于退件场景下主动查询需提供给司机的退货验证码。
| Name | Type | Description |
|---|---|---|
| return_code | string | 包裹进入 RTS 退件流程后生成的验证码，卖家需将该验证码提供给司机以完成退件确认。 注意：仅当司机已向卖家发起 RTS 退货流程时，此字段才会返回。如果司机尚未发起包裹退货流程，则此字段为空。 |
2）package_info_push支持 return_code 字段生成推送
package_info_push 通知中的 change_fields 新增 return_code 枚举值，同时 old 和 new 对象下分别新增 return code 字段，用于返回生成的验证码信息，帮助卖家及时感知验证码已生成。
当包裹触发退件流程且系统生成验证码后，平台将主动推送通知，此时 changed_fields 数组中将包含 "return_code"，且 old 对象下的 return_code 为空字符串，new 对象下的 return_code 为生成的验证码。
示例如下：
{
"order_sn": "260313ABC1234",
"package_number": "OFG111111111111",
"changed_fields": ["return_code"],
"old": {
"return_code": ""
},
"new": {
"return_code": "1234"
},
"update_time": 1773390722
}
影响接口
v2.logistics.get_tracking_info
package_info_push
上线时间
2026 年 4 月 24 日