Merchandiser API: Sıralı Koleksiyonlar ve Ürün Metrikleri

Genel Bakış

Hazır entegrasyonu olan bir platformdaki mağazaların API'ye ihtiyacı yoktur: Merchandiser ürün sırasını onlar için platforma yazar. API, bunun dışındaki her şey içindir.

Koleksiyon API'si

Koleksiyonlarınıza ve her birinin sıralı ürünlerine okuma erişimi. Özel platformlar ve headless vitrinler içindir. Token gerekmez; istekler hesap UID'nizle tanımlanır.

Ürün Metrikleri API'si

Ürünlerinizin satış metriklerine yazma erişimi. Online ve mağaza satışlarını bir ERP'den veya veri ambarından göndermek içindir. Token gerektirir.

Aşağıdaki tüm adresler temel URL ile başlar. Hesap UID'niz ve her koleksiyonun kopyalanmaya hazır adresi, panelin API Entegrasyonu sayfasında gösterilir.

https://api.merchandiser.com.tr/v1

Koleksiyon API'si

Bir Türdeki Koleksiyonları Listeleme

GET https://api.merchandiser.com.tr/v1/accounts/{account_uid}/collections/{type}

{type} şunlardan biridir: category, brand, list, page, widget veya other. Yanıt, o türdeki aktif koleksiyonları listeler:

{
  "type": "category",
  "total_records": 2,
  "collections": [
    {
      "id": 1042,
      "name": "Women > Jackets",
      "type": "category",
      "code": "women-jackets",
      "path": "/women-jackets",
      "smart": false,
      "sort_type": {"id": 7, "uid": "0b0c…", "name": "Merchandiser AI"},
      "updated": 1760000000.0
    }
  ]
}

code, mağazanızın koleksiyon için kullandığı tanımlayıcıdır. updated, son sıralamanın Unix zaman damgası olarak zamanıdır; bir koleksiyonun yeniden çekilmesi gerekip gerekmediğini anlamak için bunu en son gördüğünüz değerle karşılaştırın.

Bir Koleksiyonun Sıralı Ürünlerini Alma

GET https://api.merchandiser.com.tr/v1/accounts/{account_uid}/collections/{type}/{code}?page=1&size=50

Bir koleksiyona kendi UID'siyle de erişilebilir:

GET https://api.merchandiser.com.tr/v1/collections/{collection_uid}

page

Döndürülecek sayfa; 1'den başlar.

size

Sayfa başına ürün sayısı. Belirtilmezse 50'dir.

expand

true değeri, her ürünü adı, markası, fiyatları, puanı, adresi ve görseliyle birlikte döndürür. Bu parametre olmadan bir ürün, SKU'su ve sırasından ibarettir.

ws_code

true değeri, sku alanında her ürünün SKU'su yerine ERP kodunu döndürür.

color, gender

Yalnızca bu renklerdeki veya cinsiyetlerdeki ürünleri döndürür. Her ikisi de tekrarlanabilir.

sort_by

Bir sıralama türünün UID'si. Koleksiyonu, kayıtlı sırası yerine o sıralama türüne göre sıralanmış olarak döndürür.

{
  "collection": "Women > Jackets",
  "code": "women-jackets",
  "type": "category",
  "id": 1042,
  "page": 1,
  "size": 50,
  "total_pages": 3,
  "total_records": 128,
  "has_next": true,
  "has_prev": false,
  "products": [
    {"sku": "AB-123", "position": 1},
    {"sku": "AB-124", "position": 2}
  ]
}

Ürünler, pinler dâhil, sıralanmış hâlleriyle döndürülür. Yalnızca stokta olan ürünler döndürülür. has_next true olduğu sürece sonraki sayfayı isteyin.

expand=true ile her ürün şu alanları da taşır: name, brand, sale_price, list_price, discount_rate, currency, rating, reviews, url ve image_url.

Sınırlar ve Hatalar

İsteklere IP adresi başına hız sınırı uygulanır. Her yanıt, geçerli zaman aralığında kalan istek sayınızı içeren bir X-Api-Call-Limit başlığı taşır. Sunucularınızın adreslerini bize bildirin; onları sınırdan muaf tutalım.

