Menü ve Ürün Eşleme

Menüyü çekin, ürünlerinizi kimlikle eşleyin, fiyat ve satılabilirliği güncelleyin.

Bu sayfadaki uçlar yalnız restoran işletmelerinde vardır; Çarşı anahtarıyla çağrılırsa 404 not_available_for_vertical döner. Siparişi kendi sisteminize düşürebilmek için platformdaki ürünün sizin tarafınızdaki karşılığını bilmeniz gerekir. GET /menu menüyü kimliklerle verir; sipariş kalemleri de aynı kimliği taşır. Eşlemeyi bir kez kurarsınız, sonra her sipariş kendiliğinden çözülür.

Ada göre eşleme yapmayın. İşletme ürünü yeniden adlandırdığı anda eşleme kopar ve siparişler sessizce düşmeye başlar. Her zaman id kullanın.

Bu sayfadaki uçlar

Her satır API referansındaki tam tanıma gider — alanlar, yanıt kodları ve deneme konsolu orada.

Menüyü çekin

GET /menu yanıtı (kısaltılmış)

{
  "merchantId": "cm_ornek_isletme",
  "itemCount": 59,
  "generatedAt": "2026-01-31T10:00:00.000Z",
  "categories": [
    { "id": "cm_ornek_kategori", "name": "Ana Yemekler", "sortOrder": 1, "active": true,
      "items": [
        { "id": "cm_ornek_urun",   // sipariş kalemleri BU kimliği taşır
          "name": "Örnek Ürün", "description": null, "price": 260, "originalPrice": null,
          "calories": null, "image": null, "available": true, "popular": false,
          "prepMinutes": 15, "sortOrder": 1, "approvalStatus": "approved",
          "modifierGroups": [
            { "name": "Boy Seçimi", "minSelect": 1, "maxSelect": 1, "singleChoice": true,
              "choices": [ { "id": "cm_ornek_secenek_1", "name": "Küçük", "price": 0 },
                           { "id": "cm_ornek_secenek_2", "name": "Büyük", "price": 20 } ] }
          ],
          "updatedAt": "2026-01-31T09:00:00.000Z" }
      ] }
  ]
}

Alanların anlamı

Alan	Tip	Açıklama
`id`	string	Platformdaki ürün kimliği. Eşlemenin anahtarı: sipariş kalemlerindeki `items[].id` ile aynıdır. Eşleme yalnız bu kimlikle yapılır.
`available`	boolean	`false` ise müşteri sipariş veremez.
`approvalStatus`	enum	Müşteri yalnız `approved` ürünleri görür. `pending`/`rejected` ürünler, eşlemenizi önden kurabilmeniz için listelenir; onlardan sipariş gelmez.
`active`	boolean	Kategori düzeyinde: pasif kategorinin ürünleri müşteriye gösterilmez.
`price`	number	Güncel satış fiyatı; ₺ ve KDV dahildir. `choices[].price` kalem fiyatına eklenen tutardır.
`choices[].id`	string	Seçenek kimliği; sipariş kaleminde `selectedOptions[].choiceId` olarak gelir.

Gereksiz veri çekmeyin: ETag

Menüler nadiren değişir ama sık yoklanır. Yanıttaki ETag başlığını saklayın ve bir sonraki istekte If-None-Match ile gönderin. Menü değişmediyse gövdesiz 304 Not Modified alırsınız. 304 yanıtı da hız sınırından bir istek hakkı düşer; yoklama aralığını menünün nadiren değiştiğini bilerek seçin. If-None-Match birden çok değer, W/ öneki ve * kabul eder.

cURL

# 1) İlk çekim — ETag'i saklayın
curl -D- "https://api.supergelsin.com/api/partner/v1/menu" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01"
# < ETag: "sA5f-91rsUIX3qA5UxNoxqL7XGzJCIjj"

# 2) Sonraki yoklamalar — değişmediyse 304, gövde yok
curl -D- "https://api.supergelsin.com/api/partner/v1/menu" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H 'If-None-Match: "sA5f-91rsUIX3qA5UxNoxqL7XGzJCIjj"'
# < HTTP/1.1 304 Not Modified

Menüyü güncelleme

Bu API ile fiyat ve satılabilirlik güncellenir. Yeni ürün oluşturma, ad/görsel/açıklama değiştirme bu yüzeyde yoktur — menü içeriği partner panelinde yönetilir. Üç uç da toplu çalışır (istek başına en çok 100 kalem; aşımda 400 too_many_items) ve sonucu kalem kalem döndürür; bir kalemin başarısızlığı diğerlerini etkilemez.

