VI | EN
Message us on Messenger
Developer resources

Hợp tác mục tiêu (target collaboration) — TikTok Shop API

tiktok.affiliate_seller.202508.target_collaborations.search · 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.

tiktok.affiliate_seller.202508.target_collaborations.search

POST/affiliate_seller/202508/target_collaborations/searchVia 360: POST https://partner.quantri360.com/v1/tiktok/affiliate_seller/202508/target_collaborations/search
Description

Tìm các hợp tác mục tiêu (target collaboration — lời mời riêng gửi creator chọn sẵn, kèm sản phẩm và hoa hồng) của gian hàng theo trạng thái / tên / sản phẩm / creator. Dù là POST, API này CHỈ ĐỌC.

  • Gọi qua /v1/tiktok/affiliate_seller/202508/target_collaborations/search với Authorization: Bearer <key>; dùng platform_shop_id khi có nhiều shop. 360 tự gắn app_key, shop_cipher, sign và access_token.
  • collaboration_status BẮT BUỘC: thiếu → HTTP 400 code 36009004 "CollaborationStatus is a required field…"; giá trị ngoài 5 giá trị trên (vd ALL, ENDED, EXPIRED) → code 98001004 "invalid params".
  • Không có kết quả: data chỉ có target_collaborations: [] (không có total_count, next_page_token).
  • Muốn xem toàn bộ: gọi VALID (còn hiệu lực) và COMPLETED (đã kết thúc).
  • Danh sách không có creator / sản phẩm cụ thể — xem GET /affiliate_seller/202508/target_collaborations/{target_collaboration_id}.
  • API chỉ đọc; code = 0 mới là thành công.

Request

Endpoint

POST https://partner.quantri360.com/v1/tiktok/affiliate_seller/202508/target_collaborations/search

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
page_sizequeryintNo20CHỈ nhận 20, 50 hoặc 100.
page_tokenquerystringNonext_page_token của trang trước (giữ nguyên body và page_size).
collaboration_statusbodystringYesONGOINGONGOING (còn hạn > 7 ngày) · EXPIRING (còn < 7 ngày) · VALID (mọi hợp tác còn hiệu lực) · CANCELING (đang hủy) · COMPLETED (đã kết thúc: hết hạn + đã hủy).
search_parambodyobjectNo{"keyword_type":"PRODUCT_ID","keyword":"1735000000000000001"}Tìm theo từ khóa — gửi đủ cả hai: keyword_type (PRODUCT_ID · PRODUCT_NAME · TARGET_COLLABORATION_ID · TARGET_COLLABORATION_NAME; tên tìm gần đúng) và keyword.
creator_user_open_idbodystringNoChỉ hợp tác có creator này (creator_open_id).
creator_accept_statusbodystringNoALLACCEPT (creator đã thêm sản phẩm vào showcase) · ALL (mặc định).
free_sample_settingbodystringNoALLWITH_FREE_SAMPLE · ALL (mặc định).

Pagination

Lặp khi data.next_page_token khác rỗng: gửi lại đúng body, thêm query page_token.

Request examples

curl -s -X POST "https://partner.quantri360.com/v1/tiktok/affiliate_seller/202508/target_collaborations/search?platform_shop_id=7494000000000000000&page_size=20" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"collaboration_status":"COMPLETED"}'
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.post(
    "https://partner.quantri360.com/v1/tiktok/affiliate_seller/202508/target_collaborations/search",
    params={
        "platform_shop_id": "7494000000000000000",
        "page_size": 20
    },
    json={
        "collaboration_status": "COMPLETED"
    },
    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/tiktok/affiliate_seller/202508/target_collaborations/search');
for (const [k, v] of Object.entries({"platform_shop_id":"7494000000000000000","page_size":20})) 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({"collaboration_status":"COMPLETED"}),
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok/affiliate_seller/202508/target_collaborations/search' . '?' . http_build_query(['platform_shop_id' => '7494000000000000000', 'page_size' => 20]);
$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, '{"collaboration_status":"COMPLETED"}');
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Shop)

NameTypeSampleDescription
codeint00 = thành công; khác 0 xem message (105001–105003 = token, 360 đã tự làm mới một lần).
messagestringSuccessThông điệp của TikTok.
request_idstring2025101900000000000000000000Mã request TikTok.
dataobjectDữ liệu.
total_countint5Tổng khớp (vắng khi không có kết quả).
next_page_tokenstringRỗng = hết.
target_collaborationsobject[]Hợp tác mục tiêu.
idstring7642000000000000001Mã hợp tác — dùng cho API chi tiết / sửa.
namestringCửa hàng mẫuTên.
messagestringLời nhắn gửi creator.
typestringSTANDARD`STANDARD` (người bán tự chọn sản phẩm + creator) · `TOP_CREATOR_PROGRAM`.
start_timeint1779425875Unix giây.
end_timeint1782838799Unix giây.
create_timeintUnix giây.
update_timeintUnix giây.
creator_inivited_countint1Số creator được mời (tên trường viết sai chính tả `inivited` — giữ nguyên khi đọc).
showcase_creator_countint1Số creator đã thêm ít nhất một sản phẩm vào showcase.
content_creator_countint1Số creator đã đăng nội dung.
product_countint3Số sản phẩm.
free_sample_ruleobject{has_free_sample, is_sample_approval_exempt} — gửi mẫu miễn phí / tự duyệt mẫu.

Response sample

{
  "code": 0,
  "message": "Success",
  "request_id": "202610291653060C6A82…",
  "data": {
    "total_count": 5,
    "next_page_token": "",
    "target_collaborations": [
      {
        "id": "7642000000000000001",
        "name": "Cửa hàng mẫu",
        "message": "",
        "type": "STANDARD",
        "start_time": 1779425875,
        "end_time": 1782838799,
        "create_time": 1779425876,
        "update_time": 1779425876,
        "creator_inivited_count": 1,
        "showcase_creator_count": 1,
        "content_creator_count": 1,
        "product_count": 3,
        "free_sample_rule": {
          "has_free_sample": false,
          "is_sample_approval_exempt": false
        }
      }
    ]
  }
}

Get started

  1. Sign up for Partner
  2. Enable a data type of the Affiliate group on the platform page
  3. Create an API key (tick the TikTok Shop channel)
  4. Call it as in the examples above