Restomenum Geliştirici
Giriş yapKayıt ol

Kategori Yazma — categories/create · update · delete ✓ Canlı

Kategori kataloğunu yazar. Scope ürünlerle aynıdır (products:write) — kategoriler ürün/menü domain'inin parçasıdır. Sahiplik/idempotency/hata/echo kuralları katalog yazma ile ortaktır.

← API Uçları · Scope: products:write.

categories/create

POST /plugin-api/categories/create
{
  "title": "Tatlılar",               // ZORUNLU (2..100)
  "active": true,                    // ops (default true)
  "color": "#ff8800",                // ops (<=32)
  "languages": { "en": { "title": "Desserts" } },  // ops
  "idempotencyKey": "cat-1"          // ops
}
  • Yeni kategori kök ve hiçbir menüye atanmamış oluşur; menü ataması/hiyerarşi panelden yönetilir (API'de yazılamaz).
  • Yanıttaki id, ürünlerin category alanında kullanılır → önce kategori, sonra ürün (products/create).

categories/update

POST /plugin-api/categories/update
{ "id": "a0-0c", "title": "Tatlılar & İçecekler" }   // {id} + title/active/color/languages'ten en az biri

{ id } + title/active/color/languages'ten en az biri. Sahiplik kontrollü (notOwned).

categories/delete

POST /plugin-api/categories/delete
{ "id": "a0-0c" }
Kategori boş olmalı: bağlı ürün varsa (kim oluşturursa oluştursun) → plugin.catalog.categoryNotEmpty. Önce ürünleri silin/başka kategoriye taşıyın. (Kaskad silme eklentilere kapalı — güvenli ret.)

Yanıt şekli (create/update)

categories/list ile aynı şekil: { id, title, image, color, rank, active, languages }.

Sahiplik modeli (ZORUNLU kural)

  • create ile oluşturduğunuz her kayıt eklentinize damgalanır (sahiplik).
  • update ve delete yalnız KENDİ oluşturduğunuz kayıtlarda çalışır — işletmenin veya başka eklentinin kaydını düzenleyemez/silemezsiniz → plugin.catalog.notOwned. (Slack chat.delete deseni.)
  • İşletme personeli panelden sizin kayıtlarınızı da düzenleyip silebilir (tam yetki). Personel düzenlemesi sahiplik damgasını korur — kayıt "sizin" kalır.
  • Hangi kayıtların size ait olduğunu create yanıtındaki id ile kendi tarafınızda takip edin; okuma uçları sahiplik bilgisi döndürmez.

Idempotency

Tüm create uçları: idempotencyKey (≤128 char, önerilir) → retry'da duplicate yazmaz, ilk başarılı yanıtı aynen döner (24sa pencere; eklenti+tenant+entity başına). Eşzamanlı 2. istek işlenirken → plugin.catalog.duplicateInProgress (kısa bekle, aynı key ile tekrar dene). update/delete doğal idempotenttir (silinmiş kayda tekrar delete → plugin.catalog.notFound).

Hata mesajları

Hatalar HTTP 200 + { success:false, message } (rate limit 429 hariç).

messageAnlam
joi doğrulama mesajıEksik/yanlış tip alan veya tanımsız alan (kütle-atama engeli)
plugin.scope.deniedGerekli yazma scope'u (products:write) onaylı değil
plugin.catalog.notFoundid ile kayıt bulunamadı
plugin.catalog.notOwnedKayıt sizin eklentinizce oluşturulmamış (update/delete reddi)
plugin.catalog.categoryNotEmptySilinmek istenen kategoriye bağlı ürünler var
plugin.catalog.duplicateInProgressAynı idempotencyKey ile eşzamanlı 2. istek
plugin.rateLimitedOrtak write kovası aşıldı (HTTP 429; varsayılan 20/dk — Limitler)

Webhook etkileşimi (echo dahil)

Her başarılı yazma ilgili kanonik event'i tetikler (category.*).

Event abone tüm eklentilere gider — çağrıyı yapan eklenti dahil (echo; Shopify/Stripe davranışı). Kendi yazmanızı ayırt etmek için create yanıtındaki id'yi saklayıp event data.id ile eşleyin. Event data'sı bu uçların yanıt data'sıyla aynı şekildedir.