Zaman aralıkları

API'nin farklı bölümleri farklı tarih filtreleri kullanır. Bu kılavuz bir özet tablodur — çağırdığınız uç nokta için doğru olanı seçin ve bunları birbirine karıştırmayın.

Bir bakışta#

En sık yapılan tek hata: göndermek başlangıç_tarihi / bitiş tarihi yanında dönem TikTok Shop uç noktalarında. Sakın yapmayın — bu alanlar, yukarı akıştaki nokta duyarlı gelir eşlemesiyle çakışır ve verilerin çoğunu sessizce filtreler. Geç sadece dönem belirli bir uç nokta için belgelerde aksi belirtilmedikçe.

TikTok Mağazası dönem#

Kullanım alanı keşfet, sayı, ayrıntılı toplamlar, tarihçeve "altında" başlığı altındaki metrik içeren uç noktaların çoğu /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"

• Tedavi dönem bir opak ip uygulama içi filtre arayüzünü yansıtan (7d, 30d, 90d, …). Arka uç bunu dönemlere özgü alanlara eşler, örneğin 30 günlük gelir, 7 günlük gelir artış oranıvb.
• Yap değil ayrıca gönder başlangıç_tarihi / bitiş tarihi. TikTok Shop API'si bunları keşif akışına eşlemez — bu verilerin gönderilmesi, üst aşamada "son N gün içinde ilk kez görülenler" gibi dar kapsamlı bir davranışa yol açabilir ve kataloğun çok küçük bir kısmını döndürebilir.
• Sıralama anahtarları (sıralama=) aynı dönemi takip eder — geçerek sıralama=gelir ile süre=7 gün şu hale gelir 7 günlük gelir kaynak tarafında.
• Toplam gelir rakamları (ör. mağaza toplamları) için, dönem hangi gelir.{anahtar} yanıtta okumanız gereken alan.

Ziyaret-etkinlik uç noktaları (ürün-diğer-ziyaretler, kategori-ziyaret-etkinlikler, etkinliklere-ayrıntılı-ziyaret)#

Bunlar daha sınırlı bir kümeyi kabul eder:

Yanıt şunları içermektedir dönem etiketi (örneğin "Son 30 gün") böylece ayrıştırmaya gerek kalmadan görüntüleyebilirsiniz.

Marka takipçisi tarih aralığı#

Aşağıdaki gibi gösterge paneli rotaları tarafından kullanılır: /api/markalar/reklamlar, /api/markalar/reklam-metinleri, /api/markalar/reklam-başlıkları, /api/markalar/reklam-bağlantıları, /api/markalar/kullanıcı profilleri, /api/markalar/temalarve diğer marka ayrıntıları sekmeleri (oturum).

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

Kabul edilen değerler (uygulamadaki Marka takipçisi tarih seçiciyle aynı işlevsellik):

Birkaç ipucu:

• Aynı üç parametre (tarih aralığı, başlangıç tarihi, bitiş tarihi) her marka ayrıntıları sekmesine aktarın. Kullanıcı için bir tarih filtresi oluşturduktan sonra, o marka oturumu için yaptığınız her çağrıda bu filtreyi yeniden kullanın.
• canlı şudur sadece değer, "başlangıç" değil, "son görülme" zamanına göre belirlenir. Bunu şununla karıştırmayın 7d.
• özel ikisi de olmadan başlangıç tarihi ve bitiş tarihi "tarih filtresi yok" seçeneğine geri döner.

Marka bilgilerinin yer aldığı alan sadece oturum (oturum açılmış tarayıcı), dolayısıyla bu bölüm, kontrol panelini yansıtma işlemi sırasında geçerlidir; şu durumlarda değil: GET /api/v1/markalar tek başına. Tam kaynak: Markalar ve Marka Takibi.

GET /api/v1/tiktok-shop/products#

Bu rota, belirli tarihler de dahil olmak üzere az sayıda GET parametresi alan düz bir liste son noktasıdır:

GET /api/v1/tiktok-shop/products
  ?country=US
  &date_from=2026-03-01
  &date_to=2026-03-31
  &search=maskara
  &min_price=10&max_price=50
  &min_sales=100
  &min_rating=4

• Her ikisi de başlangıç tarihi ve bitiş tarihi şunlardır A-G-Y diziler.
• Her ikisi de atlanabilir; bu durumda üst katman makul bir varsayılan değer uygular.
• Bu sadece TikTok Shop'ta ürünlerin düz listeleme yolu başlangıç tarihi / bitiş tarihi birinci sınıf parametrelerdir. Diğer tüm durumlarda, dönem.

Zaman parametrelerini karıştırmak neden sorun yaratır?#

Sık karşılaşılan bir hata durumu: "ürünleri keşfet" isteğini kopyalayıp başlangıç_tarihi=2026-01-01 bunun aralığı daraltacağını düşünerek. Aslında olan şey:

1. "Explore" işleyicisi şunu tutar süre=30 gün (varsayılan).
2. Ayrıca, sizin başlangıç_tarihi / bitiş tarihi.
3. Upstream bunu "bu tarihler arasında ilk kez görüldü" şeklinde yorumluyor.
4. Kataloğun yaklaşık %5'ini geri alırsınız — yalnızca o zaman aralığında ilk kez taranan öğeler.

Çözüm: seçin bir istek başına mekanizma. Eğer dönem İhtiyacınızı karşılıyorsa, tek başına kullanın. Gerçekten özel bir aralığa ihtiyacınız varsa, belgelerde belirtilen yolları kullanın başlangıç tarihi / bitiş tarihi (Marka takipçisi, düz ürünler liste, reklam kütüphanesi).

Hızlı karar ağacı#

• Çağrı /api/v1/tiktok-shop/... keşfet / say / ayrıntı / geçmiş? → süre=7 gün|30 gün|90 gün.
• Çağrı /api/v1/tiktok-shop/ürünler (daire ilanı)? → başlangıç tarihi, bitiş tarihi.
• Çağrı /api/v1/tiktok-shop/...ziyaret-etkinlikleri* ya da ürün-diğer-ziyaretler? → dönem=7 gün|30 gün|tümü.
• Çağrı /api/markalar/* (kontrol paneli oturumu)? → tarih aralığı, ayrıca başlangıç tarihi + bitiş tarihi eğer date_range=özel. (API anahtarıyla izlenen liste: GET /api/v1/markalar — hayır tarih aralığı (o güzergâhta.)
• Çağrı /api/v1/adlibrary ya da /api/adlibrary (Meta reklamları)? → bkz. Meta reklam kütüphanesi.