v2.global_product.init_tier_variation
POST/api/v2/global_product/init_tier_variationVia 360: POST https://partner.quantri360.com/v1/shopee/api/v2/global_product/init_tier_variation
Write endpoint — changes data on Shopee. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description
CHỈ NGƯỜI BÁN TRUNG QUỐC ĐẠI LỤC VÀ HÀN QUỐC: Khởi tạo hoặc chuyển cấu trúc phân loại của sản phẩm toàn cầu, tối đa hai tầng.
- HIỆN CHƯA GỌI ĐƯỢC QUA 360: đây là API cấp merchant, 360 hiện ký theo gian hàng nên Shopee trả
error_param"There is no merchant_id in query.". Cần dùng API này → liên hệ 360. - Thị trường áp dụng: Người bán Trung Quốc đại lục và Hàn Quốc. Không áp dụng shop nội địa VN.
- API GHI: thay đổi dữ liệu thật trên Shopee; cần key có quyền ghi (can_write) và gói mở module Sản phẩm. Chuyển cấu trúc phân loại và đặt giá, tồn cho cấu trúc mới.
- Tối đa hai tầng: ví dụ chỉ màu là một tầng, màu và kích cỡ là hai tầng. Có thể chuyển giữa không tầng, một tầng và hai tầng. Sau khi tạo sản phẩm, chờ ít nhất 5 giây trước khi tạo phân loại vì có thể có độ trễ.
Request
Endpoint
POST https://partner.quantri360.com/v1/shopee/api/v2/global_product/init_tier_variation
Authentication & shop
| Name | In | Type | Sample | Description |
|---|---|---|---|---|
| Authorization | header | header | Bearer q360_live_ab12cd34_… | Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand. |
| platform_shop_id | query | string | 100001 | Gian hàng (lấy ở GET /v1/platforms → shops[].platform_shop_id). BẮT BUỘC khi brand có > 1 gian hàng trên nền tảng; 360 bỏ tham số này trước khi chuyển tiếp. |
Request parameters
| Name | In | Type | Required | Sample | Description |
|---|---|---|---|---|---|
| global_model | body | object[] | Yes | [{"original_price": 100, "seller_stock": [{"location_id": "demo-location", "stock": 10}], "global_model_sku": "DEMO-MODEL", "tier_index": [0], "weight": 0.5, "dimension": {"package_height": 1, "package_length": 1, "package_width": 1}, "pre_order": {"days_to_ship": 3}}] | Danh sách phân loại, tối đa 50 phân loại. |
| global_model[].original_price | body | float | Yes | 100 | Giá gốc phân loại toàn cầu. |
| global_model[].seller_stock | body | object[] | No | [{"location_id": "demo-location", "stock": 10}] | Tồn kho người bán của sản phẩm toàn cầu. |
| global_model[].seller_stock[].location_id | body | string | No | demo-location | Mã vị trí tồn kho; bắt buộc nếu merchant có shop 3PF. Lấy danh sách vị trí qua v2.merchant.get_merchant_warehouse_location_list; có thể bỏ trống nếu chỉ có shop xuyên biên giới thông thường. |
| global_model[].seller_stock[].stock | body | int64 | Yes | 10 | Số lượng tồn kho. |
| global_model[].global_model_sku | body | string | No | DEMO-MODEL | SKU phân loại toàn cầu, tối đa 100 ký tự. |
| global_model[].tier_index | body | int32[] | Yes | [0] | Chỉ số tầng phân loại bắt đầu từ 0. Để chuyển từ một/hai tầng về không có tầng, gửi tier_variation=[], standardise_tier_variation=[], global_model[].tier_index=[] cùng original_price, seller_stock để đặt giá và tồn cho sản phẩm sau chuyển đổi. |
| global_model[].weight | body | float | No | 0.5 | Khối lượng phân loại toàn cầu (kg); bỏ trống dùng khối lượng sản phẩm. Nếu đặt dimension riêng thì bắt buộc đặt weight riêng. |
| global_model[].dimension | body | object | No | {"package_height": 1, "package_length": 1, "package_width": 1} | Kích thước phân loại toàn cầu; bỏ trống thì dùng kích thước sản phẩm toàn cầu. |
| global_model[].dimension.package_height | body | int32 | Yes | 1 | Chiều cao kiện của phân loại toàn cầu (cm). |
| global_model[].dimension.package_length | body | int32 | Yes | 1 | Chiều dài kiện của phân loại toàn cầu (cm). |
| global_model[].dimension.package_width | body | int32 | Yes | 1 | Chiều rộng kiện của phân loại toàn cầu (cm). |
| global_model[].pre_order | body | object | No | {"days_to_ship": 3} | Thông tin đặt trước của phân loại toàn cầu; bỏ DTS thì dùng DTS của sản phẩm toàn cầu. |
| global_model[].pre_order.days_to_ship | body | int32 | Yes | 3 | Số ngày chuẩn bị hàng; lấy phạm vi từ v2.product.get_dts_limit. |
| global_item_id | body | int64 | Yes | 100021 | Mã sản phẩm toàn cầu. |
| standardise_tier_variation | body | object[] | No | [{"variation_id": 100061, "variation_name": "Mẫu", "variation_group_id": 100061, "variation_option_list": [{"variation_option_id": 100061, "variation_option_name": "Mẫu", "image_id": "demo-image"}]}] | Phải có ít nhất một trong standardise_tier_variation và tier_variation. Để chuyển từ một/hai tầng về không có tầng, gửi cả hai danh sách rỗng, global_model[].tier_index=[] cùng original_price, seller_stock. |
| standardise_tier_variation[].variation_id | body | int32 | Yes | 100061 | Mã tầng phân loại chuẩn hóa. |
| standardise_tier_variation[].variation_name | body | string | No | Mẫu | Tên tầng phân loại chuẩn hóa. |
| standardise_tier_variation[].variation_group_id | body | int32 | No | 100061 | Mã nhóm tầng phân loại chuẩn hóa. |
| standardise_tier_variation[].variation_option_list | body | object[] | Yes | [{"variation_option_id": 100061, "variation_option_name": "Mẫu", "image_id": "demo-image"}] | Danh sách lựa chọn tầng phân loại chuẩn hóa. |
| standardise_tier_variation[].variation_option_list[].variation_option_id | body | int32 | Yes | 100061 | Mã lựa chọn tầng phân loại chuẩn hóa. |
| standardise_tier_variation[].variation_option_list[].variation_option_name | body | string | No | Mẫu | Giá trị lựa chọn tầng phân loại chuẩn hóa. |
| standardise_tier_variation[].variation_option_list[].image_id | body | string | No | demo-image | Mã ảnh lựa chọn tầng phân loại chuẩn hóa. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/shopee/api/v2/global_product/init_tier_variation" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"global_model":[{"original_price":100,"tier_index":[0],"seller_stock":[{"stock":10}]}],"global_item_id":100021,"standardise_tier_variation":[{"variation_id":100061,"variation_option_list":[{"variation_option_id":100061}]}]}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/shopee/api/v2/global_product/init_tier_variation",
params={},
json={
"global_model": [
{
"original_price": 100,
"tier_index": [
0
],
"seller_stock": [
{
"stock": 10
}
]
}
],
"global_item_id": 100021,
"standardise_tier_variation": [
{
"variation_id": 100061,
"variation_option_list": [
{
"variation_option_id": 100061
}
]
}
]
},
headers={"Authorization": f"Bearer {KEY}"},
timeout=60,
)
print(r.status_code)
print(r.json())Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/shopee/api/v2/global_product/init_tier_variation');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"global_model":[{"original_price":100,"tier_index":[0],"seller_stock":[{"stock":10}]}],"global_item_id":100021,"standardise_tier_variation":[{"variation_id":100061,"variation_option_list":[{"variation_option_id":100061}]}]}),
});
console.log(r.status, await r.json());PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/shopee/api/v2/global_product/init_tier_variation' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"global_model":[{"original_price":100,"tier_index":[0],"seller_stock":[{"stock":10}]}],"global_item_id":100021,"standardise_tier_variation":[{"variation_id":100061,"variation_option_list":[{"variation_option_id":100061}]}]}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;Response
Response fields (as returned by Shopee)
Kiểm error / message trước khi đọc kết quả; error rỗng mới là thành công.
| Name | Type | Sample | Description |
|---|---|---|---|
| request_id | string | d52ca43b277a4f9292fb8be658bfd33d | Mã request của Shopee để tra lỗi. |
| error | string | Mã lỗi Shopee; rỗng = thành công. | |
| message | string | Mô tả lỗi. | |
| warning | string | Cảnh báo. |
Response sample
{
"error": "",
"message": "",
"warning": "",
"request_id": "demo-request"
}
Shopee error codes (22)
Show
| Code | Meaning |
|---|---|
| add_on.add_on_deal_expired | Không sửa chương trình mua kèm đã hết hạn. |
| error_data | Dữ liệu không tồn tại hoặc không hợp lệ cho thao tác (vd mã không có, loại yêu cầu không cho phép). |
| error_param | Tham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào. |
| error_server | Lỗi hệ thống Shopee — thử lại sau ít phút. |
| error_auth | Ủy quyền gian hàng cho 360 đã hết hạn hoặc bị thu hồi (360 đã tự làm mới token một lần) — chủ gian hàng kết nối lại Shopee trong Partner. |
| error_busi_global_item_not_found | Không tìm thấy sản phẩm toàn cầu. |
| error_busi_global_item_sku_over_limit | SKU sản phẩm toàn cầu vượt giới hạn. |
| error_busi_global_item_price_should_bigger_than_zero | original_price phải lớn hơn 0. |
| error_duplicated_variation_option | Lựa chọn tầng phân loại bị trùng. |
| error_busi_global_tier_option_image_not_equal_to_tier_one_option | Số ảnh lựa chọn phân loại không bằng số lựa chọn của tầng phân loại. |
| error_inner | Lỗi hệ thống Shopee — thử lại sau. |
| error_permission | Gian hàng không có quyền xem dữ liệu này (vd yêu cầu trả / đơn không thuộc gian hàng). |
| error_param_validate | Thiết lập bán sỉ hoặc thị trường của merchant chưa hợp lệ; xem `message`. |
| error_update_item_price | Cập nhật giá sản phẩm không được chấp nhận; xem `message`. |
| error_busi | Merchant/gian hàng có nhiều kho; cần gửi location_id. |
| error_system_busy | Hệ thống đang bận; thử lại sau. |
| error_stock_less_then_min_limit | normal_stock/seller_stock nhỏ hơn giới hạn tối thiểu. |
| error_stock_bigger_then_limit | normal_stock/seller_stock lớn hơn giới hạn tối đa. |
| error_limit | Chạm hạn mức gọi Shopee trong ngày của kết nối — 360 trả kèm thời điểm thử lại; giảm tần suất gọi. |
| error_rate_limit | Gọi quá nhanh — chờ vài giây rồi gọi lại (360 cũng giới hạn theo key: 429 + Retry-After). |
| merchant_no_linked | Merchant chưa liên kết với 360. |
| partner_frozen | Ứng dụng kết nối đang bị tạm ngưng — liên hệ 360. |
Get started
- Sign up for Partner
- Enable a data type of the Sản phẩm group on the platform page
- Create an API key (tick the Shopee channel)
- Call it as in the examples above