Restomenum Geliştirici
Giriş yapKayıt ol

Mimari & Kavramlar

Bir Restomenum eklentisinin nasıl çalıştığının kuş bakışı haritası: kurulum/kimlik, Restomenum ↔ eklenti iletişiminin yönleri, scope/consent, imzalama ve yaşam döngüsü. Her kavram ilgili detay sayfasına bağlıdır.

Uçtan uca ilk eklenti için: Hızlı Başlangıç.

Büyük resim

  Eklenti (senin sistemin: webhookUrl · connectUrl · actionUrl — hepsi TEK domain)
        ▲   │
   (3)  │   │  Restomenum → eklenti
 webhook│   ├─ webhook event'leri (async)        /docs/events
 imzalı │   ├─ lifecycle webhook'ları (async)    /docs/lifecycle
        │   ├─ hook/gate çağrısı (senkron)       /docs/hooks
        │   └─ aksiyon butonu POST (senkron)     /docs/buttons
        │   ▼
  Restomenum (panel + runtime)
        ▲
   (4)  │  eklenti → Restomenum
 Bearer │  ├─ Veri API (oku)                     /docs/api
 apiKey │  └─ packets/create (yaz)               /docs/api/packets-create
        │
   (1)(2) Kurulum: OAuth Connect → Token Exchange → { tenantId, apiKey, webhookSecret, scopes }

Eklentin kendi sunucundur (kayıtlı bir domain altında webhookUrl, connectUrl, actionUrl + iframe UI origin'i). Restomenum ile iki yönde konuşur; hangi veriyi okuyabildiğini/ne yapabildiğini scope'lar belirler.

1) Kurulum & Kimlik

Tenant eklentini kurarken OAuth Connect akışı çalışır; dönen tek-kullanımlık code'u Token Exchange ile kalıcı dört değere çevirirsin ve tenant başına saklarsın:

DeğerNe için
tenantIdKurulumun kimliği (her event/çağrı bununla eşlenir)
apiKeyVeri API çağrılarında Authorization: Bearer (serverId.pluginId.secret)
webhookSecretwebhook/hook imza doğrulaması + session token doğrulaması (HMAC)
scopesTenant'ın gerçekten onayladığı yetkiler (manifest'te istediğinin alt kümesi olabilir)

Kurulum/abonelik durumu ayrıca Lifecycle Webhook'ları ile bildirilir (install/uninstall, subscription) — bunlara abone olmazsın, her bağlı kuruluma gelir.

2) Restomenum → eklenti (gelen)

  • Webhook event'leri (async): bir şey olduğunda haber (packet.created…). Manifest events[] + events:subscribe ister. Event Kataloğu.
  • Lifecycle webhook'ları (async): kurulum/abonelik sinyalleri. Abonelik gerekmez. Lifecycle.
  • Hook/Gate (senkron): bir çekirdek işlem (masa/paket kapanışı, statü) gerçekleşmeden ÖNCE sorulur; allow/deny dönersin. Hook'lar.
  • Aksiyon butonu (senkron): panele eklediğin buton actionUrl'ine POST eder. Butonlar.
Hepsi imzalıdır (X-Restomenum-Signature, HMAC, ±5 dk). Gelen her isteği ham gövde üzerinden doğrula; geçersizse 401 dön. İmza şeması.

3) Eklenti → Restomenum (giden)

  • Veri API (oku): GET {RESTOMENUM_BASE}/plugin-api/…, Authorization: Bearer apiKey. API Uçları.
  • Yazma: POST /plugin-api/packets/create (orders:write). Fiyat sunucuda hesaplanır; idempotencyKey ile retry-güvenli.
  • iframe UI: Custom UI sayfalarınız session token (JWT, webhookSecret ile imzalı) ile kendi backend'inize güvenli çağrı yapar.

Temel ilkeler

  • Scope & consent: ne okuyabildiğini scope belirler; PII scope'ları (customers:read, users:read) ek consent ister. Scope Referansı.
  • Tek-apex: webhookUrl + connectUrl + actionUrl + tüm UI origin'leri aynı registered domain altında olmalı. iframe Güvenliği.
  • Etkileşim yalnız id taşır: event/hook/buton gövdesi target.id verir; dolu veriyi Data API'den çekersin (opt-in includeData hariç).
  • Idempotency: her gelen isteğin bir id'si var; retry'da tekrar gelir → id ile dedup.
  • Yaşam döngüsü: manifest → sürüm draft → incelemeye gönder → onay → published; her yeni sürüm kendi review'undan geçer.