Zenginleştirme Uçları

enrichments, product-facts ve app/enrichments

Ürün zenginleştirmesi üç uçtan dağıtılır. Hangisini kullanacağınız içeriği kimin ve nerede çizeceğine bağlıdır:

Uç	İçeriği kim çizer	Sayfa
`GET /public/sites/:siteKey/enrichments`	Widget, tarayıcıda; ham blok ve token verir	Bu sayfa
`GET /public/sites/:siteKey/product-facts`	Widget, kampanya metnindeki `product.*` yer tutucuları için	Bu sayfa
`GET /public/sites/:siteKey/app/enrichments`	Mobil uygulama; hazır HTML verir	Bu sayfa
`GET /public/sites/:siteKey/ssr/enrichments`	Sizin sunucunuz, sayfayı oluştururken; hazır HTML verir	Sunucu Taraflı Render API

Zenginleştirmenin panelde nasıl kurulduğu için Ürün Zenginleştirme bölümüne bakın. Üç tarayıcı uçta da kimlik, kanalın doğrulanmış alan adıdır (ya da başlıksız istekte mobile_read anahtarı). Kimlik kuralları: Kimlik Doğrulama ve Erişim.

enrichments

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.

curl -G "https://api.selwise.com/api/v1/public/sites/SITE_KEY/enrichments" \
  -H "Origin: https://magaza.com" \
  --data-urlencode "code=SKU-12345"

Parametre	Açıklama
`code`	Ürün kodu. `sku`, `item_code` ya da sepet kodu; büyük/küçük harf duyarsız. En çok 100 karakter
`test`	`1` ya da `true` ise test modundaki kurallar da gelir

{
  "v": "m3k1p.4",
  "items": [
    {
      "assignmentId": "8f3a2b7c-...",
      "selector": ".product-description",
      "insertPosition": "after",
      "order": 0,
      "blocks": [
        { "blockId": "5d1e9c0a-...", "html": "<table>…</table>", "css": ".x{}", "reservedHeightPx": 240 }
      ],
      "segmentTargetingMode": "all",
      "segmentIds": [],
      "isTestMode": false
    }
  ],
  "tokens": { "code": "SKU-12345", "title": "Ürün Adı", "price": 199.9, "currency": "TRY", "inStock": true }
}

Alan	Anlamı
`v`	İçerik sürüm damgası; sitenin herhangi bir zenginleştirme kuralı ya da bloğu değiştiğinde değişir
`items[]`	Render sırasındadır. Bir kural birden fazla blok taşıyabilir; bunlar tek kök altında çizilir ve tek gösterim sayılır
`insertPosition`	`before`, `after`, `inside-start`, `inside-end` ya da `replace`; panelde sırasıyla Before element, After element, Inside element (start), Inside element (end), Replace element (Türkçe arayüzde Öğeden önce, Öğeden sonra, Öğe içinde (başlangıç), Öğe içinde (bitiş), Öğeyi değiştir)
`blocks[].html`, `.css`	Satıcı tarafından yazılmış içerik; `${...}` yer tutucuları henüz doldurulmamıştır
`blocks[].reservedHeightPx`	Blok gelmeden önce ayrılacak yükseklik (px); sayfa kaymasın diye
`tokens`	Yer tutucuları doldurmak içindir. Blok `${attr.renk}` gibi besleme özniteliklerini kullanıyorsa `tokens.attrs` yalnızca kullanılan anahtarları taşır
`segmentTargetingMode`, `segmentIds`	Segment hedeflemesi istemcide değerlendirilir; kişiye bağlı bir karar sunucuda verilmez
`isTestMode`	`true` ise yalnızca test modundaki ziyaretçiye çizilir

Kod bulunamazsa, boş gönderilirse, 100 karakterden uzunsa ya da tekrarlı ?code= verildiyse uç hata değil boş yanıt döner (items: []): widget kodu sayfadan okur ve orada 400 üzerinde işlem yapamayacağı bir gürültüdür. Sitede aktif istemci zenginleştirmesi yoksa yine boş döner.

html ve css satıcı içeriğidir. Widget bunları DOM'a koymadan önce sanitize eder ve CSS'i blok kapsamına alır. Kendi arayüzünüzde kullanıyorsanız bunu sizin yapmanız gerekir; zenginleştirme izin listesi yazılı bir bileşendir ve aynı çıktıyı elde etmenin en güvenli yolu bu ucu değil SSR ucunu (hazır, temizlenmiş HTML) kullanmaktır.

