TikTok Shop API: extraia produtos e preços em JSON

A API TikTok Shop da GeckoAPI transforma buscas de produtos do TikTok Shop Brasil em dados prontos para o seu sistema. Envie uma palavra-chave e receba produtos, preços, vendedores, imagens, avaliações, contagens de vendas e promoções em JSON, conforme as informações disponíveis na busca.

Com uma única integração, você pode acompanhar ofertas de concorrentes, descobrir lojas em uma categoria, montar históricos de preços e alimentar planilhas, dashboards ou agentes de IA. A GeckoAPI executa a coleta e organiza a resposta; sua aplicação faz uma chamada HTTP e trabalha diretamente com os campos de cada produto.

O ponto de partida é simples: uma palavra-chave, uma página e 5 créditos por consulta. Teste a API TikTok Shop no playground ou use os exemplos deste guia para começar pelo código.

Como usar a API TikTok Shop da GeckoAPI

O endpoint de extração é POST https://api.geckoapi.com.br/v1/extract. Para buscar produtos, informe target: "tiktok.com", type: "plp" e a palavra-chave em keyword.

Por exemplo, uma pesquisa por “cafeteira” usa este corpo JSON:

{
  "target": "tiktok.com",
  "type": "plp",
  "keyword": "cafeteira",
  "page": 1
}

plp identifica a extração de uma listagem de produtos. Cada item retornado corresponde a um produto encontrado na busca, com os dados comerciais disponíveis no cartão.

Faça sua primeira consulta com cURL

Gere uma chave no dashboard da GeckoAPI, salve-a na variável de ambiente GECKOAPI_KEY e execute:

curl --fail-with-body --max-time 120 \
  --request POST 'https://api.geckoapi.com.br/v1/extract' \
  --header "Authorization: Bearer ${GECKOAPI_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "target": "tiktok.com",
    "type": "plp",
    "keyword": "cafeteira",
    "page": 1
  }'

A resposta traz os produtos em data.items, o horário da extração em data.extractedAt e os indicadores de paginação. Você pode salvar o JSON, selecionar campos para uma planilha ou encaminhar os resultados para o banco de dados da sua aplicação.

Parâmetros da busca de produtos

Campo	Como preencher
`target`	Use `"tiktok.com"`.
`type`	Use `"plp"`.
`keyword`	Termo de busca obrigatório, de 1 a 200 caracteres, desconsiderando espaços nas extremidades.
`page`	Página de 1 a 20. Quando omitida, a consulta usa a página 1.

O conector consulta o TikTok Shop Brasil, com região BR e moeda da busca BRL fixas. A entrada é uma palavra-chave; não é necessário montar uma URL de pesquisa. Os quatro campos acima são os parâmetros aceitos pelo endpoint.

Veja o contrato completo na documentação da API TikTok Shop PLP.

Produtos, preços, lojas e promoções: o que a GeckoAPI entrega

O valor de uma API de produtos do TikTok Shop está em reunir informações que ajudam a avaliar uma oferta. Além do título e do preço, o retorno da GeckoAPI pode incluir a loja, a nota do produto, os sinais de vendas e o contexto promocional exibido na busca.

Dados	Campos do JSON	Como usar
Identificação do produto	`productId`, `name`	Reconhecer o mesmo produto em coletas diferentes.
Vendedor	`sellerName`, `shopId`	Agrupar ofertas por loja e acompanhar concorrentes.
Preço e desconto	`price`, `regularPrice`, `discountPercentage`	Comparar preço anunciado, referência e desconto informado.
Avaliação e vendas	`rating`, `soldCount`, `soldCountText`	Selecionar produtos para análise a partir dos sinais exibidos.
Imagem	`image.url`	Montar cartões de produto em ferramentas de pesquisa.
Promoções e cupons	`promotions`, `promotionLabels`, `flashSale`	Registrar benefícios e períodos de oferta disponíveis.
Frete e destaques	`freeShipping`, `labels`, `sellingPoints`	Acrescentar contexto comercial à comparação.

Acompanhe o preço com o contexto da oferta

price contém o preço anunciado em formato numérico, enquanto displayPrice preserva o texto exibido. Quando a origem informa preço riscado e desconto, eles aparecem em regularPrice e discountPercentage.

Para monitorar preços no TikTok Shop, guarde esses campos junto com as promoções. O preço da listagem pode refletir cupons ou ofertas específicas e é identificado por priceType: "displayed_offer". Ele representa a oferta encontrada na busca, sem confirmação de variante ou do total no checkout.

