Documentos
Ctrl+K Pesquisar Alt+[Alt+] Guias
Obter chave da API

Guias

Autenticação

Cada ponto de extremidade programático com medição aceita uma única chave de API, enviada de uma das três formas possíveis. Esta página explica onde obter a chave, como enviá-la e como o servidor a associa à sua conta.

Enviando sua

O servidor verifica três locais, nesta ordem. O primeiro valor não vazio é o vencedor.

Onde Exemplo Notas
Chave X-API cabeçalho X-API-Key: wh_… Preferencial. Nome do cabeçalho que não distingue maiúsculas de minúsculas.
Autorização cabeçalho Autorização: Portador wh_… Esquema “Standard Bearer”. Qualquer outra coisa (por exemplo, Básico) é ignorado.
chave_API parâmetro de consulta ?api_key=wh_… Apenas como alternativa. Evite usá-lo para qualquer informação confidencial — ele acaba aparecendo em URLs, logs de servidor e histórico do navegador. 
curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

curl -sS \
  -H "Authorization: Bearer $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

curl -sS "{origin}/api/v1/tiktok-shop/credits?api_key=$WH_API_KEY"

As três opções são equivalentes em termos de roteamento; escolha a que for mais fácil no seu cliente HTTP.

De onde vem a chave

As chaves são gerenciadas exclusivamente na página da API dentro do aplicativo:

  • GET /api — visualize sua chave atual, copie-a e gere-a novamente.
  • POST /api/regenerate — regeneração programática (é necessário fazer login na sessão).

Uma chave tem a seguinte aparência wh_ seguido por 48 caracteres hexadecimais. Trate-o como uma senha: ele concede acesso a todo o seu cota mensal da API.

A regeneração é imediato e destrutivo. A chave anterior deixa de funcionar no momento em que você a regenera, e quaisquer clientes que ainda a estejam usando receberão 401 Acesso não autorizado. Girar quando:

  • Você suspeita que haja um vazamento.
  • Um colega de equipe ou prestador de serviços com acesso deixa a empresa.
  • Você enviou uma chave para o controle de versão sem querer.

Caso contrário, as chaves não têm prazo de validade — elas continuam funcionando até que você as gere novamente ou seu plano seja rebaixado.

do plano#

Assim que uma chave for associada a uma conta, o servidor verifica se o acesso à API está habilitado para essa conta. Caso contrário, você receberá um erro HTTP 403, mesmo que o formato da chave seja válido. Reduções de plano ou cancelamentos podem remover o acesso imediatamente.

de equipes e organizações#

As chaves são emitidas por usuário. Em configurações de equipe, o uso e o acesso seguem as regras de cobrança da sua organização no produto — use a página da API e o painel dentro do aplicativo para obter informações oficiais sobre a sua licença.

por sessão vs. autenticação por chave de API#

As rotas do WinningHunter se dividem em três tipos. Certifique-se de que está falando com a pessoa certa.

Prefixo de rota Autenticação Quando usar
/api/v1/tiktok-shop/* Chave da API (Chave X-API) Todas as integrações programáticas/externas. Passam por créditos + limite de taxa.
/api/tiktok-shop/*, /api/detalhes-do-produto/*, etc. Sessão do navegador com login (cookies) Utilizados apenas pelo aplicativo web. São não a área da chave API — usar /api/v1/tiktok-shop/* para integrações.
/api/v1/adlibrary, /api/v1/magic-ai, /api/v1/store-tracker, /api/v1/store-explorer, /api/v1/marcas Chave da API A área programática fora do TikTok. A mesma forma de medição que /api/v1/tiktok-shop/*. O arquivo sem versão /api/<x> os formulários são mantidos como aliases compatíveis com versões anteriores para biblioteca de anúncios, rastreador de lojas, e explorador de lojas apenas — as novas integrações devem utilizar os caminhos da v1. /api/magic-ai e /api/marcas (não v1) são painel de controle, sessão, rotas, e não a interface da chave de API, pois as páginas do painel de controle ainda enviam solicitações POST/GET para essas URLs; os principais clientes devem usar /api/v1/magic-ai e /api/v1/marcas.

Se você estiver escrevendo um script ou uma integração de backend, quase sempre vai querer /api/v1/tiktok-shop/... além das poucas rotas não relacionadas ao TikTok mencionadas acima. A superfície completa está documentada no Referência da API e os guias temáticos (TikTok Shop, biblioteca de anúncios da Meta, Marcas, etc.).

Verificando se a chave

A maneira mais barata de fazer um teste de funcionalidade é GET /api/v1/tiktok-shop/credits — ela retorna o saldo atual e custa 1 crédito:

curl -i \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/credits"

A 200 com JSON significa: chave válida, plano OK, limite de taxa e créditos em bom estado. Para qualquer outro status, consulte Erros.

de segurança#

  • Armazene as chaves em variáveis de ambiente ou em um repositório seguro de credenciais — nunca no código do lado do cliente, em aplicativos móveis ou em pacotes de navegador.
  • Utilização Chave X-API ou Autorização: ao portador, e não no parâmetro de consulta, sempre que possível.
  • Realizar uma rotação após qualquer incidente, sempre que houver uma mudança na composição da equipe e, no mínimo, uma vez por ano.
  • Não compartilhe chaves entre ambientes — gere uma para cada conta de serviço e faça a rotação de forma independente.