Krediler ve faturalandırma

Başarılı sonuçlanan her API anahtarı talebi, aylık API kredilerinden düşülür. Bu kılavuzda, kota, kotanın ne zaman sıfırlandığı, hangi taleplerin ücretlendirilebilir sayıldığı ve kullanımın nasıl izleneceği açıklanmaktadır.

Kota#

Kota dolduğunda, bundan sonraki her istek şu yanıtı verir:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "success": false,
  "error": "Monthly credit limit reached (20000). Resets next month.",
  "credits": { "used": 20000, "limit": 20000, "remaining": 0 }
}

Sayaç, bir sonraki takvim ayının başında otomatik olarak sıfırlanır — herhangi bir işlem yapmanız gerekmez.

Neler önemlidir (ve neler değildir)#

Her ölçümlü programatik çağrı, asıl işin çalıştırılmasından önce 1 kredi tutarında bir deneme yapar. Ücretlendirme işleminden sonra sunucuda yakalanmamış bir hata meydana gelirse, kredi iade edilir; bu hata nedeniyle sizden herhangi bir ücret alınmaz.

Ücretli güzergâhlar şunlardır:

• Tümü /api/v1/tiktok-shop/* uç noktalar.
• GET /api/v1/adlibrary.
• POST /api/v1/magic-ai.
• GET /api/v1/store-tracker, POST /api/v1/store-explorer.
• GET /api/v1/markalar.

Sürüm numarası yok /api/adlibrary, /api/mağaza-izleyicive /api/mağaza-keşfi hala takma ad olarak kabul edilmektedir (aynı ölçüm). /api/magic-ai ve /api/markalar şunlardır kontrol paneli yollar — bir API anahtarı için /api/v1/magic-ai ve /api/v1/markalar.

Herhangi bir ücret tahsil edilmeden önce, bu yanıtlar ücretlendirilmeden geri gönderilir (ve dakika başına ücret sınırına dahil edilmez ):

• 401 Yetkisiz — anahtar eksik veya geçersiz.
• 403 — Hesap için API erişimi etkinleştirilmemiştir.

Doğru cevaplar ve çoğu 429 satırlar şunlardır kayıt altına alınır ve şuna dahil edilir 60/dk pencere (bkz. Hız sınırları).

Kontrol Paneli ve API Karşılaştırması#

Tarayıcı uygulaması, ham API anahtarı çağrılarından farklı bir ölçümleme yöntemi uygulayabilir. Entegrasyonlar söz konusu olduğunda, sözleşmenizde aksi belirtilmedikçe, ölçümlenen her başarılı istek için 1 kredi olduğunu varsayınız.

Kredi kullanımının izlenmesi#

Programatik#

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

Aynı sonucu verir { kullanılmış, sınır, kalan } 429 gövdesinin sahip olduğu şekil. 1 kredi tutar (evet, bakiye kontrolü 1 kredi keser; bunu istemci tarafında önbelleğe alın).

Kontrol Paneli#

Oturum açılmışken:

• GET /api — görsel kaynaklar widget'ı + 14 günlük kullanım grafiği + son istek günlüğü.
• GET /api/kullanım — JSON: { usage: [{ day, requests }, …], credits: { used, limit, remaining } }.
• GET /api/logs?page=N — Durum kodları ve IP adreslerini içeren, sayfa başına 50 satırlık sayfalara bölünmüş istek günlüğü.

Bu üçü yalnızca oturum süresince geçerlidir (çerezler). Kredi harcamazlar.

MCP ve jeneriği#

Model Bağlam Protokolü şunu kullanır aynı aylık havuz (20.000). Her başarılı MCP araçlar/çağrı masraflar 1 kaynak — aşağıdakiler gibi araçlar dahil kredileri kontrol et. başlat, araçlar/liste, ping, vb. değil ücret.

MCP aracı trafiğinin kendine özgü kendi dakika başına patlama sınırı (bkz. MCP); bu, bu kılavuzdaki REST hız sınırlaması konusunun yerine geçmez /api/*.

Kapasite planlaması#

Sürekli ETL veya geriye dönük veri doldurma iş yükleri için, tasarımınızı dakika başına kapasiteye değil, günlük kapasiteye göre yapın. Hız sınırı ani yük artışlarını (dakikada 60) sınırlar; kredi kotası ise toplam hacmi (ayda 20.000) sınırlar.

Kredilerinizi en verimli şekilde kullanmanızı sağlayan stratejiler#

• Şu öğelerle birlikte YAYIN JSON. Tek bir istekte gönderilen büyük filtre kümeleri, çok sayıda küçük filtre kümesinden daha üstündür.
• Önbellekte saklanan aramalar. Kategori hiyerarşileri, ülke listeleri, filtre ön ayarları — en fazla günde bir kez alın.
• Kullanım sayı önce keşfet sadece bir sayıya ihtiyacınız olduğunda.
• Anket yapmayın krediler agresif bir şekilde — her çağrı 1 kredi tutar. Kullanımı kendi yanıt sayacınızla istemci tarafında takip edin ve /api/v1/tiktok-shop/krediler saatte bir kez.

Sıfırlama davranışı#

Sunucuda kullanım, her takvim ayının başında (UTC) sıfırlanır. Yeni ayın ilk ölçülen isteği, otomatik olarak yeni bir sayaç alır.

Peki ya plan değişiklikleri?#

• Ay ortasında yükseltme: Mevcut kredi sayacınız çalışmaya devam eder; limit 20.000 olarak kalır (kota, kullanıcı başına belirlenir, seviye başına değil).
• API erişiminin kesilmesi: Erişim yeniden sağlanana kadar ücretli aramalar 403 hatası verir; aynı dönem içinde erişimi yeniden etkinleştirirseniz, önceki kullanım sayacı değerleri genellikle devredilir — kontrol panelinden teyit edin.
• Daha yüksek hacimli ihtiyaçlar: Özel bir limit belirlemek için destek ekibiyle iletişime geçin.