T-SOFT/Storefront API/Puan Kazanım Önizlemesi

Puan Kazanım Önizlemesi

Bir ürün satın alındığında müşterinin kazanacağı tahmini puanı döner. Ürün detay ekranındaki "bu ürünü alırsan X puan kazanırsın" gösterimi için tasarlanmıştır.

Yetki:storefront:read — herkese açık, token isteğe bağlı. Müşteri token'ıyla sonuç kişiselleşir; anonim istekte taban değer döner.

Dönen points değeri yaklaşık değerdir. Kesin kazanım, sipariş anında sepet koşullu kurallar uygulanarak hesaplanır ve önizlemeden farklı olabilir.

Mağazada puan alışverişi veya ürün detayında puan gösterimi kapalıysa, ya da ürün için hesaplanan puan 0 ise (örneğin ürün puan kazanımından hariç tutulmuş bir kategorideyse) ilgili ürün için kayıt hiç dönmez. İstemci sözleşmesi "kayıt varsa göster"dir; boş data durumunda puan rozeti çizilmemelidir.

Listeleme

filter[productId] zorunludur. Virgülle ayrılmış birden fazla ürün id'si verilebilir; liste ekranları tek istekle çalışır.

GET /loyalty-earning-previews

curl -s 'https://<domain>/api/v3/storefront/2026-01/loyalty-earning-previews?filter[productId]=771,772' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer <TOKEN>'

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "type": "loyalty-earning-previews",
      "id": "771",
      "attributes": {
        "productId": 771,
        "points": 29,
        "pointsValue": 29,
        "basePrice": 582.5,
        "currencyCode": "TRY"
      }
    },
    {
      "type": "loyalty-earning-previews",
      "id": "772",
      "attributes": {
        "productId": 772,
        "points": 8,
        "pointsValue": 8,
        "basePrice": 166.67,
        "currencyCode": "TRY"
      }
    }
  ]
}

Alanlar

Alan	Tip	Kural
`productId`	number	Ürün id'si; kaydın `id` değeri ile aynıdır
`points`	number	Tahmini kazanılacak puan, tamsayı. `0` hesaplanan ürün için kayıt dönmez
`pointsValue`	number	Kazanılacak puanın para karşılığı — "X puan kazanırsınız, değeri Y TL" gösterimi için. Puan sayısının mağazanın puan değeri ayarına bölünmesiyle bulunur
`basePrice`	number	Puan hesabına baz alınan ürün fiyatı. Mağaza ayarına göre KDV dahil veya hariç olabilir
`currencyCode`	string	`basePrice` ve `pointsValue` alanlarının para birimi (ISO 4217)

Filtreler

Filtre	Örnek	Davranış
`filter[productId]`	`filter[productId]=771,772`	Zorunlu. Virgülle ayrılmış bir veya daha fazla ürün id'si. Bulunamayan id'ler sessizce atlanır; filtresiz istek `400` döner

Sıralama

Bu kaynak sıralama parametresi desteklemez; kayıtlar istekteki filter[productId] sırasıyla döner.

`points` semantiği

Hesap, mağazanın puan kazanım oranı ve puan değeri üzerinden ürünün güncel fiyatıyla yapılır. Üye grubuna özel fiyat tanımlıysa ve istek ilgili grup bağlamını taşıyorsa hesap özel fiyat üzerinden yapılır.
Müşteri token'ı ile yapılan isteklerde müşterinin sadakat seviyesine bağlı kazanım çarpanı ve müşteriye özel kazanım kuralları uygulanır. Anonim isteklerde temel hesap döner; aynı ürün için giriş yapmış müşteri farklı (genellikle daha yüksek) bir değer görebilir.
Sepet tutarına veya ödeme yöntemine bağlı kurallar ürün önizlemesinde uygulanamaz; bu nedenle değer tahminidir.

`pointsValue` semantiği

Puanın para karşılığıdır: points değeri mağazanın puan değeri ayarına bölünerek bulunur. Puan değeri 1 ise pointsValue ile points sayısal olarak eşittir.
Para birimi currencyCode ile aynıdır; çoklu para birimi açık bir mağazada istenen para birimine çevrilir.
points tamsayıdır, pointsValue kuruşlu olabilir (iki basamağa yuvarlanır).
"Bu ürünü alırsan X puan (Y TL değerinde) kazanırsın" gösteriminde points ve pointsValue birlikte kullanılır.

Kazanılan puanların hesap dökümü için: Sadakat Hareketleri.