Public API

Client script'in kullandığı tüm public (kimlik doğrulaması gerektirmeyen, istemci tarafı) HTTP endpoint'leri burada belgelenmiştir. Bunları mobil uygulama veya sunucu tarafı (headless) entegrasyonlarda doğrudan çağırabilirsiniz.

Taban adres ve kimlik doğrulama

• Taban adres: https://api.selwise.com/api/v1
• Yol kalıbı: /public/sites/:siteKey/...
• Kimlik doğrulama: Bu endpoint'ler API token istemez. Bunun yerine güvenlik domain doğrulamasından gelir: istekler, doğrulanmış site alan adınızın Origin veya Referer başlığını taşımalıdır. Tarayıcı başlığı olmayan istekler (mobil/sunucu) için x-selwise-api-key başlığı kullanılır.

Hız sınırları

Endpoint grubu	Sınır
Genel public	~1000 istek/dk
Event batch	Ziyaretçi başına 120 event/dk; IP başına daha yüksek güvenlik sınırı
Sipariş	IP başına 10 sipariş/dk

Bootstrap: tracking-config

Client'ın açılışta ilk çektiği yapılandırma.

GET /api/v1/public/sites/:siteKey/tracking-config

Örnek yanıt:

{
  "batchingEnabled": false,
  "batchSize": 50,
  "flushInterval": 30,
  "offlinePersistence": true,
  "sendBeaconOnUnload": true,
  "maxRetries": 3,
  "maxQueueSize": 100,
  "maxStorageEvents": 50,
  "debugMode": false,
  "dataLayerConfig": { "enabled": true, "variableName": "selwiseLayer" },
  "geo": { "country": "TR" }
}

geo yalnızca ülke çözülebildiğinde döner ve önbelleğe alınmaz (istek başına eklenir).

Toplu içerik: config

Kampanya, widget, öneri ve takip yapılandırmasını tek çağrıda döndürür (dört ayrı isteğin yerine).

GET /api/v1/public/sites/:siteKey/config

{
  "campaigns": [
    {
      "id": "uuid",
      "type": "announcement_bar",
      "contentJson": {},
      "stylesJson": {},
      "placementConfigJson": {},
      "pageTargetingJson": {},
      "segmentTargetingMode": "all",
      "segmentIds": []
    }
  ],
  "widgets": [],
  "recommendations": [],
  "tracking": { "batchingEnabled": false, "batchSize": 50 },
  "geo": { "country": "TR" }
}

Event takibi: events/batch

Event'ler tek tek değil, toplu gönderilir.

POST /api/v1/public/sites/:siteKey/events/batch
Content-Type: application/json
Origin: https://magaza.com

İstek gövdesi:

{
  "requestId": "istemci-uretimli-idempotency-anahtari",
  "sessionId": "SESSION_ID",
  "consentSnapshot": {
    "granted": true,
    "categories": { "analytics": true, "marketing": false },
    "timestamp": 1767312000000,
    "source": "banner"
  },
  "visitorId": "VISITOR_ID",
  "siteUserId": "user-42",
  "pageUrl": "https://magaza.com/urun/sku-123",
  "referrer": "https://google.com",
  "journeyId": "JOURNEY_ID",
  "events": [
    {
      "eventId": "olay-idempotency-anahtari",
      "entityType": "product",
      "productItemCode": "SKU-123",
      "name": "product_view",
      "metadata": { "price": 149.9, "currency": "TRY" },
      "eventTs": 1767312000123,
      "journeyId": "JOURNEY_ID",
      "journeySequence": 3
    }
  ]
}

Alan notları:

Alan	Zorunlu	Açıklama
requestId	Evet	Batch için idempotency anahtarı (tekrar gönderimde çift işlemeyi önler).
sessionId	Evet	Oturum kimliği.
consentSnapshot	Evet	O anki onay durumunun anlık görüntüsü.
events[]	Evet	En fazla 200 event.
events[].entityType	Evet	campaign / widget / recommendation / search / script / page / product / basket / checkout / user / custom.
events[].name	Evet	Kanonik event adı. Bkz. Event Referansı.
events[].productItemCode	Ürün olaylarında	Besleme SKU'su.
events[].metadata	Hayır	Event başına en fazla 2 KB.

Sipariş: orders

POST /api/v1/public/sites/:siteKey/orders

Alanlar ve örnekler için bkz. Sipariş Takibi. Özet gövde:

{
  "orderId": "ORDER_12345",
  "currency": "TRY",
  "total": 129.90,
  "subtotal": 119.90,
  "shippingTotal": 20.00,
  "items": [
    { "productItemCode": "SKU-RED-XL", "name": "Tişört", "quantity": 1, "unitPrice": 129.90 }
  ]
}

Yanıt:

{ "success": true, "created": true, "id": "order-uuid" }

Aynı orderId aynı pencere içinde tekrar gönderilirse HTTP 409 döner (tekilleştirme).

Onay: consent

POST   /api/v1/public/sites/:siteKey/consent
DELETE /api/v1/public/sites/:siteKey/consent

Gövde ve davranış için bkz. Onay Yönetimi.

Arama

GET  /api/v1/public/sites/:siteKey/search?q=...&limit=24&category=...&minPrice=...&maxPrice=...&inStock=true
GET  /api/v1/public/sites/:siteKey/search-config
GET  /api/v1/public/sites/:siteKey/search/suggestions?q=...
POST /api/v1/public/sites/:siteKey/search/log
POST /api/v1/public/sites/:siteKey/search/click
POST /api/v1/public/sites/:siteKey/search/zero-results

Arama yanıtı (özet):

{
  "hits": [],
  "total": 42,
  "took": 12,
  "categories": [],
  "suggestions": [],
  "strategy": "standard",
  "traceId": "uuid"
}

q zorunludur (maks. 200 karakter), limit 100 ile sınırlıdır. search/log, search/click ve search/zero-results analitik amaçlıdır. Detay: Arama modülü.

Öneriler

GET  /api/v1/public/sites/:siteKey/recommendations?pageUrl=...
POST /api/v1/public/sites/:siteKey/recommendations/:widgetId/products
POST /api/v1/public/sites/:siteKey/recommendations/track/event
POST /api/v1/public/sites/:siteKey/recommendations/track/behavior

• recommendations — Sayfa için uygun öneri widget'larını döndürür (pageUrl ile sayfa hedeflemesi değerlendirilir).
• :widgetId/products — Belirli widget için önerilecek ürünleri döndürür. Gövde: currentProductId?, sessionId?, visitorId?, userId?.
• track/event — Öneri gösterim/tıklama/sepet/satın alma olayını bildirir.
• track/behavior — Davranış (view, add_to_cart, purchase, wishlist) bildirir. productItemCode zorunludur.

Detay: Öneriler modülü.

Metrikler

POST /api/v1/public/sites/:siteKey/metrics

İstemci tarafı SDK metriklerini (düşen event, başarısız batch, gecikme örnekleri vb.) izleme amacıyla gönderir. Client bunu otomatik kullanır; normal entegrasyonda elle çağırmanız gerekmez.