API Uçları — Genel Bakış

Eklentinin Restomenum'dan veri okuduğu / işlem yaptığı HTTP uçları. Etkileşimler (event, action, iframe) yalnızca bir id taşır; dolu veriyi bu API'lerden çekersiniz. Liste zamanla genişler.

Ortak kurallar

GET {RESTOMENUM_BASE}/plugin-api/<kaynak>/<aksiyon>
Authorization: Bearer <apiKey>     // kurulumdaki (OAuth exchange) install API key

{RESTOMENUM_BASE} ortama göre değişir — geliştirmede sandbox, canlıda production:

Ortam	Base URL
Dev / Sandbox	https://sandbox.plugins.restomenum.app
Production	https://plugins.restomenum.app

Base: tüm uçlar {RESTOMENUM_BASE}/plugin-api/… altında (yukarıdaki tablo).
Auth: Authorization: Bearer <apiKey> — token exchange'te alınan install API key. apiKey üç parçalıdır: serverId.pluginId.secret (secret = 32-byte hex). Sunucu, secret'ı saklı apiKeyHash ile SHA-256 timing-safe karşılaştırır. Kurulum aktif değilse (enabled + connected + billing) çağrı 401 alır.
Scope: her uç kendi scope'unu ister; eksikse plugin.scope.denied.
PII: customer alanları customers:read + consent ile dolu gelir; yoksa webhook ile aynı kuralla kırpılır.

Yanıt zarfı

// başarı
{ "success": true, "data": { … } }

// hata
{ "success": false, "message": "<kod>" }

Yanıt REST-uyumlu HTTP status taşır: başarı 200; hata not-found 404, doğrulama 400, scope/sahiplik 403, çakışma 409, rate limit 429, auth 401. Gövde her durumda { success, message } (message = makine-okur kod). Tam liste: Hata Kodları.

Uçlar

