Sunucu Taraflı Render API

Sunucu taraflı render endpoint'i, panelde hazırlanmış zenginleştirme içeriğini basmaya hazır HTML olarak döndürür. Kendi uygulama sunucunuzdan çağırırsınız; çıktıyı şablonunuza olduğu gibi yazarsınız.

Kavramsal anlatım ve panel tarafı: Sunucu Taraflı Render.

Neden hazır HTML

Diğer public endpoint'ler ham veri döndürür ve işlemeyi widget yapar: token yerleştirme, HTML temizleme, CSS kapsamlama. Sunucu tarafında bu üç adımı size yaptırmak üç ayrı güvenlik açığı davetiyesi olurdu — şablonda |safe, temizlenmemiş markup, kapsamlanmamış CSS.

Bu yüzden endpoint son hâli döndürür: token'lar yerleşmiş, izin listesine göre temizlenmiş, CSS blok kapsamına alınmış.

Kimlik doğrulama

Diğer public endpoint'ler güvenliği doğrulanmış domain'den alır. Bu endpoint almaz: sunucudan gelen bir isteğin Origin başlığı yoktur, dolayısıyla domain doğrulaması yapılamaz.

Bunun yerine site API anahtarı ister — her istekte, başlığın varlığından bağımsız olarak:

GET /api/v1/public/sites/:siteKey/ssr/enrichments?code=ABC-1&slots=urun-aciklama-alti
x-selwise-api-key: swpk_live_...

Anahtarı Kanallar ekranındaki anahtar simgesinden, Kullanım amacı olarak Sunucu taraflı render seçerek oluşturun.

ssr_read, mobil SDK'nın kullandığı mobile_read ile aynı torbada değildir ve bu bilinçli: SSR anahtarı sizin uygulama sunucunuzda yaşar, dağıtım hattınızdan, CI günlüklerinizden ve imajlarınızdan geçer. Mobil anahtarlar mobile_write ile eşleşerek verilir — sızan bir SSR anahtarının hiçbir şey yazamaması gerekir.

Yanıt	Anlamı
401	Başlık yok. Bir şey sunmadınız
403	Anahtar geçersiz, iptal edilmiş veya ssr_read kapsamı yok
404	siteKey bulunamadı
429	Hız sınırı. Retry-After başlığına bakın

Hız sınırı

Anahtar başına, IP başına değil — varsayılan 6000 istek/dakika.

Sebebi doğrudan sizinle ilgili: diğer public endpoint'leri alışverişçilerin tarayıcıları çağırır, yani bir IP kabaca bir ziyaretçidir. SSR çağrısını sizin sunucularınız yapar; bütün mağaza trafiği birkaç adresten çıkar. IP başına sayılsaydı yoğun bir mağaza paylaşılan public kovayı saniyeler içinde tüketir ve widget'ınızı, event akışınızı ve aramanızı da beraberinde durdururdu.

Yanıt X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını taşır.

İstek

GET /api/v1/public/sites/:siteKey/ssr/enrichments

Parametre	Zorunlu	Açıklama
code	Evet	Ürün kodu. sku, item_code veya sepetin kabul ettiği kod — üçü de katalogda çözülür
slots	Evet	Yuva adları. Virgülle ayrılmış (a,b) veya tekrarlı parametre (slots=a&slots=b). En fazla 10

İki yazım da kabul edilir çünkü ikisi de doğal olarak yazılan biçimdir: Django'nun urlencode çıktısı tekrarlı, elle kurulan bir Next.js URL'i virgüllü olur.

Yanıt

{
  "v": "m3k1p.4",
  "mode": "anonymous",
  "slots": {
    "urun-aciklama-alti": {
      "html": "<div data-selwise-root=\"true\" ...>...</div>",
      "assignmentIds": ["8f3a..."]
    },
    "sepet-ustu": { "html": "", "assignmentIds": [] }
  },
  "css": "[data-selwise-enrichment=\"...\"] .spec-table{...}",
  "meta": {
    "code": "ABC-1",
    "resolved": true,
    "renderedAt": "2026-09-10T09:12:00.000Z"
  }
}

Alan	Ne için
v	İçerik sürüm damgası. Her blokta da nitelik olarak yazılır; widget bununla bayat önbelleği yakalar
mode	Şu an her zaman anonymous: yanıtta kişiye göre değişen hiçbir şey yok, yani sayfa önbelleğine yazılabilir
slots	İstenen her yuva burada bulunur. İçeriği olmayanlar boş dize taşır, anahtar hiç eksilmez
css	Rendere giren blokların kapsamlanmış stilleri, tekilleştirilmiş. Sayfaya bir kez basın
meta.resolved	Kodun katalogda bulunup bulunmadığı. false ise içerik yine gelir, yalnızca ürün token'ları boş kalır

css alanının ayrı olması zorunlu: zenginleştirme izin listesi style etiketini yasaklar, yani markup'ın içine gömülü CSS zaten silinir. Stil blok kapsamına alınmış olduğu için head erişiminiz yoksa içeriğin yanına da basabilirsiniz.

Önbellekleme

Yanıt şu başlıklarla gelir:

Cache-Control: public, max-age=60, stale-while-revalidate=600
ETag: W/"..."
Vary: x-selwise-api-key

ETag'i saklarsanız tekrar render bir gövde yerine 304 maliyetine iner. max-age kasten kısa: bu HTML sizin sayfanızın içine girdiği anda bizim önbelleğimizin ulaşamayacağı bir yere geçer, ve panelde yapılan bir düzenleme oraya yetişemez.

Zaman aşımı ve fail-open

Çağrıyı kısa bir zaman aşımıyla yapın (önerilen 400 ms) ve hatayı yutun. Merchant'ın ürün sayfası bizim yüzümüzden beklememeli.

Bozulma merdiveni şu sırayla iner ve hiçbir basamak diğerini beklemez:

SSR başarılı        → içerik ilk baytta, crawler görür, widget ölçümü devralır
SSR başarısız       → şablon hiçbir şey basmaz → widget normal yoldan basar
widget de yoksa     → sayfa mağazanın kendi hâliyle çıkar, hiçbir şey kırılmaz

Hazır parçalar bunu kendi içinde yapar: Akinon entegrasyon kiti.

Ne dönmez

Kural türü	Neden dışarıda
Test modundaki kurallar	Önbelleğe donan test içeriği herkese gider ve mağazadaki test bayrağı hiç sorulmaz
Segment hedefli kurallar	Kişiye göre değişen bir cevaptır; paylaşılan bir önbellekte bir ziyaretçinin segmenti herkese yapıştırılır
Yuva adı olmayan kurallar	Adresi yoktur. Yalnızca tarayıcıda yaşar
Nerede oluşturulur alanı Yalnızca tarayıcı olan kurallar	Merchant öyle seçmiş

Boyut sınırı

Bir yanıtın markup'ı en fazla 256 KB taşır. Sınıra ulaşıldığında yanıt kural sınırında kesilir: ilk kurallar gelir, sınırı aşan atlanır. Bu HTML sizin sayfanızın içinde her ürün görüntülemesinde taşındığı için sınır bir formalite değil.

Arama ve öneriler

Arama ve öneri endpoint'leri de sunucudan çağrılabilir; ikisi de JSON döndürür ve markup üretmez — liste şablonu sizin tasarımınızdır, bizim basacağımız markup orada yabancı durur. Bkz. Public API.

Öneri şeritlerinin sunucuda HTML olarak oluşturulması ayrı bir çalışmadır ve henüz yayında değil.