Öneri Uçları

Öneri uçları, ürün öneri şeritlerinin sözleşmesidir: hangi şeritlerin bir sayfada gösterileceğini ve her şeridin ürünlerini döndürür, gösterim ve tıklamaları da geri alır. Kendi arayüzünüzü (ya da uygulamanızı) yazıyorsanız şeridin içeriğini bu uçlardan alırsınız; tasarımı sizin olur. Panelde şeritleri kurmak için Öneriler bölümüne bakın.

Yöntem ve yol	Kimlik	Ne yapar
GET /public/sites/:siteKey/recommendations	Alan adı ya da mobile_read anahtarı	Bir sayfada gösterilecek şeritler
POST /public/sites/:siteKey/recommendations/:widgetId/products	Alan adı ya da mobile_write anahtarı	Bir şeridin ürünleri
POST /public/sites/:siteKey/recommendations/track/event	Yok	Gösterim, tıklama, sepet, satın alma olayı
POST /public/sites/:siteKey/recommendations/track/behavior	Yok	Ürün davranışı (görüntüleme, sepet, satın alma, favori)

Kimlik kuralları: Kimlik Doğrulama ve Erişim. Birinci ve ikinci uçta sınır IP başına dakikada 100 istektir (uç başına ayrı); iki track ucu hız sınırının dışındadır.

Şeritleri listeleme

curl -G "https://api.selwise.com/api/v1/public/sites/SITE_KEY/recommendations" \
  -H "Origin: https://magaza.com" \
  --data-urlencode "pageUrl=https://magaza.com/urun/elbise-0042"

Parametre	Açıklama
pageUrl	Sayfanın adresi. Şeridin sayfa hedeflemesi buna göre değerlendirilir. Verilmezse hedefleme yalnızca "tüm sayfalar" kuralına göre çalışır ve yanıta page_url_missing kodu eklenir

{
  "widgets": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "name": "Bunlar da ilginizi çekebilir",
      "strategy": "similar_products",
      "displayType": "carousel",
      "maxProducts": 12,
      "isTestMode": false,
      "title": "Bunlar da ilginizi çekebilir",
      "containerSelector": ".product-detail",
      "insertPosition": "after",
      "showOnAllPages": false,
      "includeUrls": ["/urun/*"],
      "excludeUrls": [],
      "pageTypes": ["product"],
      "segmentTargetingMode": "all",
      "segmentIds": [],
      "priority": 10,
      "currency": "TRY",
      "productCard": {},
      "reasonCodes": ["eligible_widgets_found"],
      "eligibilityFlags": { "isActive": true, "pageTargetingConfigured": true, "segmentTargetingRequired": false, "containerSelectorRequired": true, "testModeOnly": false, "liveCartRequired": false }
    }
  ],
  "reasonCodes": ["site_found", "site_verified", "subscription_validated", "eligible_widgets_found"],
  "eligibilityFlags": { "siteFound": true, "siteVerified": true, "subscriptionValidated": true, "pageUrlEvaluated": true, "hasEligibleWidgets": true }
}

Şerit nesnesi, panelde ayarladığınız her şeyi taşır: strateji, görünüm türü (displayType), kaydırıcı ayarları (slidesPerView, autoplay ...), başlık ve stiller, yerleşim (containerSelector, insertPosition), sayfa hedefleme, segment hedefleme, ürün kartı tanımı (productCard) ve sepete ekleme ayarları. Kendi arayüzünüzü yazıyorsanız genelde id, strategy, maxProducts, title, productCard ve eligibilityFlags yeterlidir.

Önemli alanlar:

Alan	Anlamı
reasonCodes	Boş bir liste dönmesinin nedeni: no_widgets_configured, no_eligible_widgets (sayfa hedeflemesi hepsini eledi), page_url_missing, eligible_widgets_found
eligibilityFlags.liveCartRequired	Strateji ölçülmüş sepeti bekliyor (free_shipping_complement). Şeridi yalnızca sepet ölçüldükten sonra çizin ve ürünler ucuna cart gönderin
isTestMode	Yalnızca test modundaki ziyaretçiye gösterilmeli
segmentTargetingMode, segmentIds	Segment hedeflemesi istemcide değerlendirilir; bkz. Widget'ın Kendi Kullandığı Uçlar

