API da TikTok Shop — filtros e parâmetros de consulta
This reference is for integrators calling /api/v1/tiktok-shop/* with an Chave da API, or the same path shapes under /api/tiktok-shop/... in a logged-in browser session. HTTP route list and high-level behavior: Referência da API.
How parameters are sent#
| Mecanismo |
Detalhes |
| String de consulta |
É comum para GET. |
| POST JSON |
For explore and count routes that accept POST, a JSON object in the body is merged with query parameters (same keys as the tables below). Use this when filter sets are large (avoids 414 URI Too Long). |
| Formulário POST |
application/x-www-form-urlencoded O corpo também é incorporado aos parâmetros. |
| Omitido / vazio |
String vazia, null, ou a sequência literal "indefinido" são removidos e geralmente ignorados. |
Explore & count (categories, shops, creators, videos, products)#
Isso corresponde a:
Route suffix (under /api/v1/tiktok-shop/) |
Objetivo |
categorias/explorar, categorias/contagem |
List or filter categories / count matches |
lojas/explorar, lojas/contagem |
List or search shops / count matches |
criadores/explorar, criadores/contagem |
List or search creators / count matches |
vídeos/explorar, número de vídeos |
List or search videos / count matches |
produtos/explorar, número de produtos |
List or search products / count matches |
Pagination & sorting (explore only; not sent on count)
| Parâmetro |
Padrão |
Notas |
página |
1 |
Página inteira. |
limite |
20 |
Tamanho da página. |
depois de |
— |
Cursor opaco do conjunto de teclas (navegação para a frente). |
incluir_total |
— |
Se houver, encaminhe para o responsável. |
salto de ponto de verificação |
— |
Se houver, encaminhe para o responsável. |
classificar |
Veja a classificação padrão por entidade abaixo |
O Upstream mapeia campos de classificação específicos para cada período. |
encomenda |
desc |
Direção da ordenação. |
Definição do escopo da categoria (explorar e contar, quando tem_hierarquia_de_categorias (é verdade)#
| Parâmetro |
Notas |
IDs de categoria |
Separado por vírgulas ou em matriz; combinado com os IDs de nível abaixo. |
id_da_categoria_l1, id_da_categoria_l2, id_da_categoria_l3 |
Um único ID; vários apelidos ids_da_categoria_l1, ids_da_categoria_l2, ids_da_categoria_l3 também são aceitos. |
excluir_ids_de_categoria |
Lista separada por vírgulas a ser excluída. |
Defaults#
| Parâmetro |
Padrão |
país |
EUA |
Entity-specific filters#
Each entity exposes an allowlisted set of filters. Requests use canonical parameter names; aliases accept alternate names (same value).
Categorias — ordenação padrão: origem_da_receita#
| Filtros |
país, nível, IDs de categoria, nome, período, receita mínima, receita máxima, receita_mínima_por_loja, receita_máxima_por_loja, min_top_3_shop_ratio, max_top_3_shop_ratio, proporção_mínima_das_10_melhores_lojas, max_top_10_shop_ratio, min_shop_count, max_shop_count, min_video_count, max_video_count |
Aliases: receita mínima ← receita_mínima_30_dias; receita máxima ← receita_máxima_em_30_dias.
Lojas — ordenação padrão: receita#
| Filtros |
país, nome, período, IDs de categoria, receita mínima, receita máxima, taxa_mínima_de_crescimento_da_receita, taxa_máxima_de_crescimento_da_receita, taxa_mínima_de_crescimento_das_vendas, taxa_máxima_de_crescimento_das_vendas, visto pela primeira vez, classificação mínima, classificação máxima, tipo_de_vendedor, número_mínimo_de_produtos, número_máximo_de_produtos, preço_médio_mínimo_por_unidade, preço_médio_máximo_por_unidade, min_creator_count, max_creator_count, min_video_count, max_video_count, percentual_mínimo_de_canais_operados_internamente, max_channel_strategy_percentual_de_operação_própria |
Aliases: receita mínima ← min_gmv_30d; receita máxima ← max_gmv_30d; taxa_mínima_de_crescimento_da_receita ← taxa_de_crescimento_do_GMV_em_30_dias; taxa_máxima_de_crescimento_da_receita ← taxa_de_crescimento_do_GMV_em_30_dias; preço_médio_mínimo_por_unidade ← preço_médio_mínimo; preço_médio_máximo_por_unidade ← preço_médio_máximo.
Criadores — ordenação padrão: receita#
| Filtros |
país, nome, período, IDs de categoria, receita mínima, receita máxima, taxa_mínima_de_crescimento_da_receita, taxa_máxima_de_crescimento_da_receita, taxa_mínima_de_crescimento_de_seguidores, taxa_máxima_de_crescimento_de_seguidores, taxa_de_crescimento_mínima_de_visualizações, taxa_de_crescimento_de_visualizações_máxima, mín. de seguidores, máximo de seguidores, mín. de visualizações, máximo de visualizações, verificado, número_mínimo_de_produtos, número_máximo_de_produtos, min_video_count, max_video_count |
Aliases: receita mínima ← min_gmv_30d; receita máxima ← max_gmv_30d.
Vídeos — ordenação padrão: receita#
| Filtros |
país, nome, período, IDs de categoria, receita mínima, receita máxima, taxa_mínima_de_crescimento_da_receita, taxa_máxima_de_crescimento_da_receita, taxa_de_crescimento_mínima_de_visualizações, taxa_de_crescimento_de_visualizações_máxima, taxa_de_crescimento_mínima_de_curtidas, taxa_de_crescimento_de_curtidas, taxa_mínima_de_crescimento_das_ações, taxa_máxima_de_crescimento_das_ações, mín. de visualizações, máximo de visualizações, duração mínima, duração máxima, ROAS mínimo, max_roas, gasto_mínimo_com_publicidade, gasto_máximo_com_publicidade, mín. de curtidas, máximo de curtidas, número mínimo de seguidores do criador, número máximo de seguidores do criador, data_de_publicação, is_ad, é afiliado, é_autopromoção, is_ai_ugc, tendência_de_receita |
Produtos — ordenação padrão: receita#
| Filtros |
país, nome, período, IDs de categoria, receita mínima, receita máxima, taxa_mínima_de_crescimento_da_receita, taxa_máxima_de_crescimento_da_receita, taxa_mínima_de_crescimento_das_vendas, taxa_máxima_de_crescimento_das_vendas, mínimo de itens vendidos, máximo de itens vendidos, mín_de_unidades_vendidas, máximo de unidades vendidas, preço_médio_mínimo_por_unidade, preço_médio_máximo_por_unidade, taxa_mínima_de_comissão, taxa_máxima_de_comissão, pontuação_mínima_do_produto, pontuação máxima do produto, min_product_review_cnt, max_product_review_cnt, min_creator_count, max_creator_count, data_mínima_de_lançamento_do_produto, data_máxima_de_lançamento_do_produto, min_creator_conversion_ratio, max_creator_conversion_ratio, visto pela primeira vez, preço_mínimo, preço_máximo |
Aliases: mínimo de itens vendidos ← min_vendido; máximo de itens vendidos ← máximo vendido.
Permitido classificar valores#
Sort keys are não fully enumerated in this doc; the upstream analytics service maps generic sort keys to period-specific fields. Treat classificar como uma sequência de caracteres opaca alinhada à interface de filtro do aplicativo web, ou inspecione as chamadas de rede no painel de controle para a mesma entidade.
Dashboard-only parameters#
Do not rely on undocumented dashboard query flags for metering. For API integrations, send only the filters documented above and follow Credits & billing.
GET /api/v1/tiktok-shop/products#
Parâmetros de consulta (todos opcionais, exceto auth):
| Parâmetro |
Padrão |
página |
0 |
limite |
20 |
classificar |
descrição_de_vendas |
categoria, preço_mínimo, preço_máximo, vendas mínimas, max_vendas, classificação mínima, data_de, data_até, pesquisar, país |
— |
GET /api/v1/tiktok-shop/search (Pesquisar produtos)#
| Parâmetro |
Obrigatório |
q |
Sim (termo de pesquisa) |
página |
Não (0 (padrão) |
limite |
Não (20 (padrão) |
categoria |
Não |
GETtrending (obterProdutosEmDestaque)#
| Parâmetro |
Padrão |
limite |
10 |
prazo |
7 dias |
categoria |
— |
GET /api/v1/tiktok-shop/shop-details / lojas/detalhes (obterDetalhesDaLoja)#
| Parâmetro |
Obrigatório |
id |
Sim — identificador da loja |
GET /api/v1/tiktok-shop/suggestions (sugestões)#
| Parâmetro |
Obrigatório |
Notas |
tipo |
Sim |
Uma das seguintes opções: categorias, lojas, criadores, produtos, vídeos. |
q |
Sim |
Nome parcial; se estiver vazio, retornará sugestões vazias. |
limite |
Não |
1–20, padrão 10. |
país |
Não |
Padrão EUA. |
Hierarchy & static reads#
| Caminho |
Parâmetros |
categorias/hierarquia, categorias/camadas |
país (padrão EUA). |
categorias/resumo, categorias/história, … |
Mostly OBTER query params (país, ids, period, …); see the in-app network tab for the exact shape per route. |
Para POST veículos em rotas específicas (detalhes da loja, detalhes do produto, etc.), each route has its own JSON shape — capture a request from the dashboard for the tab you need, then replay it against /api/v1/tiktok-shop/... with your API key.
MCP tools (same data as explore)#
If you use Protocolo de Contexto de Modelo (Claude Desktop, etc.), the TikTok tools issue the same explore/count payloads the HTTP API accepts — same filter semantics as this document where applicable (palavra-chave, país, página, size vs HTTP limite, revenue/price bounds on products, …).
| MCP tool |
Maps to |
search_tiktok_products |
produtos/explorar |
search_tiktok_shops |
lojas/explorar |
search_tiktok_creators |
criadores/explorar |
search_tiktok_videos |
vídeos/explorar |
count_tiktok_entities |
Counts results matching the same filters used in the explorar pontos finais. |
browse_tiktok_categories, list_tiktok_category_top, autocomplete_tiktok |
Category hierarchy / layers / summary / history / siblings / top lists / suggestions |
get_tiktok_product, get_tiktok_shop, get_tiktok_creator, get_tiktok_video |
Detail + slice payloads (metrics, history, lists, strategy) — see MCP tools reference |
get_tiktok_trending_products |
Same idea as GETtrending (section below) |
verificar créditos |
Same idea as GET /api/v1/tiktok-shop/credits |
Full argument names: MCP · tools reference.
Where to look next#
| Preocupação |
Localização |
| Route list (paths + verbs) |
API reference — TikTok Shop section |
| Filters & bodies (this doc) |
Tables above |
| Entity details (JSON bodies) |
TikTok Shop details |
| ce](/docs/api) — TikTok Shop section |
|
| Filters & bodies (this doc) |
Tables above + in-app network captures for edge cases |
