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

Guias

Intervalos de tempo

Different parts of the API use different date filters. This guide is the cheat sheet — pick the right one for the endpoint you're calling, and don't mix them.

At a glance

Surface Parâmetro Typical values
TikTok Shop explore / count / detail período 7d, 30d, 90d, sometimes todos
Brands tracker (dashboard /api/brands/..., session) período + optional data_de, data_até ao vivo, 7d, 30d, 3m, 6m, custom
TikTok Shop visit-event endpoints período 7d, 30d, todos (padrão 30d)
GET /api/v1/tiktok-shop/products data_de, data_até D-m-a strings
Ad library (API key: /api/v1/adlibrary or alias /api/adlibrary) Same query string as the dashboard's /api/fb-ads (ver Biblioteca de anúncios do Meta). Per-parameter there.

The single most common mistake: sending start_date / end_date alongside período on TikTok Shop endpoints. Don't — those fields collide with the period-aware revenue mapping upstream and silently filter out most data. Pass only período unless the docs for a specific endpoint say otherwise.

TikTok Shop período

Used by explorar, contar, detail aggregates, history, and most metric-bearing endpoints under /api/v1/tiktok-shop/.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/products/explore?country=US&period=30d&limit=20"
  • Treat período as an opaque string that mirrors the in-app filter UI (7d, 30d, 90d, …). The backend maps it to period-specific fields like revenue_30d, revenue_growth_rate_7d, etc.
  • Do não also send start_date / end_date. The TikTok Shop API does not map those to the explore flow — sending them can trigger narrow “first seen in last N days” behavior upstream and return a tiny slice of the catalog.
  • Sort keys (sort=) follow the same period — passing sort=revenue with period=7d becomes revenue_7d upstream.
  • For aggregate revenue numbers (e.g. shop totals), the period determines which revenue.{key} field you should read in the response.

Visit-event endpoints (product-other-visits, category-visit-events, detail-visit-events)

These accept a more limited set:

period= Janela
(omitted) Defaults to 30d
7d, 30d Rolling N-day window
todos / alltime Lifetime totals
<integer> (por exemplo, 90) Treated as Nd

The response includes period_label (por exemplo, "Last 30 days") so you can display it without parsing.

Brands tracker período

Used by dashboard routes such as /api/brands/ads, /api/brands/ad-copies, /api/brands/ad-headlines, /api/brands/ad-hooks, /api/brands/personas, /api/brands/themes, and the other brand-detail tabs (session).

GET /api/brands/ads?id={page_id}&date_range=30d
GET /api/brands/ad-copies?id={page_id}&date_range=custom&date_from=2026-01-01&date_to=2026-03-31

Accepted values (same semantics as the Brand tracker date picker in the app):

date_range= Effect
(omitted) ou todos No date filter.
ao vivo Ads last seen in the last 3 days (uses the atualizado em field).
7d, 30d, 3m, 6m Ads with start date on or after the rolling cutoff (começou field).
custom Requires both data_de e data_até as D-m-a.

A few tips:

  • The same three params (período, data_de, data_até) carry across every brand-detail tab. Once you have a date filter for the user, reuse it on every call you make for that brand session.
  • ao vivo is the only value keyed off "last seen", not "started". Don't confuse it with 7d.
  • custom without both data_de e data_até falls back to "no date filter".

The brand-detail surface is session-only (logged-in browser), so this section applies when you mirror the dashboard, not when you use GET /api/v1/marcas alone. Full reference: Marcas e acompanhamento de marcas.

GET /api/v1/tiktok-shop/products

This route is a flat listing endpoint that takes a small set of GET params, including explicit dates:

GET /api/v1/tiktok-shop/products
  ?country=US
  &date_from=2026-03-01
  &date_to=2026-03-31
  &search=mascara
  &min_price=10&max_price=50
  &min_sales=100
  &min_rating=4
  • Ambos data_de e data_até são D-m-a strings.
  • Either may be omitted; the upstream applies a sane default if so.
  • This is the only TikTok Shop flat-listing path where data_de / data_até are first-class params. On every other path, prefer período.

Why mixing time params goes wrong

A common failure mode: copying a "products explore" request and adding start_date=2026-01-01 thinking it'll narrow the window. What actually happens:

  1. The explore handler keeps period=30d (default).
  2. It also forwards your start_date / end_date.
  3. Upstream interprets that as "first seen between those dates".
  4. You get back ~5% of the catalog — only items first crawled in that exact window.

Fix: choose one mechanism per request. If período covers your need, use it alone. If you genuinely need a custom range, use the routes that document data_de / data_até (the Brands tracker, the flat produtos listing, the ad library).

Quick decision tree

  • Calling /api/v1/tiktok-shop/... explore / count / detail / history? → period=7d|30d|90d.
  • Calling /api/v1/tiktok-shop/products (flat listing)? → data_de, data_até.
  • Calling /api/v1/tiktok-shop/...visit-events* ou product-other-visits? → period=7d|30d|all.
  • Calling /api/marcas/* (dashboard session)? → período, plus data_de + data_até if date_range=custom. (Tracked list with an API key: GET /api/v1/marcas — no período on that route.)
  • Calling /api/v1/adlibrary ou /api/adlibrary (Meta ads)? → see Biblioteca de anúncios do Meta.