# Açılış Uçları

Widget ve SDK’nın açılışta çektiği yapılandırma: config, kampanyalar, scriptler, ürün sayıları
Kaynak: https://selwise.com/docs/api-reference/bootstrap-endpoints

Widget'ın ve uygulama SDK'sının açılışta çektiği yapılandırma uçları. Widget kullanıyorsanız bunları çağırmanız gerekmez; kendi arayüzünü kuran (headless) bir entegrasyon ya da sunucu için buradadır. Kimlik ve sözleşme kuralları [API'ye Genel Bakış](/docs/api-reference/public-api) sayfasındadır.

## Açılış: config

Widget açılışta yapılandırmanın tamamını **tek istekte** çeker; dört ayrı isteğin yerine geçer.

```http
GET /api/v1/public/sites/{siteKey}/config
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Kararlı sözleşme

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |
| `p` | sorgu | `any` | Hayır | İstemcinin anlayabildiği protokol sürümü (güncel `4`). Bu sürümün çizemeyeceği bir kampanya yanıta konmaz. Verilmezse `1`. |
| `lang` | sorgu | `any` | Hayır | Ziyaretçinin ya da sayfanın dili (`tr`, `en-GB`…). Hesabın dillerinden en yakını seçilir; yoksa varsayılan dil. Tek dilli hesapta etkisi yoktur. |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `modules` | `map<string, boolean>` | Evet | Hesabın sözleşmesindeki modüller. Olmayan modülün içeriği aşağıda boş döner; widget o parçayı hiç indirmez. |
| `channel` | `ConfigChannel` | Evet | Kanalın türü (`web` veya `app`), paylaşılan katalog okuyup okumadığı ve para birimi. |
| `controlGroup` | `ConfigControlGroup` | Evet | Kanalın kontrol grubu açıksa yüzdesi ve kanal kimliği; kapalıysa `null`. Üyelik ziyaretçi kimliğinin özetiyle hesaplanır. · null olabilir |
| `campaigns` | `PublicCampaign[]` | Evet | Yayın penceresi şu an açık olan kampanyalar (`web_experience` modülü yoksa boş). Test modundakiler `isTestMode: true` ile gelir. |
| `widgets` | `any[]` | Evet | Kullanımdan kalktı, her zaman boş: widget'lar Eylül 2026'da kampanyalara birleşti. · en çok 0 öğe |
| `recommendations` | `PublicRecommendationWidgetSchema[]` | Evet | Etkin öneri şeritlerinin tanımı (`recommendations` modülü yoksa boş). Ürünler ayrıca şeridin ürünler ucundan alınır. |
| `tracking` | `TrackingSettings` | Evet | Olay toplama ayarları. `geo` yalnızca ülke çözülebildiğinde gelir. |
| `search` | `ConfigSearch` | Evet | Arama modülü açık ve etkinse `enabled: true`; widget arama parçasını buna bakarak indirir. |
| `enrichment` | `ConfigEnrichment` | Evet | Zenginleştirme yuvaları, içerik değil: `s` seçici, `p` ekleme konumu, `h` ayrılacak yükseklik (px), `k` yuvayı sunucuda dolduran adlar, `v` sürüm damgası. İçerik `enrichments` ucundan gelir. |
| `onsite` | `ConfigOnsite` | Evet | Sayfa üstü deneyler ve eylemleri. Ziyaretçinin kolu burada çözülmez; istemci kendisi hesaplar. |
| `scenarios` | `ConfigScenarios` | Evet | Kanalda site içi teslimat yapan yayında bir senaryo varsa `true`; o zaman gelen kutusu yoklanır. |
| `webPush` | `ConfigWebPush` | Evet | Tarayıcı bildirimi için herkese açık VAPID anahtarı ve izin istemi ayarı. |
| `theme` | `map<string, string>` | Evet | Marka teması: `--selwise-*` token değerleri. |
| `locale` | `ConfigLocale` | Evet | Hesabın varsayılan dili ve tüm dilleri; metinler `lang` ile seçilen dilde gelir. |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

```bash
curl "https://api.selwise.com/api/v1/public/sites/SITE_KEY/config?p=4" \
  -H "Origin: https://magaza.com"
```

**Önbellek.** Yanıt kanal başına sunucuda en fazla 5 dakika önbelleğe alınır; bir kampanyanın başlangıç ya da bitiş anı bundan yakınsa süre o ana kadar kısalır. Panelde bir değişiklik yapıldığında önbellek temizlenir. HTTP önbellek başlığı (`Cache-Control`) gönderilmez; kendi katmanınızda önbelleğe alırken kısa tutun.

### Protokol el sıkışması: `?p=`

Bir CDN `client.js`'i saatlerce tutar; yani sahadaki widget sürümleri karışıktır. Her sürüm, çizebildiği özellikleri bir protokol numarasıyla bildirir ve API, istemcinin yanlış çizeceği bir kampanyayı **yanıttan çıkarır**:

| `p` | İstemci neyi çizer |
| --- | --- |
| `1` (varsayılan) | Yer tutucusuz içerik |
| `2` | Sepet yer tutucuları (`cart.total` gibi) |
| `3` | Ürün yer tutucuları (`product.price` gibi) |
| `4` | Ürün koşulları (hedeflemede ürün stoğu gibi kurallar) |

Güncel widget `4` bildirir. Kendi istemcinizi yazıyorsanız anlayamadığınız bir yer tutucunun ham hâliyle ziyaretçiye görünmemesi için bildirdiğiniz sürümü gerçek yeteneğinize eşit tutun: `p=4` gönderip koşul alanlarını yok sayarsanız kampanya olması gerekenden **daha geniş** gösterilir. Aynı parametre senaryo gelen kutusunda ve deney ataması uçlarında da geçerlidir.

## tracking-config

```http
GET /api/v1/public/sites/{siteKey}/tracking-config
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Kararlı sözleşme

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `batchingEnabled` | `boolean` | Evet | Olaylar toplu gönderilsin mi. |
| `batchSize` | `number` | Evet | Bir toplu gönderimdeki en çok olay sayısı. |
| `flushInterval` | `number` | Evet | Kuyruğun boşaltılma aralığı, saniye. |
| `offlinePersistence` | `boolean` | Evet | Gönderilemeyen olaylar tarayıcıda saklanıp sonra yeniden denensin mi. |
| `sendBeaconOnUnload` | `boolean` | Evet | Sayfa kapanırken kalan olaylar `sendBeacon` ile gönderilsin mi. |
| `maxRetries` | `number` | Evet | Başarısız bir gönderimin en çok kaç kez yeniden deneneceği. |
| `maxQueueSize` | `number` | Evet | Bellekteki kuyruğun en çok olay sayısı. |
| `maxStorageEvents` | `number` | Evet | Tarayıcı deposunda tutulacak en çok olay sayısı. |
| `debugMode` | `boolean` | Evet | Widget konsola ayrıntılı günlük yazsın mı. |
| `dataLayerConfig` | `object` | Evet | Veri katmanı ayarları: sayfa türü kalıpları, izleme modülleri, çerez onayı (Ayarlar → Veri Katmanı). |
| `geo` | `GeoHint` | Hayır | Ziyaretçinin ülkesi; istek başına hesaplanır, kenar sunucu ülke göndermediyse yoktur. |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

Yanıt `config` içindeki `tracking` nesnesiyle aynıdır. Kanal başına 10 dakika önbelleğe alınır (`geo` hariç). Widget artık bunu yalnızca `config` başarısız olduğunda ayrıca çağırır.

## integrations

```http
GET /api/v1/public/sites/{siteKey}/integrations
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Widget ve SDK trafiği (istemci protokolüyle evrilir)

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `dataLayer` | `DataLayerSettings` | Evet | Veri katmanı köprüsünün ayarları: açık mı, değişken adı, harici `dataLayer` adı, platform, test modu. Bir hata olursa yalnızca `enabled: false` gelir. |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

Widget'ın veri katmanı köprüsü için okuduğu ayarlardır. Bir hata olursa istek `200` ile yalnızca `enabled: false` döner, hata vermez.

## campaigns ve widgets

```http
GET /api/v1/public/sites/{siteKey}/campaigns
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Kararlı sözleşme

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |
| `lang` | sorgu | `any` | Hayır | Ziyaretçinin ya da sayfanın dili (`tr`, `en-GB`…). Hesabın dillerinden en yakını seçilir; yoksa varsayılan dil. Tek dilli hesapta etkisi yoktur. |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `campaigns` | `PublicCampaign[]` | Evet | Yayın penceresi şu an açık olan kampanyalar (Europe/Istanbul saatiyle). `/config` içindeki listeyle aynıdır. |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

```http
GET /api/v1/public/sites/{siteKey}/widgets
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Widget ve SDK trafiği (istemci protokolüyle evrilir)

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `widgets` | `any[]` | Evet | Her zaman boş: widget'lar Eylül 2026'da kampanyalara birleşti. Eski bir `client.js` çağırdığı için uç duruyor. · en çok 0 öğe |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

`campaigns` yanıtı `{ "campaigns": [ ... ] }` biçimindedir ve `config` içindeki `campaigns` ile aynı öğeleri taşır; pencere ve önbellek kuralları da aynıdır (en fazla 5 dakika). `widgets` her zaman `{ "widgets": [] }` döner. Açılışta bunları ayrı ayrı çağırmak `config`'i bir kez çağırmaya göre fazladan istek demektir.

`type` bilinmeyen bir kayıt yanıttan süzülür; `stylesJson` ve `placementConfigJson` tipe göre sunucuda temizlenir.

## scripts

```http
GET /api/v1/public/sites/{siteKey}/scripts
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Kararlı sözleşme

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |
| `path` | sorgu | `string` | Hayır | Sayfanın yolu; betiklerin yol kuralı buna göre değerlendirilir. Verilmezse `/`. |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `scripts` | `PublicScript[]` | Evet | Yol kuralı `path` ile eşleşen etkin betikler: kod ve isteğe bağlı CSS. |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

**Yol bazında filtrelenir.** Parametresiz çağrı yalnızca ana sayfaya tanımlı script'leri döner, sitenin tamamını değil. Script'ler özel kod modülünün içeriğidir: bkz. [Özel Script'ler](/docs/custom-scripts/overview).

## Ürün sayıları: product-metrics

`product_view_count` ve `cart_count` widget'larının okuduğu sayılardır. Bu widget'ları kullanmıyorsanız kendi rozetinizi yazarken doğrudan çağırabilirsiniz.

```http
GET /api/v1/public/sites/{siteKey}/product-metrics/view-count
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Kararlı sözleşme

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |
| `product` | sorgu | `string` | Evet | Ürünün beslemedeki `item_code` değeri, en çok 200 karakter. |
| `lang` | sorgu | `string` | Hayır | Ziyaretçinin ya da sayfanın dili (`tr`, `en-GB`…). Hesabın dillerinden en yakını seçilir; yoksa varsayılan dil. Tek dilli hesapta etkisi yoktur. |
| `period` | sorgu | `string` | Hayır | Görüntülenme penceresi: `1h`, `24h`, `7d` veya `30d`. Verilmezse `24h`. · 1h \| 24h \| 7d \| 30d |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `count` | `number` | Evet | Tekil ziyaretçi sayısı (aynı kişinin on bakışı bir sayılır). |
| `formatted` | `string` | Evet | Gösterim için kısaltılmış hali (`1,2B` gibi). |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

```http
GET /api/v1/public/sites/{siteKey}/product-metrics/cart-count
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Kararlı sözleşme

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |
| `product` | sorgu | `string` | Evet | Ürünün beslemedeki `item_code` değeri, en çok 200 karakter. |
| `lang` | sorgu | `string` | Hayır | Ziyaretçinin ya da sayfanın dili (`tr`, `en-GB`…). Hesabın dillerinden en yakını seçilir; yoksa varsayılan dil. Tek dilli hesapta etkisi yoktur. |
| `metric` | sorgu | `string` | Hayır | Sepet ölçüsü. Şu an yalnızca `active_carts` (ürünü sepetinde tutan etkin sepet sayısı). · active_carts |

**Yanıt: 200 Başarılı**

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `count` | `number` | Evet | Tekil ziyaretçi sayısı (aynı kişinin on bakışı bir sayılır). |
| `formatted` | `string` | Evet | Gösterim için kısaltılmış hali (`1,2B` gibi). |

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

**Sayılan şey tekil ziyaretçidir, gösterim değil**: aynı kişinin bir ürüne on kez bakması sayıyı bir artırır. `cart-count` son 24 saatte ürünü **sepete ekleyen** tekil ziyaretçileri sayar; sonradan sepetten çıkaranları düşmez, yani "şu an sepette olanlar" değil "son 24 saatte sepete atanlar" demektir.

Tek sayfada birden çok widget için `batch` hepsini tek istekte döndürür (en çok 50 ürün):

```http
POST /api/v1/public/sites/{siteKey}/product-metrics/batch
```

- **Kimlik:** Tarayıcıdan doğrulanmış alan adı (`Origin`), sunucudan ya da uygulamadan `x-selwise-api-key`
- **Katman:** Kararlı sözleşme

**Parametreler**

| Ad | Konum | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- | --- |
| `siteKey` | yol | `string` | Evet | Kanal anahtarı (Kanallar → Kanal Özeti → Kanal Anahtarı). Kanalı adlandırır; sır değildir. |

**İstek gövdesi** (`application/json`)

| Alan | Tip | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `products` | `BatchProductItemDto[]` | Evet | Sorulacak sayılar, en çok 50; her biri kendi `widgetId` anahtarıyla döner. · en çok 50 öğe |
| `products[].itemCode` | `string` | Evet | Ürünün beslemedeki `item_code` değeri. |
| `products[].widgetId` | `string` | Evet | Bu girdi için sizin anahtarınız. Yanıt bu anahtarla döner; aynı ürün için iki sayı (görüntülenme ve sepet) böylece ayrışır. |
| `products[].config` | `BatchProductConfigDto` | Evet | Bu girdinin hangi sayıyı istediği. |
| `products[].config.type` | `string` | Evet | `product_view_count` (görüntülenme) veya `cart_count` (sepet). · product_view_count \| cart_count |
| `products[].config.timePeriod` | `string` | Hayır | Görüntülenme penceresi: `1h`, `24h`, `7d`, `30d`. Verilmezse `24h`. · 1h \| 24h \| 7d \| 30d |
| `products[].config.metricType` | `string` | Hayır | Sepet ölçüsü; şu an yalnızca `active_carts`. · active_carts |

**Yanıt: 201 Başarılı** — Keyed by the `widgetId` each entry was asked under; `{}` when nothing was asked.

**Hatalar:** 400 geçersiz istek, 402 modül sözleşmede yok, 403 kanal doğrulanmamış ya da köken/anahtar yetkisiz, 404 kanal anahtarı bilinmiyor, 429 hız sınırı. Gövde biçimi: [Hatalar ve Limitler](/docs/api-reference/errors-and-limits).

```json
{
  "products": [
    { "itemCode": "SKU-12345", "widgetId": "w-1", "config": { "type": "product_view_count", "timePeriod": "24h" } },
    { "itemCode": "SKU-12345", "widgetId": "w-2", "config": { "type": "cart_count", "metricType": "active_carts" } }
  ]
}
```

Yanıt, her girişin **`widgetId`** değerine göre anahtarlanmış bir nesnedir; `widgetId`'yi siz verirsiniz ve aynı ürün için iki ölçüt isteyen iki giriş iki ayrı cevap alır:

```json
{
  "w-1": { "itemCode": "SKU-12345", "type": "product_view_count", "count": 128, "formatted": "128" },
  "w-2": { "itemCode": "SKU-12345", "type": "cart_count", "count": 12, "formatted": "12" }
}
```

`config.type` zorunludur (`product_view_count` veya `cart_count`); `timePeriod` yalnızca görüntülenme için, `metricType` yalnızca sepet için okunur. Bilinmeyen bir değer `400` döner.

Sonuçlar sunucuda önbelleğe alınır (görüntüleme 2 dakika, sepet 3 dakika, toplu 2 dakika); yani gerçek zamanlı değil, "az gecikmeli" sayılardır.