renderMode Yalnızca sunucu olan kurallar bu uca hiç girmez: widget onları çizmeyeceği için gönderilmezler.

Yanıt kanal başına, ürün koduna ve sürüm damgasına göre 5 dakika, içeriği olmayan kodlar için 1 dakika önbelleğe alınır.

product-facts

Kampanya metnindeki product.* yer tutucularının (örneğin "Son 3 ürün") okuduğu katalog bilgisidir. Zenginleştirme kuralı olmadan, aynı ürün aramasıdır.

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

{
  "code": "SKU-12345",
  "known": true,
  "title": "Ürün Adı",
  "price": 199.9,
  "originalPrice": 249.9,
  "stock": 3,
  "currency": "TRY"
}

Katalogda bulunamayan, boş ya da 100 karakterden uzun bir kod için { "code": "...", "known": false } döner. stock, beslemede sayı varsa o sayıdır; ürün stokta değil ve sayı yoksa 0; stokta ve sayı yoksa null (bilinmiyor, sıfır değil). Hız sınırı IP başına dakikada 1000, yanıt 2 dakika önbelleğe alınır (bulunamayan kod 1 dakika).

app/enrichments

Uygulama kanalı için hazır içerik: yer tutucular doldurulmuş, HTML temizlenmiş, CSS kapsamlanmış. Bir uygulamada DOM ve CSS seçici yoktur; içerik yuva adıyla yerleştirilir.

curl -G "https://api.selwise.com/api/v1/public/sites/SITE_KEY/app/enrichments" \
  -H "x-selwise-api-key: swpk_live_..." \
  --data-urlencode "code=SKU-12345" \
  --data-urlencode "slots=pdp-specs,pdp-shipping"

Parametre	Açıklama
`code`	Ürün kodu
`slots`	Yuva adları, virgülle ayrılmış. Küçük harf, rakam ve tek tire; en çok 10
`test`	`1` ya da `true` ise test modundaki kurallar da gelir

{
  "v": "m3k1p.4",
  "code": "SKU-12345",
  "resolved": true,
  "slots": ["pdp-specs", "pdp-shipping"],
  "items": [
    {
      "assignmentId": "8f3a2b7c-...",
      "placementKey": "pdp-specs",
      "order": 0,
      "html": "<div data-selwise-root=\"true\" ...>...</div>",
      "css": "[data-selwise-enrichment=\"5d1e9c0a\"] .spec-table{...}",
      "reservedHeightPx": 240,
      "segmentTargetingMode": "include",
      "segmentIds": ["..."],
      "isTestMode": false
    }
  ]
}

Yanıt kural başınadır; html ve css kuralın tamamı için hazırdır. CSS her öğede ayrı gelir (yanıt boyunca tekilleştirilmez), çünkü her öğe tek başına çizilebilmelidir.
Test modu ve segment kararı istemcidedir. segmentTargetingMode, segmentIds ve isTestMode öğeyle birlikte gelir; SDK uygular. Yanıt ürüne göredir, ziyaretçiye göre değil; bu yüzden herkese aynı önbellekten verilebilir.
renderMode bu uçta sorulmaz: bu sütun "bir web sayfasında kim çizer" sorusunun cevabıdır; uygulamanın tek çizicisi vardır ve tarayıcı botu yoktur.
Bir yanıtın markup'ı (HTML ve CSS) en çok 256 KB taşır; sınıra ulaşınca ilk kurallar gelir, sınırı aşan atlanır.
Kod ya da slots verilmemişse hata değil boş yanıt döner.
Web kanalında bu uç 400 verir: This endpoint serves app channels.... Web kanalı enrichments ya da ssr/enrichments kullanır.

Hazır SelwiseEnrichment bileşeni bunu sizin yerinize çağırır: Mobil Uygulamada Zenginleştirme.

Hatalar

Durum	Neden
`403`	Alan adı ya da anahtar doğrulaması başarısız; kanal doğrulanmamış
`404`	Site anahtarı yanlış
`400`	Yalnızca `app/enrichments`: kanal web kanalı
`429`	Yalnızca `product-facts` ve genel sınır (100/dk) için: hız sınırı

Sırada ne var

Sunucu Taraflı Render API — sayfa HTML'inde doğan içerik
Ürün Zenginleştirme — panelde kural kurma
Ürün Öznitelikleri — ${attr.*} yer tutucuları

Son güncelleme: 10 Ekim 2026