400

Bir parametre geçerli değil; örneğin sayı olmayan bir page veya size.

404

Hesap veya koleksiyon mevcut değil ya da aktif değil.

429

Çok fazla istek. Daha sonra tekrar deneyin.

Ürün Metrikleri API'si

Bu istek, ürünlerinizin satış metriklerini toplu olarak günceller. Kimlik doğrulaması, talep üzerine hesabınız için verilen bir ürün metrikleri token'ı ile yapılır.

POST https://api.merchandiser.com.tr/v1/products/metrics
Content-Type: application/json
Authorization: Bearer <YOUR-PRODUCT-METRICS-TOKEN>

İstek gövdesi, en fazla 1.000 nesneden oluşan bir listedir. Her nesnede bir sku ve en az bir metrik bulunmalıdır. Metrikler sayı olarak veya sayısal dize (string) olarak gönderilebilir ve negatif olmamalıdır. Göndermediğiniz bir metriğe dokunulmaz. Hesabınızda bulunmayan SKU'lar yanıtta bildirilir ve asla oluşturulmaz.

sku

Güncellenecek ürünün SKU'su. Zorunludur.

daily_purchase, weekly_purchase, monthly_purchase

Son gün, son hafta ve son ayın online satışları.

daily_offline_purchase, weekly_offline_purchase, monthly_offline_purchase

Son gün, son hafta ve son ayın offline (mağaza) satışları.

total_daily_purchase, total_weekly_purchase, total_monthly_purchase

Online ve offline satışların toplamı.

Toplamlar Nasıl Senkron Tutulur?

• Bir online metrik göndermek o metriğin üzerine yazar ve o dönemin toplamını, kayıtlı offline değeri (yoksa 0) kullanarak online artı offline olarak yeniden hesaplar.
• Bir offline metrik göndermek de aynı şekilde çalışır; bu kez kayıtlı online değer kullanılır.
• Bir toplam göndermek o toplamın üzerine yazar. Bir toplamı aynı dönemin online veya offline metriğiyle birlikte gönderirseniz, gönderdiğiniz toplam geçerli olur.

[
  {"sku": "AB-123", "daily_purchase": 4, "daily_offline_purchase": 6},
  {"sku": "AB-124", "weekly_purchase": 18, "monthly_purchase": 63},
  {"sku": "AB-125", "total_weekly_purchase": 42}
]

curl -X POST https://api.merchandiser.com.tr/v1/products/metrics \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR-PRODUCT-METRICS-TOKEN>" \
  -d '[{"sku": "AB-123", "daily_purchase": 4, "daily_offline_purchase": 6}]'

{
  "status": 200,
  "elapsed": 0.14,
  "message": "Given product metrics processed successfully",
  "errors": ["1 SKU(s) were not found for this account: AB-999"],
  "data": {
    "received": 4,
    "updated": 3,
    "skipped": 1,
    "unknown_skus": ["AB-999"]
  }
}

data.received

İstekteki öğe sayısı.

data.updated

Metrikleri güncellenen ürün sayısı.

data.skipped

Uygulanmayan öğe sayısı: geçersiz öğeler ve bilinmeyen SKU'lar.

data.unknown_skus

Hesabınızda bulunmayan SKU'lar (ilk 50).

errors

Atlanan veya kısmen geçersiz olan her öğenin nedeni. Hata içeren bir yanıt yine de 200'dür: geçerli öğeler uygulanır.

Hatalar

400

Token eksik veya gövde bir nesne listesi değil.

403

Hesap askıya alınmış.

404

Token geçerli değil.

413

Tek bir istekte 1.000'den fazla öğe gönderildi.

415

Content-Type başlığı application/json değil.

Satışlar Ne İçin Kullanılır?

Gönderdiğiniz metrikler sıralama sinyallerine dönüşür. Bir kural yalnızca online satışlara göre veya toplamlara göre sıralayabilir; böylece mağazalarınızda iyi satan ürünler web sitenizde de yükselebilir. Merchandiser AI, toplamlar mevcut olduğunda bunlardan öğrenir.