API rehberi

Kimlik doğrulama ve işletme kapsamı

Temel adres: https://webdesiz.com/api/v1/developer

İşletme OWNER veya ADMIN üyesi Ayarlar → Geliştirici anahtarları ekranında anahtar oluşturur. Gereken okuma izinlerini ve 1–90 günlük süreyi seç. İşletme başına en çok 10 aktif, süresi dolmamış anahtar bulunabilir. Tam anahtar bir kez gösterilir; işletim sisteminin veya uygulamanın sır yöneticisinde sakla.

Anahtarı yalnız Authorization başlığında Bearer olarak gönder. İşletme ve anahtarı oluşturan üye sunucuda bağlanır; istemci başka işletme seçemez. Her istek süreyi, iptali, oluşturan kişinin güncel üyeliğini ve gereken izni kontrol eder.

// Node.js 22; inject WEBDESIZ_API_KEY from your secret manager.
const key = process.env.WEBDESIZ_API_KEY;
if (!key) throw new Error('Missing credential');
const response = await fetch(
  'https://webdesiz.com/api/v1/developer/accounts?limit=20',
  {headers: {Authorization: 'Bearer ' + key}, redirect: 'error'}
);
if (!response.ok) throw new Error('HTTP ' + response.status);
const snapshot = await response.json();

Anahtarı URL’ye, komut argümanına, kaynak dosyaya, paylaşılan MCP ayarına veya sohbete koyma. Panel oturumunun JWT değeri geliştirici API anahtarı değildir.

Panelde anahtar oluştur veya iptal et

Bu bağlantının kapsamı

Üç anahtar yönetim rotası oturum açılmış panel kimliğini kullanır. Dış geliştirici anahtarı sözleşmesinin parçası değildir.

Okuma uçları

Üç rota da Cache-Control: no-store ile JSON döndürür. Mevcut Webdesiz kayıtlarını okur; verileri yenilemek için Meta’ya çağrı yapmaz. OpenAPI 3.1 JSON

Sorgu parametreleri

İstatistik tarih aralığı iki sınırı da içerir. Geçerli tarihler, from ≤ to, en çok 90 gün ve gelecekte olmayan bitiş tarihi gerekir. Tarihler kayıtlı günlük satırları filtreler. Bilinmeyen sorgu alanları reddedilir; işletme kimliği, URL veya kimlik bilgisini sorgu parametresi olarak gönderme. from/to hesap ve kampanya sonuçlarını filtrelemez.

Yanıt alanları

Başarılı yanıtlar data (dizi) ve meta alanlarını içerir. Boş data dizisi geçerli bir sonuçtur. Aşağıdaki zarf açıklayıcı örnektir; müşteri verisi değildir:

{
  "data": [],
  "meta": {
    "source": "stored_snapshot",
    "liveMetaRequest": false,
    "limit": 50,
    "offset": 0,
    "nextOffset": null,
    "returned": 0,
    "generatedAt": "2026-10-04T00:00:00.000Z",
    "dataAsOf": "Each row reports its own lastSyncAt or syncedAt; this request does not refresh data.",
    "note": "Stored values may be stale. Account-level and campaign-level insight rows are different aggregation levels; do not sum them together. Currency is per account."
  }
}

spend, dailyBudget, ctr ve cpc gibi kayıtlı ondalık para ve oran alanları JSON metnidir; purchases, purchaseValue ve roas sayı veya null olabilir. Sonuçları birleştirirken her hesabın para birimini koru. Sağlayıcının ham veri yükü ve hesap erişim tokenları dönmez.

Sayfalama

offset=0 ile başla. meta.nextOffset sayıysa sonraki sayfada aynı filtrelerle kullan; null olduğunda dur. Tam dolu son sayfa, bir sonraki boş sayfaya işaret edebilir. Hesap ve kampanyalar id sırasıyla, istatistikler tarih azalan ve ardından id artan sırasıyla gelir. Offset sınırı 10000’dir; bu sınırsız dışa aktarma veya işlem boyunca değişmez bir veri kümesi değildir.

Güncellik ve ölçüm

generatedAt yanıtın hazırlanma zamanıdır; Meta verisinin yenilenme zamanı değildir. Hesaplarda lastSyncAt, kampanya ve istatistiklerde syncedAt değerini kullan. Null veya eski zamanlar verinin güncel olduğunu göstermez. Güncellik için SLA taahhüdü verilmez.

campaignId=null hesap düzeyindeki satırı, campaignId bulunan satır kampanya düzeyini belirtir. Bu düzeyler örtüşebilir; ikisini tek toplama ekleme. Satın alma ölçümleri kayıtlı satın alma eylemi kanıtına dayanır. Kanıt yoksa sıfır yerine null döner; açıkça bildirilmiş sıfır korunur. purchaseMeasurement, reported_purchase_value, reported_purchase_count veya unavailable olur. ROAS yalnız değer mevcut ve spend pozitifse purchaseValue/spend olarak hesaplanır; aksi halde null döner.

Hatalar ve istek sınırları

Okuma sınırları paylaşılan 60 saniyelik pencerelerde anahtar başına 60, işletme başına 120 ve IP başına 180 istek/dakikadır. Geçersiz kimlik doğrulama da IP sınırını kullanır. Hata yanıtları statusCode, error, message, path ve timestamp içerir; geliştirici yolu ve mesajı bilinçli olarak geneldir. Ayrıntılı doğrulama mesajına bağlı uygulama yazma.