Esse contexto permite, por exemplo, distinguir uma mudança no preço anunciado de uma oferta que passou a exibir um cupom. Seu dashboard pode mostrar o preço, os rótulos promocionais e o instante da consulta lado a lado.

Descubra os vendedores presentes em cada busca

Os campos sellerName e shopId ajudam a responder quais lojas aparecem para as palavras-chave monitoradas. Ao agrupar os resultados por vendedor, você consegue observar o mix de produtos encontrado, as faixas de preço e as promoções associadas a cada loja.

Mantenha productId e shopId como strings no banco e no código. Isso preserva a precisão dos identificadores e facilita relacionar capturas sem depender de nomes que podem mudar.

Use avaliações e vendas para priorizar sua pesquisa

A nota em rating e os campos de vendas podem ajudar a selecionar produtos que merecem uma análise mais próxima. A GeckoAPI entrega soldCount quando a origem fornece uma contagem numérica e preserva o texto exibido em soldCountText.

Se houver apenas um valor abreviado, o campo numérico pode ser null. Trate esse dado como um sinal comercial da listagem, com o contexto disponível na coleta, sem atribuir a ele um período de vendas ou faturamento que a fonte não informou.

Registre cupons, ofertas relâmpago e frete

promotions organiza os dados de promoções, incluindo tipos como FLASH_SALE, VOUCHER e COUPON_APPLIED_PRICE, quando presentes. promotionLabels mantém os textos comerciais exibidos, e flashSale pode informar início e fim de uma oferta.

O indicador freeShipping e os rótulos em labels complementam a leitura da oferta. Campos ausentes retornam null, e listas sem dados retornam []; preserve essa distinção ao montar os filtros do seu dashboard.

Exemplo de produto do TikTok Shop em JSON

Este é um recorte ilustrativo com valores fictícios. A resposta real inclui também metadados de execução, paginação e outros campos documentados:

{
  "data": {
    "query": "cafeteira",
    "region": "BR",
    "currency": "BRL",
    "extractedAt": "2026-09-09T12:00:00.000Z",
    "items": [
      {
        "productId": "1734000000000000001",
        "name": "Cafeteira elétrica 600 ml",
        "sellerName": "Loja Exemplo",
        "shopId": "7494000000000000001",
        "price": 89.9,
        "displayPrice": "R$ 89,90",
        "regularPrice": 119.9,
        "currency": "BRL",
        "priceType": "displayed_offer",
        "rating": 4.7,
        "soldCount": 850,
        "soldCountText": "850 sold",
        "freeShipping": null,
        "promotionLabels": ["Flash sale"],
        "flashSale": {
          "startsAt": "2026-09-09T12:00:00.000Z",
          "endsAt": "2026-09-09T18:00:00.000Z"
        }
      }
    ]
  }
}

Esse produto pode virar uma linha em uma planilha, um cartão em um comparador ou um registro no seu histórico. O formato estruturado facilita usar preço como número, agrupar por loja e consultar a data da oferta sem extrair textos de uma página por conta própria.

O que construir com a API TikTok Shop

Monitoramento de preços de concorrentes

Defina um conjunto de palavras-chave relacionadas ao seu catálogo e consulte a API em horários programados. Salve productId, shopId, price, regularPrice, promoções e extractedAt a cada execução.

Imagine que uma cafeteira seja encontrada por R$ 119,90 de manhã e R$ 89,90 à tarde. Seu sistema pode identificar a queda, verificar se há um rótulo de oferta relâmpago e gerar um alerta com os dois valores e horários. O histórico nasce das capturas que você armazena.

Para comparar produtos entre plataformas, combine a consulta com as APIs de Shopee, Amazon e Mercado Livre. Valide modelo, capacidade, quantidade e variante ao relacionar ofertas. O guia de monitoramento de preços de concorrentes com API aprofunda a organização desse fluxo.

Pesquisa de produtos e sortimento

Buscas como “cafeteira”, “cafeteira portátil” e “cafeteira italiana” permitem observar conjuntos diferentes de ofertas. Ao separar os resultados por termo, você consegue pesquisar faixas de preço, identificar lojas recorrentes e selecionar produtos para uma avaliação comercial.

Uma aplicação pode destacar itens com nota disponível acima de um critério escolhido, ofertas dentro de uma faixa de preço ou produtos encontrados pela primeira vez em uma coleta. Esses filtros são aplicados pelo seu sistema aos resultados recebidos da GeckoAPI.

Acompanhamento de campanhas promocionais

