Ürün filtreleri

Yetki: storefront:read — herkese açık, token isteğe bağlı.

Ürün listesinin yanında duran filtre panelini tek istekte verir: hangi kategoriler, markalar, modeller, özellikler ve varyant eksenleri seçilebilir, fiyat aralığı nedir, hangi sıralama seçenekleri gösterilecek. Dönen her seçeneğin yanında o seçim yapıldığında kaç ürün kalacağı da vardır.

Kaynak, ürün listesinin aynasıdır: Ürünler kaynağında geçerli olan filtreler burada da aynı adlarla kabul edilir. Panelde bir seçim yapıldığında aynı filtre kümesiyle bu kaynağı yeniden çağırırsan, kalan seçenekler ve sayılar daralır.

Listeleme

GET /product-facets

curl "https://<domain>/api/v3/storefront/2026-01/product-facets" \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <access_token>"

{
  "jsonapi": { "version": "1.0" },
  "data": [
    {
      "type": "product-facets",
      "id": "current",
      "attributes": {
        "groups": [],
        "attributes": [
          {
            "id": 1,
            "name": "Renk",
            "type": "multi",
            "options": [
              { "id": 101, "name": "Kırmızı", "count": 2 },
              { "id": 102, "name": "Mavi", "count": 2 }
            ],
            "range": null
          },
          {
            "id": 2,
            "name": "Ağırlık",
            "type": "decimal",
            "options": [],
            "range": { "min": 1.25, "max": 2.5, "count": 2 }
          }
        ],
        "categories": [
          { "id": 335, "name": "Kadın", "count": 15 },
          { "id": 340, "name": "Üst Giyim", "count": 15 }
        ],
        "brands": [
          { "id": 80, "name": "T-Soft", "count": 15 }
        ],
        "models": [],
        "priceRange": { "min": 83.33333333, "max": 8332.5, "count": 15 },
        "variantTypes": [
          {
            "id": "variantType1Id",
            "name": "",
            "options": [
              { "id": 24, "name": "Mavi", "count": 3 },
              { "id": 26, "name": "Kırmızı", "count": 3 }
            ]
          }
        ],
        "toggles": [
          { "id": "availableForSale", "type": "boolean" },
          { "id": "isNew", "type": "boolean" },
          { "id": "hasDiscount", "type": "boolean" }
        ],
        "sortOptions": [
          { "id": "name", "label": "Alfabetik A-Z" },
          { "id": "-price", "label": "Fiyat Yüksekten Düşüğe" },
          { "id": "-favoriteCount", "label": "En Çok Favorilenen" }
        ],
        "defaultSort": "position"
      }
    }
  ]
}

Kaynak tek kayıt döner; data yine dizidir ve kaydın id değeri current'tır. Sayfalama parametresi almaz.

Alanlar

Bu alanların hepsi her zaman yanıtta yer alır; kapalı olan bir filtre boş dizi (priceRange için null) döner, alan kaybolmaz.

Panelin mağaza ayarına bağlılığı

Filtre panelinin hangi bölümlerinin görüneceğini mağaza belirler. Kapatılan bölüm boş döner:

Panelde bir bölümü "veri yok" diye gizlemeden önce boş dizinin kapalı ayar anlamına da gelebileceğini hesaba kat — ikisi yanıtta aynı görünür.

attributes semantiği

Ürünün özellik grupları. Grubun tipi seçim biçimini belirler:

• options içindeki her seçenek id, name ve count taşır. count, o seçenek işaretlendiğinde listede kalacak ürün sayısıdır.
• decimal gruplarda options boştur; range alanı min, max ve count verir.
• Hiçbir ürünü kalmayan grup listeye girmez — kullanıcıya sonuçsuz bir filtre gösterilmez.
• Gruplar mağaza ayarındaki sıraya göre döner.

Seçim ürün listesine filter[attr] ile taşınır; sözdizimi Ürünler sayfasındadır.

variantTypes semantiği

Ürünün varyant eksenleri: variantType1Id (genelde renk) ve variantType2Id (genelde beden). id değeri doğrudan ürün listesindeki filtre adıdır — filter[variantType1Id]=24 gibi.

• name, eksenin mağazadaki adıdır; mağaza ad tanımlamadıysa boş string döner. Panelde başlık çizerken boş adı kendi metninle karşıla.
• options içindeki id değerleri varyant seçeneklerinin id'leridir; virgülle çoklu gönderilebilir.

toggles semantiği

Aç/kapa filtreleri. Listeye giren her anahtar, ürün listesinde aynı adla filter[<id>]=1 biçiminde kullanılır:

Mağazanın kapattığı anahtar listeye hiç girmez; panelde o düğmeyi çizme.

sortOptions semantiği

Sıralama listesini istemci sabitlemez — mağazanın açtığı seçenekler ve etiketleri buradan gelir.

• id, ürün listesine olduğu gibi yazılır: GET /products?sort=-favoriteCount.
• label, isteğin dilinde hazır metindir; istemcide çevrilmesi gerekmez.
• defaultSort, kullanıcı bir seçim yapmadan önce işaretli gelecek seçenektir. null dönerse listeyi kendi varsayılanınla aç.

Filtreler

Ürün listesindeki filtrelerin tamamı burada da geçerlidir; panel daraltılırken aynı parametreler gönderilir.

Bir bölümün kendi seçimi o bölümün sayılarına uygulanmaz: renk filtresinde "Kırmızı" seçiliyken renk seçeneklerinin sayıları diğer filtrelere göre hesaplanır, kullanıcı ikinci bir rengi de işaretleyebilsin diye. Diğer bölümlerin sayıları ise seçime göre daralır.

Sıralama

Bu kaynak sort parametresi almaz. Ürün listesinin sıralama seçenekleri sortOptions alanında döner.

İlgili konular

• Ürünler — filtrelerin ve sıralamanın uygulandığı liste
• Kategoriler — kategori ağacı
• Markalar — marka detayı