VI | EN
Nhắn Messenger
Dành cho developer

Sản phẩm được gợi ý tối ưu hoa hồng — API Shopee AMS

v2.ams.get_optimization_suggestion_product · gọi qua Quantri360 bằng một API key cho chính tài khoản / tài sản bạn đã kết nối và ủy quyền — 360 lo việc ký request và làm mới phiên đăng nhập bạn đã cấp.

v2.ams.get_optimization_suggestion_product

GET/api/v2/ams/get_optimization_suggestion_productGọi qua 360: GET https://partner.quantri360.com/v1/shopee_ams/api/v2/ams/get_optimization_suggestion_product
Mô tả API

Sản phẩm được gợi ý tối ưu Tiếp thị liên kết: sản phẩm tiềm năng nên đưa vào chiến dịch, sản phẩm nên TĂNG tỷ lệ hoa hồng, hoặc nên GIA HẠN thời gian chiến dịch — kèm tỷ lệ hiện tại, khoảng tỷ lệ đề xuất, số bán và số affiliate 90 ngày.

  • Thương hiệu mẫu: optimize_increase_commission_rate có 496 sản phẩm (đang 2%, đề xuất 6–12%); product_opportunities và optimize_extend_promotion_period rỗng (item_list [], total 0).
  • Muốn số từ display_price phải bỏ "₫" và dấu chấm.

Request

Địa chỉ

GET https://partner.quantri360.com/v1/shopee_ams/api/v2/ams/get_optimization_suggestion_product

Xác thực & gian hàng

TênVị tríKiểuMẫuMô tả
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.

Tham số request

TênVị tríKiểuBắt buộcMẫuMô tả
page_noqueryintCó1Trang, từ 1.
page_sizequeryintCó201–100.
rcmd_reason_filterquerystringCóoptimize_increase_commission_rateproduct_opportunities (sản phẩm tiềm năng) · optimize_increase_commission_rate (nên tăng hoa hồng) · optimize_extend_promotion_period (nên gia hạn).

Phân trang

Tăng page_no khi response.has_more = true.

Ví dụ request

curl -s "https://partner.quantri360.com/v1/shopee_ams/api/v2/ams/get_optimization_suggestion_product?page_no=1&page_size=20&rcmd_reason_filter=optimize_increase_commission_rate" \
  -H "Authorization: Bearer $KEY"
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/shopee_ams/api/v2/ams/get_optimization_suggestion_product",
    params={
        "page_no": 1,
        "page_size": 20,
        "rcmd_reason_filter": "optimize_increase_commission_rate"
    },
    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_ams/api/v2/ams/get_optimization_suggestion_product');
for (const [k, v] of Object.entries({"page_no":1,"page_size":20,"rcmd_reason_filter":"optimize_increase_commission_rate"})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
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_ams/api/v2/ams/get_optimization_suggestion_product' . '?' . http_build_query(['page_no' => 1, 'page_size' => 20, 'rcmd_reason_filter' => 'optimize_increase_commission_rate']);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Tham số phản hồi (nguyên của Shopee AMS)

TênKiểuMẫuMô tả
request_idstringd52ca43b277a4f9292fb8be658bfd33dMã request của Shopee để tra lỗi.
errorstringMã lỗi Shopee; rỗng = thành công.
messagestringMô tả lỗi.
responseobject
totalint496Tổng sản phẩm được gợi ý (khóa là `total`, không phải total_count).
has_morebooltrue
item_listobject[]
item_idint10000000003Mã sản phẩm.
item_namestringÁo 2 Dây Buộc Nơ Lưng Thương hiệu mẫu - SA2DBA01Tên.
rcmd_reasonstring[]["optimize_commission_rate"]Lý do: `severe_shortage` · `high_popularity` · `optimize_commission_rate` · `extend_time_period`.
campaign_idint10000000006Chiến dịch hiện tại của sản phẩm.
campaign_statusstringOngoingUpcoming · Ongoing · Terminating.
commission_ratefloat2Tỷ lệ hiện tại (%) — 2 = 2%.
suggest_min_ratefloat7Đề xuất thấp nhất (%).
suggest_max_ratefloat12Đề xuất cao nhất (%).
prefill_ratefloat7Tỷ lệ điền sẵn khi áp gợi ý (%).
prefill_subsidy_ratefloat0Tỷ lệ Shopee trợ giá tính theo hoa hồng shop (%).
has_subsidy_databoolfalseCó số liệu trợ giá.
period_start_timetimestamp1790049614Bắt đầu.
period_end_timetimestamp32503651199Kết thúc; 32503651199 = không thời hạn.
affiliate_countint0Số affiliate đã chia sẻ sản phẩm trong 90 ngày.
item_soldint3Số bán qua Tiếp thị liên kết 90 ngày (với product_opportunities: số bán của sản phẩm).
l2_category_order_countintnullSố đơn affiliate của ngành cấp 2 trong 30 ngày — chỉ có với product_opportunities, còn lại null.
display_pricestring₫99.000Giá hiển thị dạng CHỮ có ký hiệu ₫ và dấu chấm nghìn — khác display_price số thuần ở các API sản phẩm AMS khác.

Mẫu phản hồi

{
  "error": "",
  "message": "",
  "request_id": "e3e3e7f35ef7b4f7…",
  "response": {
    "item_list": [
      {
        "item_id": 10000000003,
        "item_name": "Áo 2 Dây Buộc Nơ Lưng Thương hiệu mẫu - SA2DBA01",
        "rcmd_reason": [
          "optimize_commission_rate"
        ],
        "campaign_id": 10000000006,
        "commission_rate": 2,
        "period_start_time": 1790049614,
        "period_end_time": 32503651199,
        "affiliate_count": 0,
        "item_sold": 3,
        "campaign_status": "Ongoing",
        "l2_category_order_count": null,
        "suggest_min_rate": 7,
        "suggest_max_rate": 12,
        "prefill_rate": 7,
        "prefill_subsidy_rate": 0,
        "display_price": "₫99.000",
        "has_subsidy_data": false
      }
    ],
    "total": 496,
    "has_more": true
  }
}

Mã lỗi của Shopee AMS (8)

Bấm để xem
MãÝ nghĩa
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_businessKhông thể thực hiện nghiệp vụ Affiliate; kiểm message để biết điều kiện hoặc cài đặt cần xử lý.
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_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).
shop_bannedGian hàng đang bị Shopee khóa — mọi API tạm ngưng tới khi gỡ khóa.
error_kyc_authGian hàng chưa hoàn tất đăng ký người bán trên Kênh Người Bán.

Bắt đầu dùng

  1. Đăng ký tài khoản Partner
  2. Mở loại dữ liệu thuộc nhóm Affiliate ở trang nền tảng
  3. Tạo API key (tick kênh Shopee AMS)
  4. Gọi theo ví dụ ở trên