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.

Ö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.

Kimliklendirme: users/identify

POST /api/v1/public/sites/:siteKey/users/identify
POST /api/v1/public/sites/:siteKey/users/traits

Anonim ziyaretçiyi kendi kullanıcı kimliğinizle birleştirir. identify gövdesi:

{
  "externalId": "musteri-1234",
  "visitorId": "selwise-visitor-id",
  "sessionId": "selwise-session-id",
  "email": "musteri@ornek.com",
  "traits": { "plan": "gold", "city": "Istanbul" },
  "pageUrl": "https://magaza.com/hesabim"
}

Yalnızca externalId zorunludur. email saklanmadan önce hash'lenir; ham adres tutulmaz.

traits yalnızca öznitelik güncellemek için tek başına da gönderilebilir:

{ "externalId": "musteri-1234", "traits": { "plan": "platinum" } }

Bu iki endpoint hız sınırının dışındadır: kimlik birleştirmenin kaybedilmesi, sonraki her ölçümü bozar.

Ürün metrikleri: product-metrics

product_view_count ve cart_count widget'larının okuduğu sayılar. Widget'ları kullanmıyor, kendi arayüzünüzü yazıyorsanız doğrudan çağırabilirsiniz.

GET  /api/v1/public/sites/:siteKey/product-metrics/view-count?product=SKU-12345&period=24h
GET  /api/v1/public/sites/:siteKey/product-metrics/cart-count?product=SKU-12345
POST /api/v1/public/sites/:siteKey/product-metrics/batch

Parametre	Değerler	Varsayılan
product	Ürün kodu (SKU / item code), maks. 200 karakter	zorunlu
period	1h, 24h, 7d, 30d	24h
metric	active_carts	active_carts

Yanıt:

{ "count": 128, "formatted": "128" }

Sayılan şey tekil ziyaretçidir, gösterim değil. Aynı kişinin bir ürüne on kez bakması sayıyı bir arttırır. cart-count yalnızca son 24 saatteki aktif sepetleri sayar.

Tek üründe birden fazla widget varsa batch tek istekte hepsini döndürür:

{
  "products": [
    { "itemCode": "SKU-12345", "widgetId": "widget-uuid", "config": { "type": "product_view_count", "timePeriod": "24h" } },
    { "itemCode": "SKU-12345", "widgetId": "other-uuid", "config": { "type": "cart_count", "metricType": "active_carts" } }
  ]
}

Yanıtlar sunucuda önbelleklenir (görüntüleme 2 dakika, sepet 1 dakika), yani bu uçlar gerçek zamanlı değil "az gecikmeli" sayılardır. Ürün sayfası her yüklendiğinde çağırmak güvenlidir.

Zenginleştirme: enrichments

GET /api/v1/public/sites/:siteKey/enrichments?code=SKU-12345

Bir ürün koduna atanmış, aktif zenginleştirme bloklarını çözümlenmiş hâlde döndürür — çakışma sıralaması sunucuda yapılmıştır:

{
  "v": "surum-imzasi",
  "items": [
    {
      "assignmentId": "uuid",
      "selector": ".product-description",
      "insertPosition": "after",
      "order": 0,
      "blocks": [
        { "blockId": "uuid", "html": "<table>…</table>", "css": ".x{}", "reservedHeightPx": 240 }
      ]
    }
  ],
  "tokens": { "code": "SKU-12345", "title": "Ürün Adı", "price": 199.9, "currency": "TRY", "inStock": true }
}

• items render sırasındadır; bir kural birden fazla blok taşıyabilir ve bunlar tek kök altında render edilip tek gösterim sayılır.
• tokens, blok markup'ındaki ${...} yer tutucularını doldurmak içindir.
• html ve css satıcı tarafından yazılmış içeriktir; widget bunları DOM'a koymadan önce sanitize eder. Kendi arayüzünüzde kullanıyorsanız sanitizasyon sizin sorumluluğunuzdadır.
• Test modundaki kuralları da almak için &test=1 ekleyin.

Kod bulunamazsa, boş gönderilirse veya 100 karakterden uzunsa endpoint hata değil boş yanıt döner (items: []) — widget bu kodu satıcının kendi DOM'undan okur ve orada bir 400, üzerine işlem yapamayacağı gürültüdür.

Bülten kaydı: newsletter

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

newsletter widget'ının gönderdiği kayıt. Gövde:

