Introdução

Este guia mostra passo a passo como fazer a primeira chamada à API HTTP do WinningHunter. Leva apenas cinco minutos, do início ao fim.

Resumo: Use uma conta que inclua Acesso à API, recupere sua chave em /api, inclua-o como um Chave X-API cabeçalho, chamada /api/v1/tiktok-shop/créditos para verificar a conexão e, em seguida, compilar usando o Referência da API.

1. Acesso à conta#

A API HTTP está disponível em contas WinningHunter elegíveis. Se sua chave for válida, mas as solicitações forem recusadas com o código HTTP 403, é possível que a conta conectada não tenha acesso à API — verifique o plano e o faturamento no seu painel de controle após fazer login.

2. Obtenha sua chave API#

Abrir /api enquanto estiver conectado. A página exibe:

• Sua chave de API (valor do cabeçalho, clique para copiar).
• Seu uso mensal do crédito (de um total de 20.000).
• Um registro de solicitações com códigos de status e registros de data e hora.
• Um botão de regeneração — as chaves antigas deixam de funcionar imediatamente após a regeneração.

A mesma tela também lista os endpoints HTTP disponíveis da TikTok Shop para consulta rápida.

3. Faça sua primeira solicitação#

Use um endpoint somente leitura para verificar a autenticação e a medição de crédito. /api/v1/tiktok-shop/créditos é recomendado — ele retorna seu saldo de crédito atual e os custos 1 crédito.

curl -sS \
  -H "X-API-Key: wh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "{origin}/api/v1/tiktok-shop/credits"

Uma resposta bem-sucedida é em JSON, com um HTTP 200 status e Content-Type: application/json. Se você receber uma mensagem de erro:

• 401 Acesso não autorizado — o cabeçalho está faltando, está incorreto ou a chave está errada. Consulte Autenticação.
• 403 Acesso negado — O acesso à API não está habilitado para esta conta; resolva isso no painel (plano / cobrança).
• 429 — ver Limites de taxa e Créditos e cobrança.

4. Executar uma consulta de pesquisa#

A maioria dos desenvolvedores começa com /api/v1/tiktok-shop/products/explore. É compatível com ambos OBTER e POST métodos e retorna uma lista paginada de produtos.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "{origin}/api/v1/tiktok-shop/products/explore" \
  -d '{
    "country": "US",
    "period": "30d",
    "limit": 20,
    "min_revenue": 50000
  }'

Utilização POST JSON quando o conjunto de filtros é grande — strings de consulta longas podem resultar em um 414 URI muito longo erro. Ambos os métodos aceitam os mesmos parâmetros. Os nomes dos filtros, os aliases, os valores padrão e a paginação estão documentados no Referência aos filtros da TikTok Shop.

4b. Chamar o Magic AI (opcional)#

O Magic AI também está disponível na interface de chaves de API em POST /api/v1/magic-ai.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -X POST "{origin}/api/v1/magic-ai" \
  --data-urlencode "text=Find winning beauty products for US women 25-34"

Importante:

• Utilização /api/v1/magic-ai para integrações com chave de API.
• /api/magic-ai (sem v1) é a rota de sessão do painel utilizada pelo aplicativo web.

5. Analisar o uso#

Depois de fazer várias chamadas, atualize a /api página (ou ligue para /api/uso (enquanto estiver conectado) — seu gráfico de uso e os créditos restantes refletirão a nova atividade. Cada solicitação bem-sucedida consome 1 crédito e é contabilizado no limite de tarifas por minuto.

6. (Opcional) Usar o MCP a partir de um cliente de IA#

Área de trabalho do Claude, Cursor, ChatGPT (com conectores MCP), Gêmeos (onde o Google permite o MCP remoto), e n8n (Cliente MCP / Ferramenta do Cliente MCP) pode chamar o WinningHunter como ferramentas em vez de escrever à mão curl.

• Os mesmos requisitos: uma conta na Acesso à API e o a mesma chave de API como acima — enviado como Chave X-API na configuração do cliente.
• Desfecho: HTTP com transmissão em fluxo em https://YOUR_HOST/mcp (consulte o guia para obter o JSON exato).
• Medição: cada um bem-sucedido ferramentas/chamada = 1 crédito; A MCP tem seu próprio limite por minuto (ver Guia do MCP).

Abrir MCP (Claude, Cursor, ChatGPT, Gemini, n8n) — você recebe pronto para colar claude_desktop_config.json e mcp.json trechos, notas sobre o conector do ChatGPT e do Gemini, etapas de configuração do n8n e texto de instruções para o agente. Nomes das ferramentas e argumentos: MCP · Referência de ferramentas. Contexto do produto: Filtros da TikTok Shop, Tendências. Manifesto do site para rastreadores: /llms.txt.

O que ler a seguir#

• Autenticação — opções de cabeçalho/parâmetros de consulta, regeneração, contas de equipe.
• Créditos e cobrança — a cota de 20.000 por mês, como ela é reiniciada, o que conta.
• Limites de taxa — 60 solicitações por minuto, estratégia de recuo.
• Erros — todos os códigos de status que a API pode retornar.
• Intervalos de tempo — período, período, e como a filtragem por data realmente funciona.
• Solução de problemas — quando algo parece errado.
• Glossário — definições de termos técnicos.
• Referência da API — autenticação e toda a interface de programação.
• IA mágica — corpo da solicitação, filtros e paginação para POST /api/v1/magic-ai.
• MCP (Claude, Cursor, ChatGPT, Gemini, n8n) — copiar e colar configurações de clientes, créditos e tarifas.
• MCP · Referência de ferramentas — todas as 28 ferramentas e parâmetros do MCP.
• Tendências · Explorador da loja · Rastreador da API Store — MCP + REST em contexto.