Arama Uçları

Arama, öneri, tıklama ve sıfır sonuç bildirimi

Arama uçları, site içi arama widget'ının kullandığı sözleşmedir. Kendi arama kutunuzu ya da uygulamanızı yazıyorsanız sonuçları search ucundan alır, tıklama ve sıfır sonuç bilgisini analitik uçlarına bildirirsiniz. Panelde aramanın nasıl yapılandırıldığı için Arama bölümüne bakın.

Arama uçlarının hepsi Search & Merchandising (search) modülünü ister: hesapta bu modül yoksa uç 402 ve MODULE_NOT_ENTITLED koduyla döner.

Yöntem ve yol	Kimlik	Ne yapar
`GET /public/sites/:siteKey/search`	Alan adı ya da anahtar	Ürün arar
`GET /public/sites/:siteKey/search-config`	Alan adı ya da anahtar	Arama widget'ının yapılandırması
`GET /public/sites/:siteKey/search/suggestions`	Alan adı ya da anahtar	Popüler arama, kategori ve ürün listeleri
`POST /public/sites/:siteKey/search/log`	Yok	Arama sorgusunu kaydeder
`POST /public/sites/:siteKey/search/click`	Yok	Sonuçtaki ürün tıklamasını kaydeder
`POST /public/sites/:siteKey/search/zero-results`	Yok	Sıfır sonuç olayını kaydeder

Kimlik kuralları: Kimlik Doğrulama ve Erişim. Üç GET ucunda sınır IP başına dakikada 100 istektir ve uç başına ayrı sayılır; sunucudan arama yapıyorsanız aynı sorguyu kendi önbelleğinizde tutun. Üç POST ucu hız sınırının dışındadır.

search

curl -G "https://api.selwise.com/api/v1/public/sites/SITE_KEY/search" \
  -H "Origin: https://magaza.com" \
  --data-urlencode "q=kırmızı elbise" \
  --data-urlencode "limit=24" \
  --data-urlencode "inStock=true" \
  --data-urlencode "maxPrice=1500"

Parametre	Açıklama
`q`	Arama terimi. En çok 200 karakter; uzunsa hata gövdesiyle döner (aşağıda). Boş olabilir, ama o zaman en az bir süzgeç gerekir
`limit`	Sonuç sayısı. En çok 100. Verilmezse panelde ayarlı Maksimum sonuç değeri, o da yoksa 10. Geçersiz ya da 1'den küçükse 20
`category`	Kategori adına göre süzer (içerir eşleşmesi, büyük/küçük harf duyarsız)
`minPrice`, `maxPrice`	Fiyat aralığı. Negatifler 0'a çekilir, üst sınır 99999999. `minPrice` `maxPrice`'tan büyükse ikisi yer değiştirir
`inStock`	`true` yalnızca stokta olanları, `false` yalnızca stokta olmayanları getirir

Terimsiz arama. q boşken category, minPrice, maxPrice ya da inStock'tan biri varsa istek bir kategori gezintisi olarak yanıtlanır. Hiçbir süzgeç de yoksa Query parameter required hatası döner (tüm kataloğu listelemek bir listeleme sayfasının işidir).

{
  "hits": [
    {
      "id": "ELB-0042",
      "_uuid": "b3f1c2a4-1d3e-4a5b-8c7d-9e0f1a2b3c4d",
      "itemCode": "904236",
      "sku": "ELB-0042",
      "title": "Kırmızı Midi Elbise",
      "price": 899.9,
      "originalPrice": 1199.9,
      "discountRate": 25,
      "currency": "TRY",
      "imageUrl": "https://cdn.magaza.com/elbise-0042.jpg",
      "url": "https://magaza.com/kirmizi-midi-elbise",
      "categories": "Kadın > Elbise",
      "brand": "Ardisa",
      "inStock": true,
      "stock": 14,
      "hasVariants": false,
      "cartCode": null,
      "groupCode": "ELB-0042",
      "score": 7.4
    }
  ],
  "total": 42,
  "took": 12,
  "enabled": true,
  "categories": [ { "name": "Kadın > Elbise", "count": 31 } ],
  "strategy": "standard",
  "debugMeta": { "queryLength": 14, "appliedFilters": { "limit": 24, "inStock": true, "maxPrice": 1500 } },
  "traceId": "5d0c2b6e-0e0b-4a5e-8b9c-2f0a3b2c1d9e"
}

