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

API · TikTok Shop

API de sugestões de pesquisa da TikTok Shop

Endpoint (API key)

GET /api/v1/tiktok-shop/suggestions

Send Chave X-API (ou Autorização: ao portador) like every other metered programmatic route. Behavior matches the in-app autocomplete for the same path shape.

Dashboard (session): GET /api/tiktok-shop/suggestions — used when you are logged into the web app. For scripts and integrations, always use the /api/v1/... URL.

Description

Autocomplete for TikTok Shop entities (categorias, lojas, criadores, produtos, vídeos): short id + nome rows as the user types.

Request Parameters

Parâmetro Tipo Obrigatório Descrição Exemplo
tipo cadeia de caracteres Sim Tipo de entidade a pesquisar categorias, lojas, criadores, produtos, vídeos
q cadeia de caracteres Sim Consulta de pesquisa (correspondência parcial do nome) fash, Nike, elegido
limite número inteiro Não Maximum number of suggestions to return (default: 10, cap enforced server-side) 5, 10, 20

Response Format

Success Response

Código de status: 200 OK

Tipo de conteúdo: application/json

{
  "success": true,
  "suggestions": [
    {
      "id": "category_12345",
      "name": "Fashion & Apparel"
    },
    {
      "id": "category_67890",
      "name": "Fitness Equipment"
    }
  ]
}

Error Response

Código de status: 400 Solicitação inválida

{
  "success": false,
  "error": "Invalid entity type"
}

Código de status: Erro 500 do servidor interno

{
  "success": false,
  "error": "Internal server error"
}

Entity Types

Tipo Typical id Typical nome Descrição
categorias Category id or path Category label Categorias de produtos
lojas Shop id Nome da loja Lojas do TikTok
criadores Creator id Username or display name Creators / affiliates
produtos Product id Título do produto Produtos
vídeos Video id Título do vídeo Video content

Request Examples

cURL

# Replace {origin} and $WH_API_KEY.
curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=categories&q=fash&limit=10"

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=shops&q=nike&limit=5"

curl -sS -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/suggestions?type=creators&q=fitness&limit=10"

JavaScript Fetch

// Programmatic (API key)
const response = await fetch(`${ORIGIN}/api/v1/tiktok-shop/suggestions?type=categories&q=fash&limit=10`, {
  headers: {
    Accept: 'application/json',
    'X-API-Key': process.env.WH_API_KEY,
  },
});

const data = await response.json();
console.log(data.suggestions);
// [{ id: "category_123", name: "Fashion & Apparel" }, ...]

Behavior Notes

  • Matching: Case-insensitive partial match on the primary label field for each entity (for creators, both username and display name are considered).
  • Sorting: Results are ordered by a popularity-style signal per entity (e.g. revenue, followers, views) so common matches surface first.
  • Empty input: Very short queries may return an empty sugestões array; the web app often waits until at least 2 characters before calling.
  • Client UX: If you build a typeahead, debounce requests (~300ms) and cache recent tipo+q pairs briefly to avoid redundant calls (same idea as the in-app search bar).

Auth and errors

  • /api/v1/tiktok-shop/suggestions uses your Chave da API and the same metering as other /api/v1/tiktok-shop/* routes.
  • Alça 401 / 403 de Autenticação e 429 de Limites de taxa / Créditos like any other programmatic call.

See also