Registre os textos de promotionLabels, as promoções estruturadas e os horários de flashSale. Assim, seu time pode observar quando determinada oferta apareceu com um benefício e como o preço anunciado se comportou nas capturas seguintes.

Essa análise é útil para acompanhar campanhas de concorrentes e organizar um calendário das ofertas observadas. Preserve a palavra-chave e a página da coleta para manter a origem de cada observação.

Dashboards, automações e agentes de IA

A resposta JSON pode alimentar um dashboard de e-commerce com produto, loja, preço, nota e horário da consulta. Em uma automação que aceite requisições HTTP, configure o POST /v1/extract, a credencial Bearer da GeckoAPI e o corpo da busca.

Um agente de IA também pode usar a API como ferramenta para responder a pedidos como “pesquise cafeteiras no TikTok Shop e organize as ofertas por preço”. Sua aplicação executa a consulta e entrega os produtos ao agente com os campos e a data da extração, para que a resposta se apoie na busca realizada.

Como extrair produtos do TikTok Shop com Python e salvar em CSV

Para levar a busca a uma planilha, use Python com requests e o módulo csv. Instale a dependência com python -m pip install requests, configure GECKOAPI_KEY no ambiente e execute o script:

import csv
import os
import requests

keyword = "cafeteira"
response = requests.post(
    "https://api.geckoapi.com.br/v1/extract",
    headers={
        "Authorization": f"Bearer {os.environ['GECKOAPI_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "target": "tiktok.com",
        "type": "plp",
        "keyword": keyword,
        "page": 1,
    },
    timeout=120,
)
response.raise_for_status()
payload = response.json()
data = payload["data"]

columns = [
    "productId", "name", "sellerName", "price", "currency",
    "rating", "soldCount", "promotionLabels", "keyword", "extractedAt",
]

with open("tiktok-shop-produtos.csv", "w", newline="", encoding="utf-8-sig") as file:
    writer = csv.DictWriter(file, fieldnames=columns)
    writer.writeheader()
    for item in data["items"]:
        row = {column: item.get(column) for column in columns}
        row["promotionLabels"] = " | ".join(item.get("promotionLabels") or [])
        row["keyword"] = keyword
        row["extractedAt"] = data["extractedAt"]
        writer.writerow(row)

print(f"CSV criado com {len(data['items'])} produtos.")
print(f"Execução: {payload['executionId']}")

O arquivo tiktok-shop-produtos.csv recebe uma linha por produto. Importe productId como texto no Excel ou na ferramenta de análise para preservar todos os dígitos. O script grava uma captura por execução; para um histórico contínuo, use arquivos com data no nome ou acrescente os registros a uma tabela no banco.

TikTok Shop API em JavaScript: consulte várias páginas

Para ampliar a pesquisa, use os indicadores hasMore e nextPage retornados pela GeckoAPI. A origem recebe uma solicitação de 10 produtos por página e pode devolver menos. primaryResults informa quantos produtos únicos vieram naquela página.

O exemplo abaixo consulta até três páginas, mantendo a mesma palavra-chave, e consolida os produtos por ID. Salve-o como tiktok-shop.mjs e execute com node tiktok-shop.mjs em uma versão do Node.js com fetch nativo:

const apiKey = process.env.GECKOAPI_KEY;
if (!apiKey) throw new Error("Configure GECKOAPI_KEY no ambiente.");

const keyword = "panela antiaderente";
const productsById = new Map();
const maxPages = 3;
let page = 1;

for (let request = 0; request < maxPages; request += 1) {
  const response = await fetch("https://api.geckoapi.com.br/v1/extract", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      target: "tiktok.com",
      type: "plp",
      keyword,
      page,
    }),
    signal: AbortSignal.timeout(120_000),
  });

  if (!response.ok) {
    throw new Error(`Erro na página ${page}: HTTP ${response.status}`);
  }

  const { data } = await response.json();
  for (const item of data.items) {
    if (!productsById.has(item.productId)) {
      productsById.set(item.productId, {
        ...item,
        keyword,
        extractedAt: data.extractedAt,
      });
    }
  }

  if (!data.hasMore || !Number.isInteger(data.nextPage)) break;
  if (data.nextPage <= page || data.nextPage > 20) break;
  page = data.nextPage;
}

console.log(JSON.stringify([...productsById.values()], null, 2));

Essa coleta consome até 15 créditos se as três páginas forem consultadas. A deduplicação vale para a pesquisa atual; em uma rotina de monitoramento, salve as novas capturas para manter o histórico.