Alan	Anlamı
`hits[]`	Ürünler. `id` mağazanızın kodudur (`sku`, yoksa `item_code`); `_uuid` Selwise'in dahili kimliği, izleme birleştirmeleri içindir. `cartCode` sepetin kabul ettiği kod `itemCode`'dan farklıysa dolu gelir (Akinon: sayısal ürün `pk`'si). `groupCode` kardeş ürünleri gruplar; kimlik değildir. Renk kardeşleri ve beden seçenekleri varsa `variants` ve benzer kart alanları da eklenir
`total`	Süzgeçlere uyan toplam ürün sayısı
`took`	Sunucu süresi, milisaniye
`enabled`	Arama bu kanalda kapalıysa `false`; o zaman `hits` boştur
`categories`	Sonuçların kategori dağılımı: `name` ve `count`
`redirect`	Sorgu bir yönlendirme kuralına eşleştiyse hedef adres. `hits` boştur; istemci kullanıcıyı oraya götürür
`suggestions`	Sonuç sıfırsa "bunu mu demek istediniz" alternatifleri (en çok 5)
`expandedQuery`	Eş anlamlı ve Türkçe çekim genişletmesi uygulandıysa aranan terimler
`strategy`	`standard`, `expanded_query`, `redirect`, `disabled`, `service_unavailable`, `validation_error`, `error`
`error`	Bir sorun varsa nedeni. HTTP durumu yine `200` olabilir; `strategy` ile birlikte okuyun
`traceId`	Bir şikayeti sunucu günlüğüyle eşleştirmek için
`debugMeta`	Tanılama için: uygulanan süzgeçler ve sınırlamalar. Arayüzünüzde kullanmayın

strategy: "validation_error" ve error: "Query too long" ya da "Query parameter required" HTTP 200 ile döner; arama geçersiz isteklerde bile 4xx vermez. Arama motoru geçici olarak çalışmıyorsa strategy: "service_unavailable" ve error: "Search service temporarily unavailable" gelir.

Arama kanalın kendi yapılandırmasıyla (eş anlamlılar, yönlendirmeler, sıralama kuralları) çalışır, ürünleri ise kanal başka bir kanalın kataloğunu okuyorsa paylaşılan katalogdan alır. Türkçe çekim ekleri ve eş anlamlılar sorguyu otomatik genişletir. Sıfır sonuçlu sorgular Sıfır Sonuç ekranına düşer; bunu sizin ayrıca bildirmeniz gerekmez.

search-config

GET /api/v1/public/sites/:siteKey/search-config

Widget'ın kendi arayüzünü çizmek için okuduğu yapılandırmadır: enabled, isTestMode, yerleşim (position, selector, triggerSelector, floatingPosition), metinler (placeholder, hotkey), davranış (minChars, debounceMs, maxResults, searchOnFocus, keepOpen, mobileFullscreen), sonuç gösterimi, stiller, önerilen aramalar, sepet entegrasyonu, segment hedefleme, ürün kartı ve marka teması. Kanal başına 10 dakika önbelleğe alınır. Kendi arayüzünüzü yazıyorsanız genellikle yalnızca enabled, minChars, debounceMs ve maxResults işinize yarar.

search/suggestions

GET /api/v1/public/sites/:siteKey/search/suggestions

Parametre almaz: kutu odaklandığında, yazmaya başlamadan önce gösterilen listeler. Yazarken önerilen terimler için search ucunun suggestions alanı kullanılır.

{
  "recentSearches": { "enabled": true, "maxCount": 5 },
  "popularSearches": { "enabled": true, "items": ["elbise", "ceket"] },
  "popularCategories": { "enabled": true, "items": [ { "name": "Kadın", "imageUrl": null } ] },
  "popularProducts": { "enabled": false, "items": [] },
  "styles": {}
}

recentSearches yalnızca bir ayardır; kişinin son aramaları tarayıcıda tutulur, sunucuda değil. Liste kaynakları (elle, dinamik ya da ikisi birden) panelde ayarlanır. Bir hata olursa istek 200 ve { "error": "Failed to get suggestions" } döner.

Analitik uçları

Üç uç da yalnızca site anahtarı ister ve kaydı kendi başına yazar; bir sonuç döndürmezler. Kendi arama arayüzünüz bunları çağırmazsa arama ekranları ve atıf eksik veriyle çalışır.

search/log

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/search/log \
  -H "Content-Type: application/json" \
  -d '{ "query": "kırmızı elbise", "resultsCount": 42, "sessionId": "SESSION_ID", "visitorId": "VISITOR_ID", "pageUrl": "https://magaza.com/arama" }'

Alan	Zorunlu	Açıklama
`query`	Evet	Aranan terim
`resultsCount`	Hayır	Gösterilen sonuç sayısı
`sessionId`, `visitorId`, `siteUserId`, `pageUrl`, `referrer`, `eventId`	Hayır	Bağlam. `eventId` tekilleştirme içindir

Bir search_query olayı yazar ve ilgili senaryo girişlerini değerlendirir. Yanıt 200 ve gövde, kanal bilinmiyor ya da doğrulanmamışsa { "success": false } olur.

search/click

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/search/click \
  -H "Content-Type: application/json" \
  -d '{ "productItemCode": "ELB-0042", "query": "kırmızı elbise", "category": "Kadın > Elbise", "sessionId": "SESSION_ID", "visitorId": "VISITOR_ID" }'

productItemCode zorunludur (boşsa 400, productItemCode is required); diğer alanlar query, category, sessionId, visitorId, siteUserId, pageUrl, referrer, eventId. Bir product_click olayı yazar; arama analitiği ve atfı bu tıklamayı kullanır. Yanıt { "success": true }.

search/zero-results

curl -X POST https://api.selwise.com/api/v1/public/sites/SITE_KEY/search/zero-results \
  -H "Content-Type: application/json" \
  -d '{ "query": "pembe palto", "sessionId": "SESSION_ID", "visitorId": "VISITOR_ID" }'

Bir search_zero_results olayı yazar. Sıfır sonuç tablosuna satır eklemez: search ucu sonuç sıfır olduğunda o satırı zaten kendisi yazar; ikinci bir yazım her sayıyı iki katına çıkarırdı. Bu uç yalnızca olayı (oturum, ziyaretçi ve sayfa bilgisiyle) kaydeder. Yanıt { "success": true }.

Hatalar

Durum	Neden
`402`	Kod `MODULE_NOT_ENTITLED`: hesapta arama modülü yok
`403`	Alan adı ya da anahtar doğrulaması başarısız; kanal doğrulanmamış
`404`	Site anahtarı yanlış
`400`	Yalnızca `search/click`: `productItemCode is required`
`429`	Dakikada 100 istek aşıldı (`GET` uçları)

Sırada ne var

Arama — panelde arama
Öneri API'si
Sıfır Sonuç — kaydedilen sıfır sonuçlu sorgular

Son güncelleme: 10 Ekim 2026