Method	Uç	Açıklama	Scope
GET	/plugin-api/packets/get	Paket detayı (dolu order: ürünler, müşteri, adres, toplam)	orders:read
GET	/plugin-api/packets/open	Açık paket/delivery hesapları (özet): packetId, kanal, tutar, ürün adedi. Detay: packets/get?packetId=.	orders:read
POST	/plugin-api/packets/create	Yeni paket/sipariş oluştur (yazma ucu). Sepet ürün id'leriyle; fiyat Restomenum kaydından. idempotencyKey ile retry-güvenli. Ayrı write limit (20/dk).	orders:write
POST	/plugin-api/packets/update	Paketin sınırlı alanlarını güncelle (allowlist: status[label]/note/paymentNote/customer.address\|phone). Kapanış/iptal tetiklemez.	orders:write
POST	/plugin-api/packets/update-orders	Paket kalemlerini (cart) DEĞİŞTİR (full replace). total ürün kaydından yeniden hesaplanır. paid > yeni total → reddedilir (success:false).	orders:write
POST	/plugin-api/packets/update-payments	Paket ödemelerini DEĞİŞTİR (full replace). paid yeniden hesaplanır (price>0). paid > total → reddedilir (success:false). update-orders ile eş zamanlı çağırma.	orders:write
GET	/plugin-api/tables/get	Masa detayı (dolu order). orders[] packets/get ile aynı satır şekli; kimlik masaya özel (tableId/tableName/desing — packetId değil). table.close gate target.id ile çekilir.	orders:read
GET	/plugin-api/tables/layout	Masa yerleşimi (floor plan): bölümler + masa adları. Ücret/grid alanları dönmez. Masa = bölüm+ad.	orders:read
GET	/plugin-api/tables/open	Açık masa hesapları (özet): tableId, tutar (total/paid/indirim), ürün adedi. Detay: tables/get?id=.	orders:read
POST	/plugin-api/tables/create	Dine-in masa AÇ (QR self-order / kiosk) — yayına hazırlanıyor (yakında). tableId layout'tan gelmeli (uydurulamaz); açık masada 409; kuver otomatik; cart boş olabilir. table.created tetikler. Kapatma/silme yetkisi yok.	orders:write
POST	/plugin-api/tables/update-orders	Masa kalemlerini DEĞİŞTİR (full replace). total kuver dahil yeniden hesap; timer ürün desteklenmez.	orders:write
POST	/plugin-api/tables/update-payments	Masa ödemelerini DEĞİŞTİR (full replace). Ödeme doğrulaması packets ile birebir (unknown_payment_method).	orders:write
GET	/plugin-api/products/get	Ürün detayı (id ile). fiyat, KDV, görsel, barkod, stok, seçenek/choice ağacı. cost/recete dönmez.	products:read
GET	/plugin-api/products/list	Tüm ürün kataloğu (aktif+pasif). Max 2000 (aşılırsa truncated+total). cost/recete dönmez.	products:read
GET	/plugin-api/categories/list	Tüm ürün kategorileri (aktif+pasif). id, title, image, color, rank. Ürün category ile eşleşir. Max 500.	products:read
GET	/plugin-api/categories/get?id=	Tek kategori detayı (id ile). Şekil categories/list öğesiyle aynı. category.* event id'sini zenginleştir.	products:read
GET	/plugin-api/payment-methods/list	Tanımlı ödeme yöntemleri (Nakit/Kredi Kartı…): id, title, description, cash, noreport. users dönmez.	payment_methods:read
GET	/plugin-api/ingredients/list	Malzeme/stok kataloğu (envanter): id, title, unit, stock, alert, tax. ort(maliyet)/stocks/storages dönmez.	ingredients:read
GET	/plugin-api/customers/list	Müşteri kataloğu (CRM/sadakat) — cursor pagination (after/nextCursor, max 500). name/phone/address (PII) + total (finansal) yalnız consent ile; yoksa {id,region}.	customers:read
GET	/plugin-api/customers/get?customerId=	Müşteri detayı (id ile). {id,region} + name/phone/address (PII) + total (finansal) yalnız consent ile. Şekil customers/list öğesiyle aynı.	customers:read
GET	/plugin-api/users/get	Personel (kullanıcı) listesi [{ id, name }] — name yalnız PII consent ile. Max 200, cache'le. pincode/yetki/e-posta/mesai dönmez.	users:read
POST	/plugin-api/products/{create,update,delete}	Ürün katalog yazma. Sahiplik: yalnız kendi oluşturduğunu düzenler/siler. category var olmalı; cost/stock/image yazılamaz.	products:write
POST	/plugin-api/categories/{create,update,delete}	Kategori katalog yazma (products:write; ayrı scope yok). delete: kategori boş olmalı (categoryNotEmpty).	products:write
POST	/plugin-api/payment-methods/{create,update,delete}	Ödeme yöntemi tanımı yazma. Sahiplik kontrollü. Personel ataması panelden (API'de yazılamaz).	payment_methods:write
POST	/plugin-api/ingredients/{create,update,delete}	Malzeme/stok kartı yazma. Sahiplik kontrollü. stock/ort yazılamaz; yeni kart stok 0.	ingredients:write
POST	/plugin-api/purchases/create	Tek-seferlik (IAP) satın alma başlat. Stripe Checkout URL üretir; tenant UI'da öder. Gross kuruş [min,max]; idempotencyKey ile retry-güvenli. Ayrı write kovası.	purchases:write
GET	/plugin-api/purchases/get?purchaseId=	IAP satın alma durumu (authoritative). status/type/productKey/amount/currency/zaman damgaları. net/developerShare/Stripe ID gibi finansal alanlar sızmaz.	purchases:read
GET	/plugin-api/purchases/list	Kendi IAP satın almaları — en yeni önce, limit max 100. Yalnız çağıran install'ın (serverId+pluginId) kayıtları; başka eklenti/tenant görünmez.	purchases:read
POST	/plugin-api/messaging/send	Eklentiler-arası: tenant'ın bağladığı mesaj sağlayıcısı (WhatsApp/SMS eklentisi) üzerinden müşteriye mesaj isteği. to yalnız {customerId} (ham PII yasak); idempotencyKey zorunlu; accepted ≠ delivered. Ayrı messaging kovası (60/dk).	messaging:send
POST	/plugin-api/messaging/status	Eklentiler-arası (sağlayıcı): teslim durumu raporu (DLR — sent/delivered/read/failed). Platform yalnız istek sahibi tüketiciye hedefli messaging.message.status event'i teslim eder; aynı raporun tekrarı idempotent.	messaging:provide
POST	/plugin-api/capabilities/{cap}/invoke	JENERİK eklentiler-arası yetenek çağrısı (Faz 4). cap = katalog yeteneği (messaging.send, notify.staff, invoice.issue). Tüketici, tenant'ın bağladığı sağlayıcıya ilgili payload'ı yollar; idempotencyKey zorunlu. messaging.send eski /messaging/send ucuyla aynı sonuç.	capability:{cap}:consume
POST	/plugin-api/capabilities/{cap}/status	JENERİK sağlayıcı asenkron durum raporu (yalnız async-status'lu capability'ler: messaging.send, invoice.issue). Platform yalnız istek sahibi tüketiciye hedefli status event'i teslim eder.	capability:{cap}:provide

Bu liste büyür — yeni uçlar zamanla eklenir; her uç kendi detay sayfasıyla burada listelenir.

OpenAPI spec'i (makine-okunur)

Tüm uçlar + webhook sözleşmeleri (event/lifecycle zarfları, imza header'ları, gerçek örnek payload'lar) OpenAPI 3.1 olarak yayınlanır — bu sayfayı besleyen tek-kaynak kataloglardan build sırasında üretilir, dokümanla asla sapmaz:

İnteraktif dene: API Referansı (try-it konsolu) — uçları tarayıcıda keşfet + dev-store apiKey'inle gerçek istek at.
Ham spec: /openapi.json — operasyonlar gerekli scope'u x-required-scope, yayın durumunu x-status (live|soon) ile taşır; alan tabloları için her operasyonun externalDocs'u detay sayfasına gider.
Postman / Insomnia / Bruno: /openapi.json'u Import et — koleksiyon otomatik oluşur (uç + örnek + auth).

Typed SDK üret:

# OpenAPI Generator (çok dilli)
npx @openapitools/openapi-generator-cli generate \
  -i https://dev.restomenum.com/openapi.json -g typescript-fetch -o ./sdk

# veya orval (TS, React Query)
npx orval --input https://dev.restomenum.com/openapi.json --output ./sdk/client.ts

AI ajanları için ayrıca: /llms.txt ve changelog RSS (/changelog.xml). Sürüm/uyumluluk politikası: Versiyonlama & Deprecation.