A paginação aceita no máximo a página 20. Use nextPage como valor de page na chamada seguinte, sempre com a mesma keyword. O total global da busca não está disponível: totalResults retorna null.

Por que usar a GeckoAPI para scraping do TikTok Shop?

Com a API de scraping do TikTok Shop da GeckoAPI, sua integração se concentra na busca e no uso dos dados. Você envia JSON por HTTP e recebe produtos organizados em um contrato documentado.

Isso reduz o trabalho necessário para colocar a coleta dentro de um produto:

Integração por HTTP: use a mesma chamada em Python, JavaScript ou ferramentas de automação.
Campos prontos para análise: trabalhe com preço numérico, IDs de produto e loja, avaliações e promoções estruturadas.
Paginação explícita: percorra a busca usando os indicadores de continuação do retorno.
Rastreabilidade: guarde requestId, executionId e extractedAt junto com os resultados.
Outras fontes no mesmo serviço: amplie seu projeto com as APIs de e-commerce da GeckoAPI, respeitando os campos documentados para cada conector.

Seu código cliente não precisa executar Selenium, controlar um navegador ou interpretar o HTML para obter os campos descritos neste guia. O tempo de integração pode ser dedicado aos filtros, ao histórico e às telas que o seu time precisa usar.

Quanto custa a API TikTok Shop da GeckoAPI?

Cada requisição TikTok Shop PLP custa 5 créditos e consulta uma página. O consumo é por chamada, independentemente da quantidade de produtos retornados naquela página.

Rotina de coleta	Requisições	Créditos
Uma palavra-chave, primeira página	1	5
Uma palavra-chave, três páginas	3	15
Seis palavras-chave, duas páginas por busca	12	60
A mesma rotina anterior, duas vezes por dia	24 por dia	120 por dia

Esses valores consideram a consulta de todas as páginas planejadas. Se a busca terminar antes, a rotina pode parar usando hasMore; chamadas extras para repetir uma pesquisa entram no consumo.

Comece com poucas palavras-chave e ajuste a frequência conforme a utilidade dos dados para o seu projeto. Consulte os planos da GeckoAPI para dimensionar a operação e o custo documentado do TikTok Shop PLP para planejar cada coleta.

Perguntas frequentes sobre a API TikTok Shop da GeckoAPI

Como buscar produtos do TikTok Shop por API?

Envie um POST para https://api.geckoapi.com.br/v1/extract com sua chave GeckoAPI no cabeçalho Bearer. No corpo, use target: "tiktok.com", type: "plp", uma keyword e, opcionalmente, page. Os produtos chegam em data.items.

Quais dados do TikTok Shop posso extrair?

A busca pode retornar nome e ID do produto, loja, preços, desconto, imagem, nota, contagem de vendas, frete e promoções. A disponibilidade depende dos dados informados pela origem em cada cartão. Consulte o schema para conhecer todos os campos.

A API retorna dados do TikTok Shop Brasil?

Sim. Este conector é voltado ao Brasil, com região BR e moeda da busca BRL. A requisição usa palavra-chave e página, sem seleção de outro mercado.

Posso usar a GeckoAPI para monitorar preços automaticamente?

Sim. Agende consultas, salve os resultados com extractedAt e compare os produtos por productId. Os campos de preço e promoção permitem montar alertas a partir das mudanças observadas entre capturas.

Consigo exportar os produtos para Excel ou CSV?

Sim. A GeckoAPI retorna JSON, e você pode transformar data.items em linhas. O exemplo Python deste artigo gera um CSV com produto, vendedor, preço, avaliação, vendas, promoções e horário da coleta.

É possível consultar uma URL de produto?

A API TikTok Shop descrita aqui realiza buscas PLP por palavra-chave. Os parâmetros aceitos são target, type, keyword e page; a consulta de detalhe por URL não faz parte desse endpoint.

Quantas páginas posso consultar?

O limite é a página 20. A origem pode encerrar a busca antes disso, por isso use hasMore e nextPage para decidir se deve continuar. Cada página consultada custa 5 créditos.

Teste a API TikTok Shop da GeckoAPI

Escolha uma palavra-chave que represente o produto que você quer pesquisar e faça a primeira consulta. Em uma resposta, você já pode reunir ofertas, identificar vendedores e selecionar os campos que vão alimentar sua planilha ou aplicação.

Abra o playground do TikTok Shop para testar a busca ou acesse a documentação da API TikTok Shop da GeckoAPI para integrar o endpoint ao seu projeto.