{
  "email": "musteri@ornek.com",
  "fullName": "Ad Soyad",
  "locale": "tr",
  "visitorId": "selwise-visitor-id",
  "siteUserId": "musteri-1234",
  "sourcePath": "/kampanya",
  "utmSource": "instagram",
  "utmMedium": "story",
  "utmCampaign": "bahar",
  "honeypot": ""
}

Yalnızca email zorunludur. honeypot boş kalmalıdır — dolu gelen istek bot kabul edilir. Dakikada 20 istekle sınırlıdır.

Pazarlama izni: contacts/consent

POST /api/v1/public/sites/:siteKey/contacts/consent
x-selwise-api-key: swpk_live_…

Bir alışverişçinin e-posta veya SMS aboneliğini kendi sunucunuzdan açıp kapatmanın yolu: hesabım sayfasındaki iletişim tercihleri, CRM, çağrı merkezi. Anahtar yalnızca newsletter_subscribe kapsamını taşımalıdır ve bu uç her zaman anahtar ister; tarayıcıdan çağrılmaz.

{
  "contacts": [
    { "kind": "email", "value": "musteri@ornek.com", "siteUserId": "MUSTERI-1001", "optIn": true, "note": "Hesabım > İletişim tercihleri" },
    { "kind": "phone", "value": "+905321112233", "optIn": true, "iys": "registered" },
    { "kind": "phone", "siteUserId": "MUSTERI-1001", "optIn": false }
  ]
}

Alan	Açıklama
kind	email veya phone
value	Adres ya da E.164 telefon. Hiç kaydı olmayan bir adrese izin vermek için zorunlu.
siteUserId	Sizin müşteri kimliğiniz. value ile birlikte verilirse kayıt bu müşteriye bağlanır; tek başına verilirse karar müşterinin o türdeki tüm adreslerine uygulanır.
optIn	true izin verir, false geri çeker
iys	Yalnızca telefon: numaranın İYS kaydı (registered, rejected). Selwise İYS'ye sizin adınıza başvuru yapmaz.
note	İznin kanıtı — alışverişçinin gördüğü metin gibi

Tek istekte en fazla 500 kayıt. Yanıt her kayıt için ne olduğunu söyler:

{ "success": true, "received": 3, "processed": 3, "results": [
  { "index": 0, "status": "resubscribed" },
  { "index": 1, "status": "subscribed" },
  { "index": 2, "status": "unsubscribed" }
] }

status	Anlamı
subscribed	İzin kaydedildi
resubscribed	Daha önce aboneliğini iptal etmiş biri yeniden izin verdi
unsubscribed	İzin geri çekildi
withdrawal_recorded	Hiç görülmemiş bir adres için ret kaydedildi; sonradan gelen bir toplu aktarım bu adresi aboneye çeviremez
unchanged	Kayıt zaten istenen durumdaydı
not_found	Yalnızca siteUserId verildi ama bu müşterinin o türde kaydı yok — izin vermek için value gönderin
invalid	Adres geçersiz

Tekil içerik uçları

config hepsini tek istekte döndürür ve açılışta tercih edilmesi gereken yol odur. Tek bir bölümü yenilemek için:

GET /api/v1/public/sites/:siteKey/widgets
GET /api/v1/public/sites/:siteKey/campaigns
GET /api/v1/public/sites/:siteKey/scripts?path=/urun/abc

Üçü de tek anahtarlı bir nesne döndürür — { "widgets": [] }, { "campaigns": [] }, { "scripts": [] } — ve yalnızca aktif kayıtları içerir.

widgets ve campaigns aynı şekli taşır: id, type, isTestMode, contentJson, stylesJson, placementConfigJson, customCss, customJs, varyant alanları (variantId, variantVersion, variantCustomized, variantSnapshotJson), pageTargetingJson, segmentTargetingMode, segmentIds. Tanınmayan bir type yanıttan süzülür, stylesJson ve placementConfigJson tipe göre sunucuda sanitize edilir.

scripts diğer ikisinden bir noktada ayrılır: yol bazında filtrelenir. path parametresi verilmezse / varsayılır, yani parametresiz çağrı ana sayfa için tanımlı scriptleri döndürür — sitenin tamamını değil. Belirli bir sayfanın scriptlerini istiyorsanız o sayfanın yolunu geçmeniz gerekir.

Açılışta üçünü ayrı ayrı çağırmak, config'i bir kez çağırmaya göre üç kat istek demektir.

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.