VI | EN
Message us on Messenger
Developer resources

Only for China mainland sellers and Korean sellers — Shopee API

v2.global_product.init_tier_variation · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

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

NameInTypeSampleDescription
AuthorizationheaderheaderBearer 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_idquerystring100001Gian 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

NameInTypeRequiredSampleDescription
global_modelbodyobject[]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_pricebodyfloatYes100Giá gốc phân loại toàn cầu.
global_model[].seller_stockbodyobject[]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_idbodystringNodemo-locationMã 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[].stockbodyint64Yes10Số lượng tồn kho.
global_model[].global_model_skubodystringNoDEMO-MODELSKU phân loại toàn cầu, tối đa 100 ký tự.
global_model[].tier_indexbodyint32[]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[].weightbodyfloatNo0.5Khố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[].dimensionbodyobjectNo{"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_heightbodyint32Yes1Chiều cao kiện của phân loại toàn cầu (cm).
global_model[].dimension.package_lengthbodyint32Yes1Chiều dài kiện của phân loại toàn cầu (cm).
global_model[].dimension.package_widthbodyint32Yes1Chiều rộng kiện của phân loại toàn cầu (cm).
global_model[].pre_orderbodyobjectNo{"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_shipbodyint32Yes3Số ngày chuẩn bị hàng; lấy phạm vi từ v2.product.get_dts_limit.
global_item_idbodyint64Yes100021Mã sản phẩm toàn cầu.
standardise_tier_variationbodyobject[]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_idbodyint32Yes100061Mã tầng phân loại chuẩn hóa.
standardise_tier_variation[].variation_namebodystringNoMẫuTên tầng phân loại chuẩn hóa.
standardise_tier_variation[].variation_group_idbodyint32No100061Mã nhóm tầng phân loại chuẩn hóa.
standardise_tier_variation[].variation_option_listbodyobject[]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_idbodyint32Yes100061Mã lựa chọn tầng phân loại chuẩn hóa.
standardise_tier_variation[].variation_option_list[].variation_option_namebodystringNoMẫuGiá trị lựa chọn tầng phân loại chuẩn hóa.
standardise_tier_variation[].variation_option_list[].image_idbodystringNodemo-imageMã ả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.

NameTypeSampleDescription
request_idstringd52ca43b277a4f9292fb8be658bfd33dMã request của Shopee để tra lỗi.
errorstringMã lỗi Shopee; rỗng = thành công.
messagestringMô tả lỗi.
warningstringCảnh báo.

Response sample

{
  "error": "",
  "message": "",
  "warning": "",
  "request_id": "demo-request"
}

Shopee error codes (22)

Show
CodeMeaning
add_on.add_on_deal_expiredKhông sửa chương trình mua kèm đã hết hạn.
error_dataDữ 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_paramTham số sai / thiếu / sai kiểu — xem `message` để biết tham số nào.
error_serverLỗ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_foundKhông tìm thấy sản phẩm toàn cầu.
error_busi_global_item_sku_over_limitSKU sản phẩm toàn cầu vượt giới hạn.
error_busi_global_item_price_should_bigger_than_zerooriginal_price phải lớn hơn 0.
error_duplicated_variation_optionLựa chọn tầng phân loại bị trùng.
error_busi_global_tier_option_image_not_equal_to_tier_one_optionSố ả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_innerLỗi hệ thống Shopee — thử lại sau.
error_permissionGian 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_validateThiết lập bán sỉ hoặc thị trường của merchant chưa hợp lệ; xem `message`.
error_update_item_priceCập nhật giá sản phẩm không được chấp nhận; xem `message`.
error_busiMerchant/gian hàng có nhiều kho; cần gửi location_id.
error_system_busyHệ thống đang bận; thử lại sau.
error_stock_less_then_min_limitnormal_stock/seller_stock nhỏ hơn giới hạn tối thiểu.
error_stock_bigger_then_limitnormal_stock/seller_stock lớn hơn giới hạn tối đa.
error_limitChạ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_limitGọ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_linkedMerchant 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

  1. Sign up for Partner
  2. Enable a data type of the Sản phẩm group on the platform page
  3. Create an API key (tick the Shopee channel)
  4. Call it as in the examples above