API Uçları — Genel Bakış

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:

• 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ı — OKUMA ve YAZMA aynı zarfı kullanır: veri `data` altında
{ "success": true, "data": { … } }

// hata — aynı zarf; `status` HTTP kodunun gövde içindeki kopyasıdır
{ "success": false, "status": 400, "message": "<kod>" }

POST /packets/create          → data: { packetId, docNo, docNoDate, businessDate }
POST /packets/update          → data: { packetId, updated }
POST /packets/update-orders   → data: { packetId, total }
POST /packets/update-payments → data: { packetId, paid, replayed }
POST /tables/create           → data: { tableId, docNo, docNoDate, total, paid }
POST /tables/update-orders    → data: { tableId, total }
POST /tables/update-payments  → data: { tableId, paid, replayed }

{ "success": true, "data": { "packetId": "e2e-append-packet", "paid": 340, "replayed": false } }

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

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:
  Kopyala

  # 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.