Şerit listesi kanal başına 5 dakika önbelleğe alınır ve şerit ekleme, değiştirme, silmede temizlenir. Bir config çağrısının recommendations alanı bu listenin sayfa hedeflemesi uygulanmamış hâlidir; config'i kullanıyorsanız hedeflemeyi istemcide siz değerlendirirsiniz.

Ürünleri alma

curl -X POST "https://api.selwise.com/api/v1/public/sites/SITE_KEY/recommendations/a1b2c3d4-0000-4000-8000-000000000001/products" \
  -H "Content-Type: application/json" \
  -H "x-selwise-api-key: swpk_live_..." \
  -d '{ "currentProductId": "ELB-0042", "visitorId": "VISITOR_ID", "sessionId": "SESSION_ID" }'

Gövde alanı	Açıklama
currentProductId	Şu an bakılan ürünün kodu. Ürün bağlamlı stratejiler (benzer ürünler, birlikte alınanlar, tamamlayıcı) bunu çapa alır; kod sku, item_code ya da sepet kodu olabilir ve katalogda çözülür
visitorId, sessionId	Kişiselleştirilmiş stratejiler için
userId	identify ile verdiğiniz müşteri kimliği, kişiselleştirme için
cart	Yalnızca liveCartRequired şeritlerde: { "known": true, "total": 349.9, "currency": "TRY", "codes": ["ELB-0042"] }. known tam olarak true olmalıdır; sepet ölçülmediyse göndermeyin. Toplam 0 ile 100000000 arası, en çok 100 kod
experimentVariantId	Ziyaretçi bu şeritte bir config_override deney kolundaysa kolun kimliği. Kolun stratejisi ve ürün sayısı kayıtlı varyanttan okunur; çalışan bir kola ait olmayan kimlik hiçbir şeyi değiştirmez

{
  "products": [
    {
      "id": "ELB-0044",
      "_uuid": "c4d5e6f7-1111-4222-8333-444455556666",
      "itemCode": "904240",
      "title": "Kırmızı Mini Elbise",
      "price": 749.9,
      "originalPrice": 999.9,
      "discountRate": 25,
      "currency": "TRY",
      "imageUrl": "https://cdn.magaza.com/elbise-0044.jpg",
      "url": "https://magaza.com/kirmizi-mini-elbise",
      "categories": "Kadın > Elbise",
      "brand": "Ardisa",
      "inStock": true,
      "stock": 9,
      "sku": "ELB-0044",
      "cartCode": null,
      "groupCode": "ELB-0044",
      "hasVariants": false,
      "variants": []
    }
  ],
  "productCard": {},
  "meta": { "strategy": "similar_products", "fallbackUsed": false, "fallbackStrategy": null },
  "liveCartRequired": false
}

Alan	Anlamı
products[]	Şeridin ürünleri, sıralı. id mağazanızın kodu (sku, yoksa itemCode). Sepete ekleme için cartCode doluysa onu, değilse itemCode'u kullanın (Akinon sepeti sayısal pk ister). variants buyable seçenekleri (beden) taşır; renk kardeşleri ve hover görseli kart alanlarıyla gelir
meta.fallbackUsed	Strateji yeterli ürün bulamayıp yedeğe düştüyse true; fallbackStrategy hangisine (new_arrivals, bestsellers, none). reason nedeni söyler
meta içinde complementSetComputedAt, stockCheckedAt	Yalnızca complementary stratejide: hazır setin hesaplandığı an ve stoğun istek anında yeniden doğrulandığı an
productCard	Şeridin ürün kartı tanımı (alan sözleşmesi Ürün Kartları sayfasındadır)
liveCartRequired	Şerit canlı sepeti dinler; sepet her değiştiğinde bu ucu yeniden çağırın

Pasif bir şerit ya da bu kanala ait olmayan bir widgetId hata verir. Dikkat: hata 200 ile döner: { "products": [], "error": "Recommendation widget not found" }. products boş, error dolu ise gövdeyi hata olarak ele alın.

