stable本次发布有变化全部展示
来自 TikTok Shop 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Path: /product/202604/opportunities/query
#§2 Method: [POST]
#§3 Function Description
Search and retrieve a paginated list of opportunity leads available to the authorized seller, with optional filters by type, status, category, etc and ordered by the algorithm ranking model.
§4 Common Parameters
For common parameters, refer to How to call TikTok Shop APIs - Common Parameters
| Properties | Location | Type | Require | Sample | Properties description |
|---|---|---|---|---|---|
| shop_cipher | query | string | Y | GCP_XF90igAAAABh00qsWgtvOiGFNqyubMt3 | Use this property to pass shop information in requesting the API. Failure in passing the correct value when requesting the API for cross-border shops will return incorrect response. |
| Get by API Get Authorization Shop | |||||
| content-type | header | string | Y | application/json | Allowed type: application/json |
§5 Request Query Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| app_key | string | Y | 38abcd | Every single app will have a unique key. Please use the specific key assigned to your app. |
| sign | string | Y | 5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c | Signature generated by gen algorithm. When you send API requests to TTS, you must sign them so that TTS can identify the senders. |
| timestamp | int | Y | 1623812664 | Unix timestamp GMT (UTC+00:00). This timestamp is used across all API requests. Developers can use this convert to local time. |
| page_size | int | Y | 20 | Number of results per page. Max: 100. Default: 20. |
| page_token | string | N | 100 | Pagination token from previous response. Omit for first page. |
| locale | string | N | en-US | Expressed using {language_code}-{COUNTRY_CODE}, in accordance with the BCP-47 standard. |
§6 Request Body Parameters
| Properties | Type | Require | Sample | Properties description |
|---|---|---|---|---|
| opportunity_type | string | Y | PRODUCT | Type of opportunity: PRODUCT（品线索）/ KEYWORD（词线索）/ CATEGORY（类目线索） |
| category_ids | []string | N | ["601310","601311"] | Filter by category IDs. Leave empty to return all leads that available to the seller. |
| create_time_ge | int | N | 1775976752 | Filter opportunities created after this time. timestamp in seconds |
| create_time_lt | int | N | 1776976752 | Filter opportunities created before this time. timestamp in seconds |
| tag_codes | []string | N | ["CORE_PRODUCT","TOP_PRODUCT"] | A list of tag codes used to filter the results. |
§7 Request Sample
Query
https://open-api.tiktokglobalshop.com/product/202604/opportunities/query?app_key=123abc&sign=5361235029d141222525e303d742f9e38aea052d10896d3197ab9d6233730b8c×tamp=1625484268&shop_cipher=ROW_RHkDDABBAAB8tKAVoAqsMTjsQZFLyNfY&page_size=20&page_token=100&locale=en-US
Body
{"opportunity_type":"PRODUCT","category_ids":["601310","601311"],"create_time_ge":1775976752,"create_time_lt":1776976752,"tag_codes":["CORE_PRODUCT","TOP_PRODUCT"]}
§8 Response Parameters
| Properties | Type | Sample | Properties description |
|---|---|---|---|
| code | int | 0 | The success or failure status code returned in API response. |
| message | string | Success | The success or failure messages returned in API response. Reasons of failure will be described in the message. |
| request_id | string | 202203070749000101890810281E8C70B7 | Request log |
| data | object | Specific return information | |
| ^data | object | Specific return information | |
| ^^opportunities | []object | The information of the opportunity | |
| ^^^id | string | 7123456789012345678 | Unique ID of the opportunity |
| ^^^title | string | title info | Opportunity title. |
| ^^^reference_images | []string | ["https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/61e605ce483f4f7b9b419d510f74fd22~tplv-o3syd03w52-resize-image:400:400.image?dr=15586&t=555f072d&ps=933b5bde&shp=5563f2fb&shcp=122e87b3&idc=maliva&from=1432613627&from_p=305039283"] | Reference product images of the product to list. |
| ^^^category_id_level_1 | string | 901128 | TikTok Shop L1 category ID. |
| ^^^category_id_level_2 | string | 30122212 | TikTok Shop L2 category ID. |
| ^^^category_id_level_3 | string | 3321212 | TikTok Shop L3 category ID. |
| ^^^category_name_level_1 | string | Shoes | Category name of 1st level category. |
| ^^^category_name_level_2 | string | Women's Shoes | Category name of 2nd level category. |
| ^^^category_name_level_3 | string | Sandals & Flip Flops | Category name of 3rd level category. |
| ^^^is_collected | bool | false | Whether it has been collected |
| ^^^query_words | string | word1,word2 | TikTok Shop in-site user search keyword. |
| ^^^opportunity_type | string | PRODUCT | Type of opportunity: PRODUCT（品线索）/ KEYWORD（词线索）/ CATEGORY（类目线索） |
| Empty return for a specific opportunity type indicates the business team has not enabled merchant submission for this lead type in the corresponding market. | |||
| ^^^brand_name | string | brand1 | Brand requirements for products specified by the opportunity. |
| ^^^create_time | int | 1712544000 | Opportunity creation timestamp, second-level timestamp |
| ^^^expire_time | int | 1712544000 | Opportunity expiry date, second-level timestamp |
| ^^^est_market_sales_volume | string | 100k+ | Estimated overall market sales volume. |
| ^^^est_market_gmv | string | $9M+ | Estimated overall market sales GMV in USD. |
| ^^^search_volume | string | 100k+ | TikTok Shop in-site user search volume. |
| ^^^competitor_product_count | string | 100+ | Number of competing products currently listed. |
| ^^^video_view_pv | string | 7k+ | The cumulative short video view count of all videos associated with this product opportunity. |
| ^^^tags | string | Pencarian teratas,Pencarian trending,Persaingan rendah,Trending di TikTok,Terlaris | the tag list of opportunity |
| ^^^tag_codes | []string | ["CORE_PRODUCT"] | The tag code list of opportunity, mapped one-to-one in order with tags. Allowed values for Latam include: CORE_PRODUCT, TOP_PRODUCT. |
| ^^^reward_info | string | Boost shoptab visibility | Rewards that sellers can gain by listing products as required. |
| ^^^external_product_id | string | SH1234567890 | Product ID on the reference source. |
| ^^^reference_source | string | 1 | The code of the reference_source. Returned only when external_product_id is present. |
| ^^next_page_token | string | 100 | Pagination token from previous response. Omit for first page. |
| ^^total_count | int | 200 | Total number of matching opportunities (approximate). |
§9 Response Sample
{"code":0,"data":{"data":{"opportunities":[{"id":"7123456789012345678","title":"title info","reference_images":["https://p16-oec-va.ibyteimg.com/tos-maliva-i-o3syd03w52-us/61e605ce483f4f7b9b419d510f74fd22~tplv-o3syd03w52-resize-image:400:400.image?dr=15586\u0026t=555f072d\u0026ps=933b5bde\u0026shp=5563f2fb\u0026shcp=122e87b3\u0026idc=maliva\u0026from=1432613627\u0026from_p=305039283"],"category_id_level_1":"901128","category_id_level_2":"30122212","category_id_level_3":"3321212","category_name_level_1":"Shoes","category_name_level_2":"Women's Shoes","category_name_level_3":"Sandals \u0026 Flip Flops","is_collected":false,"query_words":"word1,word2","opportunity_type":"PRODUCT","brand_name":"brand1","create_time":1712544000,"expire_time":1712544000,"est_market_sales_volume":"100k+","est_market_gmv":"$9M+","search_volume":"100k+","competitor_product_count":"100+","video_view_pv":"7k+","tags":"Pencarian teratas,Pencarian trending,Persaingan rendah,Trending di TikTok,Terlaris","tag_codes":["CORE_PRODUCT"],"reward_info":"Boost shoptab visibility","external_product_id":"SH1234567890","reference_source":"1"}],"next_page_token":"100","total_count":200}},"message":"Success","request_id":"202203070749000101890810281E8C70B7"}
§10 Error Code
For common error codes, refer to How to call TikTok Shop APIs - Common Error Code
| Code | Message |
|---|