stable本次发布有变化全部展示
来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 v2.logistics.get_mass_shipping_parameter
Use this api to check if package support pickup, dropoff, non-integrated. For pickup, return address and pickup time id options. For dropoff, return branch id, sender real name, etc. Can batch request for packages under same product_location_id and logistics_channel_id. [Please call it when packages meet: 1) fulfillment status is LOGISTICS_READY; or 2) fulfillment status is LOGISTICS_PICKUP_RETRY; or 3) fulfillment status is LOGISTICS_REQUEST_CREATED and meet Instant Order Reschedule conditions]
§2 Overview
Overview
| Field | Value |
|---|---|
| Module | Logistics |
| API type | Shop |
| HTTP method | POST |
| Path | /api/v2/logistics/get_mass_shipping_parameter |
| Production URL | https://partner.shopeemobile.com/api/v2/logistics/get_mass_shipping_parameter |
| Sandbox URL | https://partner.test-stable.shopeemobile.com/api/v2/logistics/get_mass_shipping_parameter |
| Permission | ERP System; Seller In House System; Order Management; Swam ERP |
§3 Request parameters
Request parameters
| Name | Type | Required | Sample | Description |
|---|---|---|---|---|
| logistics_channel_id | int64 | No | 50021 | The API can only batch request the shipping parameter for multiple packages under the same product_location_id and same logistics_channel_id.; Use this field to specify the logistics_channel_id for the request. If not specified, will use the logistics_channel_id corresponds to the first package_number by default. |
| product_location_id | string | No | "VN0002BIZ" | The API can only batch request the shipping parameter for multiple packages under the same product_location_id and same logistics_channel_id.; Use this field to specify the product_location_id for the request. If not specified, will use the product_location_id corresponds to the first package_number by default. |
| package_list | object[] | Yes | The list of packages you want to get shipping parameters. limit [1, 50]. | |
| package_list.package_number | string | Yes | ["OFG188728166212046"] | Shopee's unique identifier for the package under an order. You shouldn't fill the field with empty string when there isn't a package number. |
§4 Response parameters
Response parameters
| Name | Type | Required | Sample | Description |
|---|---|---|---|---|
| request_id | string | 2880a5a28510424eaa3288fd941fae2c | The identifier for an API request for error tracking. | |
| error | string | error_auth | Indicate error type if hit error. Empty if no error happened. | |
| message | string | Invalid access_token. | Indicate error details if hit error. Empty if no error happened.<path></path><path></path> | |
| response | object | |||
| response.info_needed | object | The parameters required based on each specific order to Init. Must use the fields included under info_needed to call Init. For logistic_id 80003 and 80004, both Regular and JOB shipping methods are supported. If you choose Regular shipping method, please use "tracking_no" to call Init API. If you choose JOB shipping method, please use "sender_real_name" to call Init API. Note that only one of "tracking_no" and "sender_real_name" can be selected. | ||
| response.info_needed.dropoff | string[] | [] | Could contain 'branch_id', 'sender_real_name', or 'tracking_no'. If it contains 'branch_id', choose one to Init. If it contains 'sender_real_name' or 'tracking_no', should manually input these values in Init API. If it has empty value, developer should still include "dropoff" field in Init API. | |
| response.info_needed.pickup | string[] | ["address_id", "pickup_time_id"] | Could contain 'address_id' and 'pickup_time_id'. Choose one address_id and its corresponding pickup_time_id to Init. If it has empty value, developer should still include "pickup" field in Init API. It could contains "tracking_number" returned from "info_need"for some channels, please also add it when init. | |
| response.info_needed.non_integrated | string[] | Could contain 'tracking_no'. If it contains 'tracking_no', should manually input these values in Init API. If it has empty value, developer should still include "non-integrated" field in Init API. | ||
| response.dropoff | object | Logistics information for dropoff mode package. | ||
| response.dropoff.branch_list | object[] | List of available dropoff branches info. | ||
| response.dropoff.branch_list.branch_id | int64 | The identity of logistics branch. | ||
| response.dropoff.branch_list.region | string | The region of specify address. | ||
| response.dropoff.branch_list.state | string | The state of specify address. | ||
| response.dropoff.branch_list.city | string | The city of specify address. | ||
| response.dropoff.branch_list.address | string | The address description of specify address. | ||
| response.dropoff.branch_list.zipcode | string | The zipcode of specify address. | ||
| response.dropoff.branch_list.district | string | The district of specify address. | ||
| response.dropoff.branch_list.town | string | The town of specify address. | ||
| response.pickup | object | Logistics information for pickup mode package. | ||
| response.pickup.address_list | object[] | List of available pickup address info. For Multi-Warehouse sellers, note that changing pickup address from Current may incur higher shipping fees. | ||
| response.pickup.address_list.address_id | int64 | The identity of address. | ||
| response.pickup.address_list.region | string | The region of specify address. | ||
| response.pickup.address_list.state | string | The state of specify address. | ||
| response.pickup.address_list.city | string | The city of specify address. | ||
| response.pickup.address_list.district | string | The district of specify address. | ||
| response.pickup.address_list.town | string | The town of specify address. | ||
| response.pickup.address_list.address | string | The address description of specify address. | ||
| response.pickup.address_list.zipcode | string | The zipcode of specify address. | ||
| response.pickup.address_list.address_flag | string[] | The flag of shop address, applicable values: default_address, pickup_address, return_address, current_address (Multi-Warehouse sellers only) | ||
| response.pickup.address_list.time_slot_list | object[] | List of pickup_time information corresponding to the address_id.; Some logistics channels may not return any date or time for pickup time slots. In such cases, sellers can arrange shipment without selecting any time slot, and Shopee will arrange a suitable timing for these situations. | ||
| response.pickup.address_list.time_slot_list.date | timestamp | The date of pickup time. In timestamp. | ||
| response.pickup.address_list.time_slot_list.time_text | string | The text description of pickup time. Only applicable for certain channels. | ||
| response.pickup.address_list.time_slot_list.pickup_time_id | string | The identity of pickuptime. | ||
| response.pickup.address_list.time_slot_list.flags | string[] | ["recommended"] | This field will have the value “recommended” for the time slot that Shopee suggests sellers choose.; While it is advisable for sellers to choose the recommended time slot, they can also choose other time slots that do not have the recommended flag. | |
| response.success_list | object[] | Success package list. | ||
| response.success_list.package_number | string | Shopee's unique identifier for the package under an order. | ||
| response.fail_list | object[] | Fail package list. | ||
| response.fail_list.package_number | string | Shopee's unique identifier for the package under an order. | ||
| response.fail_list.fail_reason | string | Reason for failure. |
§5 Common parameters
Common parameters
| Name | Type | Required | Sample | Description |
|---|---|---|---|---|
| partner_id | int | 1 | Partner ID is assigned upon registration is successful. Required for all requests. | |
| timestamp | timestamp | 1610000000 | This is to indicate the timestamp of the request. Required for all requests. Expires in 5 minutes. | |
| access_token | string | c09222e3fc40ffb25fc947f738b1abf1 | The token for API access, using to identify your permission to the api. Valid for multiple use and expires in 4 hours. | |
| shop_id | int | 600000 | Shopee's unique identifier for a shop. Required param for most APIs. | |
| sign | string | e318d3e932719916a9f9ebb57e2011961bd47abfa54a36e040d050d8931596e2 | Signature generated by partner_id, api path, timestamp, access_token, shop_id and partner_key via HMAC-SHA256 hashing algorithm. More details: https://open.shopee.com/documents?module=87&type=2&id=58&version=2 |
§6 Request samples
Request samples
§7 Payload
Payload
{
"package_list": [
{
"package_number": "OFG188728166212046"
},
{
"package_number": "OFG189588735210225"
},
{
"package_number": "OFG190576613214356"
}
],
"logistics_channel_id": 50021,
"product_location_id": "VN0002BIZ"
}
§8 Response sample
Response sample
§9 JSON
JSON
{
"error": "",
"message": "",
"request_id": "e3e3e7f32bcee492460a0c6f610ab401:01000259bd426768:000000195ef6df10",
"response": {
"info_needed": {
"dropoff": [],
"pickup": [
"address_id",
"pickup_time_id"
]
},
"dropoff": {
"branch_list": null
},
"pickup": {
"address_list": [
{
"address": "112 Nguyễn Du",
"address_flag": [],
"address_id": 200000001,
"city": "Quận 1",
"district": "Phường Bến Thành",
"region": "VN",
"state": "TP. Hồ Chí Minh",
"time_slot_list": [
{
"date": 1737018000,
"pickup_time_id": "1737018000"
},
{
"date": 1737104400,
"pickup_time_id": "1737104400"
},
{
"date": 1737190800,
"pickup_time_id": "1737190800"
},
{
"date": 1737277200,
"pickup_time_id": "1737277200"
},
{
"date": 1737363600,
"pickup_time_id": "1737363600"
},
{
"date": 1737450000,
"pickup_time_id": "1737450000"
},
{
"date": 1737536400,
"pickup_time_id": "1737536400"
},
{
"date": 1737622800,
"pickup_time_id": "1737622800"
},
{
"date": 1737709200,
"pickup_time_id": "1737709200"
},
{
"date": 1737795600,
"pickup_time_id": "1737795600"
},
{
"date": 1737882000,
"pickup_time_id": "1737882000"
},
{
"date": 1737968400,
"pickup_time_id": "1737968400"
},
{
"date": 1738054800,
"pickup_time_id": "1738054800"
}
],
"town": "",
"zipcode": ""
},
{
"address": "capital place",
"address_flag": [],
"address_id": 200000012,
"city": "Quận Ba Đình",
"district": "Phường Liễu Giai",
"region": "VN",
"state": "Hà Nội",
"time_slot_list": [
{
"date": 1737018000,
"pickup_time_id": "1737018000"
},
{
"date": 1737104400,
"pickup_time_id": "1737104400"
},
{
"date": 1737190800,
"pickup_time_id": "1737190800"
},
{
"date": 1737277200,
"pickup_time_id": "1737277200"
},
{
"date": 1737363600,
"pickup_time_id": "1737363600"
},
{
"date": 1737450000,
"pickup_time_id": "1737450000"
},
{
"date": 1737536400,
"pickup_time_id": "1737536400"
},
{
"date": 1737622800,
"pickup_time_id": "1737622800"
},
{
"date": 1737709200,
"pickup_time_id": "1737709200"
},
{
"date": 1737795600,
"pickup_time_id": "1737795600"
},
{
"date": 1737882000,
"pickup_time_id": "1737882000"
},
{
"date": 1737968400,
"pickup_time_id": "1737968400"
},
{
"date": 1738054800,
"pickup_time_id": "1738054800"
}
],
"town": "",
"zipcode": ""
},
{
"address": "15 Lê Thánh Tôn",
"address_flag": [
"current_address"
],
"address_id": 200000014,
"city": "Quận 1",
"district": "Phường Bến Nghé",
"region": "VN",
"state": "TP. Hồ Chí Minh",
"time_slot_list": [
{
"date": 1737018000,
"pickup_time_id": "1737018000"
},
{
"date": 1737104400,
"pickup_time_id": "1737104400"
},
{
"date": 1737190800,
"pickup_time_id": "1737190800"
},
{
"date": 1737277200,
"pickup_time_id": "1737277200"
},
{
"date": 1737363600,
"pickup_time_id": "1737363600"
},
{
"date": 1737450000,
"pickup_time_id": "1737450000"
},
{
"date": 1737536400,
"pickup_time_id": "1737536400"
},
{
"date": 1737622800,
"pickup_time_id": "1737622800"
},
{
"date": 1737709200,
"pickup_time_id": "1737709200"
},
{
"date": 1737795600,
"pickup_time_id": "1737795600"
},
{
"date": 1737882000,
"pickup_time_id": "1737882000"
},
{
"date": 1737968400,
"pickup_time_id": "1737968400"
},
{
"date": 1738054800,
"pickup_time_id": "1738054800"
}
],
"town": "",
"zipcode": ""
},
{
"address": "167/2 Đ. Nguyễn Ảnh Thủ",
"address_flag": [],
"address_id": 200000016,
"city": "Quận 12",
"district": "Phường Trung Mỹ Tây",
"region": "VN",
"state": "TP. Hồ Chí Minh",
"time_slot_list": [
{
"date": 1737018000,
"pickup_time_id": "1737018000"
},
{
"date": 1737104400,
"pickup_time_id": "1737104400"
},
{
"date": 1737190800,
"pickup_time_id": "1737190800"
},
{
"date": 1737277200,
"pickup_time_id": "1737277200"
},
{
"date": 1737363600,
"pickup_time_id": "1737363600"
},
{
"date": 1737450000,
"pickup_time_id": "1737450000"
},
{
"date": 1737536400,
"pickup_time_id": "1737536400"
},
{
"date": 1737622800,
"pickup_time_id": "1737622800"
},
{
"date": 1737709200,
"pickup_time_id": "1737709200"
},
{
"date": 1737795600,
"pickup_time_id": "1737795600"
},
{
"date": 1737882000,
"pickup_time_id": "1737882000"
},
{
"date": 1737968400,
"pickup_time_id": "1737968400"
},
{
"date": 1738054800,
"pickup_time_id": "1738054800"
}
],
"town": "",
"zipcode": ""
}
]
},
"success_list": [
{
"package_number": "OFG190576613214356"
}
],
"fail_list": [
{
"fail_reason": "Package is not under the specified warehouse",
"package_number": "OFG188728166212046"
},
{
"fail_reason": "Package is not under the specified warehouse",
"package_number": "OFG189588735210225"
}
]
}
}
§10 Error example
Error example
§11 JSON
JSON
{
"error": "error_param",
"message": "Wrong parameters, detail: package_list is a required field.",
"request_id": "e3e3e7f32bcdbfc24afc49375711f401:010002dc3f97801d:00000004051285ee"
}
§12 Errors
Errors
| Error | Description | Solution |
|---|---|---|
| logistics.error_param | Duplicate package number | |
| logistics.lack_of_invoice_data | Please upload the invoice or verify the details of the document already submitted, which is currently flagged as invalid by SEFAZ. Correction is required to release the shipment. | |
| error_param | Package is not under the specified fulfilment channel | |
| logistics.error_param | Package is not under the specified warehouse | |
| logistics.invalid_address_version | Some addresses are no longer supported per new regulation, please update to avoid wrong fulfilment | |
| logistics.error_param | Package exceeds limit. | |
| error_data | parse data failed | |
| error_data | data not exist | |
| error_param | parameter invalid | |
| error_param | Shipping parameters can only be obtained when package is ready to be shipped | |
| error_param | The information you queried is not found. | |
| error_param | Wrong parameters, detail: {msg}. | |
| error_server | Something wrong. Please try later. | |
| error_shop | shopid is invalid | |
| logistics.no_available_time_slot | No available time slot | |
| logistics.no_supported_dropoff_branch | No supported drop-off branch | |
| logistics.no_supported_pickup_address | No supported pickup address | |
| logistics.no_valid_shipping_parameters | No valid shipping parameters. Please contact support | |
| error_param | request not from gateway | |
| error_param | Package cannot be rescheduled | |
| error_other | Rescheduling dependency error |
§13 Common errors
Common errors
| Error | Description | Solution |
|---|---|---|
| error_auth | partner_id is invalid | |
| error_auth | The App is deleted, and you'll be unable to make any API call. | |
| error_auth | App developer’s permissions for authorizations have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details. | |
| error_param | There is no partner_id in query. | |
| error_param | Invalid partner_id. | |
| error_param | no timestamp | |
| error_param | Invalid timestamp | |
| error_param | There is no sign in query. | |
| error_sign | Wrong sign. | |
| invalid_partner_id | Invalid partner_id, please have a check. | |
| error_auth | No permission to current api. | |
| error_api_call_restricted | The App permission for api call have been restricted. If you’re a seller, contact the developer for more information. If you’re the developer, refer to the Open Platform Console for details. | |
| api_suspended | The API is offline. Please call v2 API instead. | |
| error_limit | The total API call number made by your APP has reached the daily API call limit, please try again after 00: 00 (UTC+08:00) | |
| error_rate_limit | Too many requests. You have reached the rate limit. Please try again later. | |
| source_ip_undeclared | Request Source IP ({ip}) is undeclared. Please declare all your IP addresses in the Shopee Open Platform Console > App list > IP Address Whitelist | |
| error_param | Permission denied. This API is currently offline or the request path is incorrect. | |
| error_param | Partner_id is invalid, should be an integer between 0 and 4294967295. | |
| error_param | no timestamp. | |
| error_param | Timestamp is invalid, should be an integer between 0 and 4294967295. | |
| error_param | Timestamp is expired. | |
| error_partner_key_expired | Your API partner key has expired, please reset the Live API Partner Key in Console to get a new valid partner key to call open api. | |
| error_api_permission | This app type has no permission to this API. | |
| error_param | There is no access_token in query. | |
| error_auth | Invalid access_token. | |
| error_auth | Invalid partner_id or shopid. | |
| shop_no_linked | Partner and shop has no linked. | |
| shop_banned | The shop account has been banned. Permissions for shop authorization and API calls have been suspended until the shop account is restored. | |
| invalid_acceess_token | Invalid access_token, please have a check. | |
| partner_shop_no_link | Invalid partner_id or shop_id, please have a check. | |
| error_ashop_api_permission | The shop is Affiliate shop has no permission to call this API. | |
| error_kyc_auth | No permission. Please inform the seller to complete the Seller Registration on Shopee Seller Center first, then this shop can call for this API. | |
| error_auth | System error, please try again later. | |
| error_param | There is no shop_id in query. | |
| error_param | shop_id is invalid, should be an integer between 0 and 4294967295. |
§14 Update log
Update log
| Date | Change |
|---|---|
| 2026-03-13 | Support getting shipping parameter for Instant Order Reschedule Pickup |
| 2025-03-24 | Add "flags" response parameter under time_slot_list |
| 2025-02-24 | New API |