Menü

Menüyü okuma

GET/api/v1/pos/menuPOS anahtarı

Restoranın güncel menüsünü döndürür.

{
  "data": {
    "menus": [{ "id": "…", "name": "Ana Menü", "is_active": true }],
    "items": [{ "id": "…", "name": "Tavuk dürüm", "price": 180.0, "is_available": true }]
  },
  "meta": { "request_id": "01JB2K9X7Q" }
}

Tam katalog yazma

PUT/api/v1/pos/menuPOS anahtarıscope: menu:write

Gönderdiğiniz katalog menünün tamamını temsil eder: kategoriler ve ürünler eşlenir, gönderilmeyen ürünler yumuşak kapatılır — silinmez, siparişe kapanır. Böylece geçmiş siparişlerin ürün bağlantısı kopmaz.

{
  "source": "firmaniz",
  "categories": [
    {
      "external_id": "KAT-01",
      "name": "Dürümler",
      "items": [
        {
          "external_id": "URN-104",
          "name": "Tavuk dürüm",
          "description": "Lavaş, tavuk, domates",
          "price_kurus": 18000,
          "is_available": true
        }
      ]
    }
  ]
}

Alan	Zorunlu	Kural
source	ilk importta evet	Entegratör adı. Menü POS-yönetimli olmadığı sürece zorunlu; eksikse 422 pos.source_required. POS-yönetimli hâle geldikten sonra boş bırakılabilir (restoranın atanmış entegratörü kullanılır); farklı bir değer gönderirseniz 409 pos.source_mismatch
categories[].external_id	evet	Sizin tarafınızdaki kategori kimliği; eşleme bunun üzerinden kurulur. Gövde genelinde tekil olmalı
items[].external_id	evet	Sizin tarafınızdaki ürün kimliği. Değiştirmeyin — değişirse ürün yeni sayılır ve eskisi kapanır. ⚠️ Tekillik kategori içinde değil, gövde genelinde aranır: iki ayrı kategoride aynı external_id → 422
items[].price_kurus	evet	Dükkan fiyatı, kuruş. 0'dan büyük, en çok 10.000.000 (100.000 ₺); dışında 422 pos.menu_invalid
items[].is_available	hayır	Boş bırakılırsa true

Gövde sınırları

Sınır	Değer	Aşılırsa
Kategori sayısı	en çok 30	422 pos.menu_invalid
Ürün sayısı	toplam en çok 300	422 pos.menu_invalid
Kategori ve ürün adı	en çok 200 karakter	422 pos.menu_invalid
Boş kategori listesi ya da hiç ürün	kabul edilmez	422 pos.menu_invalid

300 ürün sınırı tek PUT ile senkronu bitirir

Toplu senkron tek istekte yapılır ve 300 üründen fazlası reddedilir. Parçalayarak göndermek de işe yaramaz: her PUT menünün tamamını temsil eder ve gövdede olmayan ürünler kapatılır.

Menüsü 300 ürünü aşan bir restoranla çalışıyorsanız bize yazın.

Fiyatı olmayan ürünü 0 ile göndermeyin

0 reddedilir. Satışta olmayan bir ürünü is_available: false ile kapatın, fiyatını 0 yapmayın.

price_kurus dükkan fiyatıdır, müşterinin gördüğü fiyat değil

Girdiğiniz tutar restoranın eline geçecek olan tutardır. Müşteriye gösterilen satış fiyatı bunun üzerine platform bedeli eklenerek Veni tarafında hesaplanır.

Müşteriye gösterilecek fiyatı buraya yazarsanız restoran kendi payından kaybeder. Adisyondaki satış fiyatını değil, restoranın kazanmak istediği tutarı gönderin.

Yanıt iki moddan birini söyler:

{
  "data": {
    "mode": "draft",
    "source": "firmaniz",
    "import_id": "imp_441",
    "categories_upserted": 12,
    "items_upserted": 218,
    "items_soft_closed": 0
  },
  "meta": { "request_id": "01JB2K9X7Q" }
}

mode	Anlamı
draft	İlk içe aktarma. Menü taslak olarak durur ve restoranın panelden onayını bekler. import_id o taslağın kimliğidir
applied	Canlıya doğrudan uygulandı

⚠️ items_soft_closed yalnız applied modunda dolar: taslak yolunda hiçbir ürün kapatılmaz ve alan 0 döner. Taslak yanıtında bu sayıya bakıp "şu kadar ürün kapandı" sonucu çıkarmayın.

Tek ürünü güncelleme

POST/api/v1/pos/menu/items/{externalID}/availabilityPOS anahtarıscope: menu:write

Gün içinde tükenen bir ürünü kapatmak ya da fiyatını değiştirmek için tam katalog göndermeniz gerekmez.

{
  "is_available": false,
  "out_of_stock_until": "2026-10-12T21:00:00Z"
}

Alan	Davranış
is_available	false → siparişe kapanır. true → açılır ve varsa zaman kilidini temizler
stock_quantity	Adet stok (isteğe bağlı)
out_of_stock_until	RFC3339 → o ana kadar kapalı. "" → kilidi temizler. Alan hiç gönderilmezse dokunulmaz
price_kurus	Dükkan fiyatı, kuruş. Yukarıdaki uyarı burada da geçerli

Gönderilmeyen alan değiştirilmez; her istekte tüm alanları yollamak zorunda değilsiniz.

{
  "data": { "item_id": "…", "external_id": "URN-104", "is_available": false },
  "meta": { "request_id": "01JB2K9X7Q" }
}

⚠️ Bu uç menü POS-yönetimli olmadan çalışmaz: taslak onaylanana kadar 409 pos.menu_not_pos_managed döner.

Yetki

Bu sayfadaki iki yazma ucu menu:write ister, yani pos_push rolündeki bir anahtar. read_mirror anahtarıyla çağırırsanız 403 alırsınız; okuma uçları ikisiyle de çalışır.