Satışa aç / kapat

curl -X PUT "https://api.supergelsin.com/api/partner/v1/menu/items/status" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "id": "cm_ornek_urun", "available": false }] }'

# { "total": 1, "applied": 1, "pendingReview": 0, "failed": 0,
#   "results": [{ "id": "cm_ornek_urun", "status": "applied" }] }

Satış durumu değişimi anında uygulanır. Tükenen ürünü kapatmak, sipariş gelip iptal edilmesini önler; en sık kullanacağınız yazma ucudur. Yasaklı ürün şüphesi taşıyan ürün pending_review döner ve onaylanana kadar satışta görünmez.

Fiyat

curl -X PUT "https://api.supergelsin.com/api/partner/v1/menu/items/price" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "id": "cm_ornek_urun", "price": 139.50 }] }'

# İndirim: anında uygulanır
# { "applied": 1, "pendingReview": 0 }

# Eşik üstü zam: incelemede, canlı fiyat değişmez
# { "applied": 0, "pendingReview": 1, "results": [{ "status": "pending_review" }] }

Menü yazımları senkrondur: yanıt geldiğinde iş bitmiştir, kalem başına sonuç results içindedir ve sorgulanacak bir toplu iş kimliği yoktur. Tek istekte en fazla 100 kalem gönderilir; daha büyük listeleri bölün. Kalem sayısı tavanı şema denetiminden sonra uygulanır: tavanı aşan ve geçersiz kalem de içeren istek too_many_items yerine invalid_body alır. Çarşı'daki katalog yazımları ise bin kaleme kadar taşıyabildiği için 202 ve batchId ile asenkron çalışır; iki dikeyi aynı istemci koduyla sürüyorsanız bu farkı göz önünde bulundurun.

İndirim ve küçük artış anında uygulanır. Eşik üstü zam incelemeye düşer ve pending_review döner — bu durumda canlı fiyat değişmez. Aynı kural partner panelinde de geçerlidir; API onu baypas etmez.

originalPrice (üstü çizili, indirim öncesi fiyat) yazılamaz. Platform onu kendi fiyat geçmişinden hesaplar. Alanı gönderirseniz istek reddedilmez; değer yok sayılır. Fiyat zaten istenen değerdeyse yazım yapılmaz ve kalem applied döner; menünün ETag değeri değişmez. Aynı id bir istekte iki kez gönderilemez.

Kategori satışa aç / kapat

curl -X PUT "https://api.supergelsin.com/api/partner/v1/menu/categories/status" \
  -H "Authorization: Basic $(printf '%s:%s' "$API_KEY" "$API_SECRET" | base64)" \
  -H "X-Integrator: Ornek POS" \
  -H "X-Operator: kasiyer_01" \
  -H "Content-Type: application/json" \
  -d '{ "categories": [{ "id": "cm_ornek_kategori", "active": false }] }'

Kalem sonuçlarını mutlaka kontrol edin

HTTP 200 "hepsi başarılı" demek değildir. Her kalemin kendi status alanı vardır:

Alan	Tip	Açıklama
`applied`	status	Uygulandı, canlıda.
`pending_review`	status	Kabul edildi ama incelemede; canlı sürüm korunuyor. Kendi tarafınızda "beklemede" gösterin.
`not_found`	status	Bu işletmede böyle bir kayıt yok — kimliği ve menüyü tazeleyin.
`invalid`	status	Değer geçersiz (ör. fiyat ≤ 0); `message` sebebi söyler.

Önerilen eşleme akışı

Menüyü çekin, id → sizin ürün kimliğiniz tablosunu kurun.
Yeni sipariş geldiğinde items[].id ile bu tablodan çözün.
Eşleşmeyen bir kimlik görürseniz menüyü tazeleyin (yeni ürün eklenmiş olabilir); yine eşleşmezse siparişi kayıtsız bırakmak yerine operasyon ekibinize bildirin.
Menüyü periyodik olarak (ör. 15 dakikada bir) If-None-Match ile yoklayın; 304 yanıtı gövde taşımaz, yine de hız sınırından bir istek hakkı düşer.

Çarşı'da menü yerine katalog vardır ve ürünü siz oluşturabilirsiniz — bkz. Çarşı — Katalog. Orada eşleme anahtarı clientReferenceId değeridir.