Ürün sonuçları stratejiye göre sunucuda önbelleğe alınır: kişiye bağlı olmayan stratejiler 10 dakika, ziyaretçiye bağlı olanlar 1 dakika. Bu yüzden aynı çapa ürün için ardışık isteklerde sıra aynı kalır.

Olay bildirimi: track/event

Şeridin gösterim, tıklama, sepete ekleme ve satın alma olaylarını bildirir. Kendi arayüzünüzde bunu çağırmazsanız öneri raporları ve atıf boş kalır.

curl -X POST "https://api.selwise.com/api/v1/public/sites/SITE_KEY/recommendations/track/event" \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "a1b2c3d4-0000-4000-8000-000000000001",
    "eventType": "click",
    "productItemCode": "ELB-0044",
    "visitorId": "VISITOR_ID",
    "sessionId": "SESSION_ID",
    "pageUrl": "https://magaza.com/urun/elbise-0042",
    "deviceType": "mobile",
    "eventId": "evt_91ac"
  }'

Alan	Zorunlu	Açıklama
widgetId	Evet	Şeridin kimliği
eventType	Evet	impression, click, add_to_cart ya da purchase
productItemCode	click, add_to_cart, purchase için	Ürünün kodu (beslemedeki). Yoksa 400: productItemCode is required for recommendation click
visitorId, sessionId, journeyId, userId	Hayır	Bağlam. userId müşteri kimliğidir
pageUrl, deviceType, metadata, eventId	Hayır	eventId tekilleştirme içindir

Yanıt { "success": true }. Bilinmeyen site anahtarında { "success": false, "error": "Site not found" }, bir yazım hatasında { "success": false, "error": "Failed to track event" } döner; ikisi de HTTP 200'dür.

Gösterimi ürün kartı başına bir kez, yarısından fazlası görünür olduğunda gönderin; widget de böyle yapar. Aynı şeridin kendi gösterimini ikinci kez saymak gösterim sayısını şişirir.

Davranış bildirimi: track/behavior

Kendi arayüzünüzden ürün davranışını (öneri sinyali olarak) bildirir.

curl -X POST "https://api.selwise.com/api/v1/public/sites/SITE_KEY/recommendations/track/behavior" \
  -H "Content-Type: application/json" \
  -d '{ "behaviorType": "view", "productItemCode": "ELB-0042", "visitorId": "VISITOR_ID", "sessionId": "SESSION_ID", "dwellTime": 18 }'

Alan	Zorunlu	Açıklama
behaviorType	Evet	view, add_to_cart, purchase, wishlist
productItemCode	Evet	Boşsa 400 (productItemCode is required)
productCategory, productPrice, dwellTime, deviceType	Hayır	Bağlam
sessionId, visitorId, siteUserId, pageUrl, referrer, eventId	Hayır	Kimlik ve bağlam

Bu uç user_behaviors kaydı yazar ve ayrıca bir izleme olayı (entityType product, olay adı behaviorType) üretir. Davranışa dayalı stratejiler (recently_viewed, user_history, bestsellers) ve müşteri profilindeki sayaçlar bu kaydı okur. Widget bunu, öneri şeridindeki bir ürün sepete eklendiğinde kendisi çağırır. Ürün görüntülemelerini genel olay akışıyla (events/batch) gönderiyorsanız ayrıca bu uca çağrı yapmanız gerekmez; yalnızca kendi arayüzünüzde öneri şeridi çizip sepete ekleme davranışını da geri bildirmek istiyorsanız kullanın.

Hatalar

Durum	Neden
403	Alan adı ya da anahtar doğrulaması başarısız (mobile_write eksik olabilir)
404	Site anahtarı yanlış
400	Bir track ucunda zorunlu productItemCode eksik
429	Dakikada 100 istek aşıldı (ilk iki uç)

Sırada ne var

• Öneriler — strateji ve şerit türleri
• Ürün Kartları — productCard alanı
• Mobil SDK Önerileri — uygulamada aynısının hazır hâli