v1 · REST + Webhook'lar

Geliştirici dokümantasyonu

Tek bir API üzerinde müşteri, sürücü ve satıcı uygulamaları oluşturun. Restoranları, menüleri, siparişleri ve sürücüleri okuyun ve yazın; imzalı webhook'lar üzerinden gerçek zamanlı olaylar alın. Her şey belirteç sahibiyle sınırlıdır.

🛍️ müşteri uygulaması 🛵 Sürücü uygulaması 🧑‍🍳 Satıcı uygulaması

Pazar yeri için mi geliştiriyorsunuz? Uygulama geliştirici belgeleri →  ·  Tema geliştirici belgeleri →

Yeni bizim Dev MCP sunucusu MCP destekli herhangi bir AI aracını bir platform uzmanına dönüştürür. learn_platform onu hazırlar, get_liquid_reference ona yetkili beyaz listeyi verir ve validate_theme çıktısı üzerinde pazar yerinin kendi kontrollerini çalıştırır — editörünüzden çıkmadan tam öğren → oluştur → doğrula döngüsü. Tek komutla bağlanın →

Başlarken

Panonuzda şuradan bir API belirteci oluşturun: API token'ları ve Webhook'lar. Şunu seçin: read ve/veya write yetkilerini seçin ve belirteci kopyalayın — yalnızca bir kez gösterilir.

Temel URL: https://mail.menubarcode.com/api/v1

Belirtecinizin çalıştığına dair hızlı bir kontrol:

curl https://mail.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer YOUR_TOKEN"
Kök GET https://mail.menubarcode.com/api/v1 kullanılabilir uç noktaların makine tarafından okunabilir bir dizinini döndürür (kimlik doğrulaması gerekmez). Makine tarafından okunabilir OpenAPI 3.1 spesifikasyonu (JSON) — canlı yönlendiriciden oluşturulur, bu yüzden her zaman dağıtılan API ile eşleşir.

Kimlik doğrulama

Her istekte belirtecinizi bir Bearer üstbilgisi olarak gönderin:

Authorization: Bearer YOUR_TOKEN

Hızlı testler için bunun yerine şunu geçebilirsiniz: ?api_token=YOUR_TOKEN bir sorgu parametresi olarak, ancak belirteçler asla günlüklere sızmasın diye üstbilgi kesinlikle tercih edilir.

YetkiTahsisler
readTümü GET uç noktalar (her kaynak).
writeTüm değiştiren uç noktalar (ve bir üst küme olduğundan tüm okumalar).

Kapsamlı belirteçler

Kaba kapsamın ötesinde read/write, bir belirteç şununla belirli kaynaklarla sınırlanabilir: resource:action yetkiler. Kaynaklar: restaurants, menu, orders, customers, analytics, drivers, webhooks; İşlemler read, write. Belirteci panoda oluştururken bunları seçin.

Örnek belirteçYapabilir
["orders:write"]Yalnızca siparişleri okuma + yazma (bir POS entegrasyonu).
["menu:read"]Menüyü oku; başka bir şey değil.
["orders:read","analytics:read"]Bir raporlama panosu.

Kapsam kuralları: * her şeyi verir; bir :write kapsamı ayrıca kendi :read; kaba read/write gibi davranır *:read / *:write. Gerekli kapsamı bulunmayan bir istek şunu döndürür: 403. Eski read/write belirteçler etkilenmez.

Belirteçler durağan halde karma alınır (SHA-256) ve isteğe bağlı bir son kullanma taşıyabilir. Herhangi bir belirteci panodan anında iptal edin.

Hız sınırları

API şuna izin verir: dakikada 120 istek belirteç başına. Bunu aşmak şunu döndürür: 429 Too Many Requests şununla: Retry-After üstbilgisi. Standart hız sınırı üstbilgileri her yanıta dahil edilir:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

Hatalar

Bir üzerindeki her hata /api/v1 rota geleneksel HTTP durum kodları ve tek bir JSON zarfı döndürür — insan tarafından message, kararlı bir makine code, ve (doğrulamada) alan başına bir errors Harita

{ "message": "Invalid or expired token.", "code": "unauthenticated" }

{ "message": "The given data was invalid.",
  "code": "validation_failed",
  "errors": { "title": ["The title field is required."] } }
durumcodeAnlamı
401unauthenticatedEksik, geçersiz veya süresi dolmuş belirteç.
403forbiddenBelirteç gerekli yetkiye/kapsama sahip değil.
404not_foundKaynak bulunamadı veya belirtece ait değil.
422validation_failedDoğrulama başarısız (bkz. errors).
429rate_limitedHız sınırı aşıldı.
Makineyi ayrıştırın code, insan olanı değil message — iletiler yeniden ifade edilebilir veya yerelleştirilebilir; kodlar kararlıdır.
Sahibi olmadığınız bir kaynağı istemek şunu döndürür: 404, değil 403 — API asla başka bir sahibin verisinin varlığını onaylamaz.

Sayfalama

Liste uç noktaları Laravel tarzı sayfalandırılmış zarflar döndürür. Şunu kullanın: ?page= sayfalarda gezinmek için sorgu parametresi.

{
  "data": [ ... ],
  "current_page": 1,
  "last_page": 3,
  "per_page": 20,
  "total": 47
}

Restoranları ve menüyü oku

GET /restaurants

Belirtece ait restoranları listeleyin, sayfalandırılmış (sayfa başına 20).

{
  "data": [
    { "id": 12, "title": "Nova Bistro", "slug": "nova-bistro",
      "url": "https://.../nova-bistro", "template": "linen",
      "created_at": "2026-06-01T10:22:00+00:00" }
  ],
  "current_page": 1, "last_page": 1, "total": 1
}
GET /restaurants/{id}

Menü kategorileri ve öğe sayısı ile birlikte tek bir restoran.

GET /restaurants/{id}/menu

Kategoriye göre gruplanmış tam aktif menü.

[
  { "id": 3, "name": "Starters",
    "items": [
      { "id": 88, "name": "Bruschetta", "price": 6.50,
        "is_sold_out": false, "is_popular": true, "is_vegan": true,
        "is_halal": true, "calories": 210 }
    ]
  }
]

Siparişler

GET /restaurants/{id}/orders

Siparişler en yeni önce, sayfalandırılmış (sayfa/30). Şununla filtreleyin: ?status=.

GET /restaurants/{id}/orders/{orderId}

Satır öğeleri, ekstralar, sürücü ve teslimat zaman çizelgesi ile tam sipariş ayrıntısı.

POST /restaurants/{id}/orders Yaz

Bir sipariş oluşturun — bir müşteri uygulaması bir sepet gönderir (satıcının arka ucu belirteci tutar). Her öğe restoranın canlı menüsüne göre doğrulanır; tükenen veya yabancı öğeler tüm siparişi reddeder (422). Şunu tetikler: order.created ve şunu içeren tam siparişi döndürür: track_token.

curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/orders \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "delivery",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "address": "9 Cedar Road",
    "tip_amount": 3.00,
    "note": "Ring the bell",
    "source": "customer_app",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12], "note": "no onion" },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Sipariş type şunlardan biridir: on-table, takeaway, delivery. için on-table geçir table_number; için delivery geçir address.

Etkisizlik (idempotency). Bir gönder Idempotency-Key üstbilgisi (veya bir gövde client_uuid) herhangi bir sipariş oluşturma çağrısında. Aynı anahtarla yeniden denemek orijinal siparişi döndürür ve asla bir kopya oluşturmaz — kesilen yanıtlar ve çevrimdışı yeniden oynatma için güvenlidir. Anahtarlar restoran başına kapsamlıdır.

PUT /restaurants/{id}/orders/{orderId}/status Yaz

Mutfak durumunu güncelleyin (new|preparing|ready|delivered|completed|cancelled). Tetikler order.status_changed.

Storefront API (restoran başına belirteç)

Bir ile kimliği doğrulanan ayrı, herkese açık bir API restoran başına storefront belirteci şu şekilde gönderilir: X-Storefront-Token (sahip Bearer belirteci değil). Bunları panonuzdan verin; her belirteç yalnızca kendi restoranına ulaşabilir. Okuma kapsamı şudur: menu:read; sipariş vermek şunu gerektirir: order:write Kapsam

GET /storefront/menu

Belirtecin restoranı için tam menü (varyantlar, ekstralar, gruplar, galeri).

GET /storefront/restaurant

Belirtecin restoranı için temel restoran bilgileri.

POST /storefront/orders order:write

Bir müşteri adına bir sepet gönderin. Sunucu tarafından fiyatlandırılır ve ödenmedi (müşteri geldiğinde öder); takeaway veya on-table yalnızca. Her öğe canlı menüye göre doğrulanır — tükenen veya yabancı öğeler tüm siparişi reddeder (422). Sınırlar: sipariş başına 40 öğe, satır başına 30 adet. İsteğe bağlı coupon_code sunucu tarafında bir sahip indirimi uygular. Tetikler order.created ve döndürür track_token + continue_url.

curl -X POST https://mail.menubarcode.com/api/v1/storefront/orders \
  -H "X-Storefront-Token: YOUR_STOREFRONT_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "takeaway",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "coupon_code": "WELCOME10",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12] },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Analizler ve müşteriler

GET /restaurants/{id}/analytics

Bir tarih aralığı üzerindeki satış özeti (?from=YYYY-MM-DD&to=YYYY-MM-DD, varsayılan son 30 gün): duruma/türe göre sipariş sayıları, brüt ve ödenmiş gelir, ortalama sipariş değeri ve en çok satan öğeler.

{
  "range": { "from": "2026-06-02", "to": "2026-07-02" },
  "orders": { "total": 214, "paid": 198, "by_status": {...}, "by_type": {...} },
  "revenue": { "gross": 8420.50, "paid": 7990.00, "avg_order_value": 39.35 },
  "top_items": [ { "item_id": 88, "name": "Margherita", "quantity": 143 } ]
}
GET /restaurants/{id}/customers

Restoranın müşteri listesi (CRM), sayfalandırılmış. Şununla filtreleyin: ?search=.

Sürücüleri yönet Yaz

Sürücüler size ve (isteğe bağlı olarak) bir restorana aittir. Bir sürücü oluşturmak veya döndürmek ham bir belirteç döndürür: sürücü belirteci tam olarak bir kez — sürücünün uygulamasına verin; onunla kimlik doğrularlar (aşağıya bakın).

GET /drivers
POST /drivers
curl -X POST https://mail.menubarcode.com/api/v1/drivers \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Alex","phone":"+15550001111","restaurant_id":12}'

# → { "id": 7, "name": "Alex", ..., "token": "RAW_DRIVER_TOKEN_SHOWN_ONCE" }
PUT /drivers/{id}
DELETE /drivers/{id}
POST /drivers/{id}/rotate-token

Eski belirteci geçersiz kılar ve yeni bir tane döndürür.

Bir teslimatı ata ve takip et

GET /restaurants/{id}/deliveries

Teslimat siparişleri, şuna göre filtrelenebilir: ?delivery_status= ve ?driver_id=.

POST /restaurants/{id}/orders/{orderId}/assign Yaz

Kurye ata {"driver_id": 7}. Ayarlar delivery_status=assigned ve tetikler order.driver_assigned.

PUT /restaurants/{id}/orders/{orderId}/delivery-status Yaz

Teslimat aşamasını geçersiz kılın: pending | assigned | picked_up | out_for_delivery | delivered | failed.

Sürücü uygulaması API

Sürücü uygulaması bir ile kimlik doğrular Kurye token’ı (sahip belirteci değil) yukarıda verildi. Temel yol https://mail.menubarcode.com/api/v1/driver. Her yanıt o tek sürücüyle sınırlıdır.

Authorization: Bearer RAW_DRIVER_TOKEN
GET /driver/me

Kimliği doğrulanmış sürücünün profili.

GET /driver/deliveries

Bu sürücüye atanan siparişler. Şunu ekleyin: ?active=1 teslim edilenleri/başarısızları gizlemek için.

PUT /driver/deliveries/{orderId}/status

Teslimatı ilerletin: {"delivery_status":"out_for_delivery"} sonra "delivered" veya "picked_up" / "failed", isteğe bağlı note). Sahip uç noktasıyla aynı webhook'ları tetikler.

PUT /driver/location

Canlı konumu gönderin: {"lat":25.2048,"lng":55.2708}. Teslimattayken müşterinin takip görünümünde gösterilir.

Müşteri hesapları

A bağımsız müşteri uygulaması kendi kullanıcılarını müşteri başına bir belirteçle doğrular (Sanctum tarzı: birden çok cihaz, ayrı ayrı iptal edilebilir). Hiçbir sahip belirteci söz konusu değildir. Müşteriler restoran başına kapsamlıdır, bu yüzden kimlik doğrulama şu altındadır: /restaurants/{id}/customer/…. Önce herkese açık uç noktayla menüye göz atın:

GET /menu/{restaurantId} Genel

Kategoriye göre gruplanmış aktif menü (tükenen öğeler çıkarılır). Kimlik doğrulaması yok.

Kaydol / giriş yap

POST /restaurants/{id}/customer/register
POST /restaurants/{id}/customer/login
curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/customer/login \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","password":"secret123","device":"iPhone 15"}'

# → { "token": "RAW_CUSTOMER_TOKEN", "customer": { "id": 42, "name": "Sam", ... } }

Parolasız (SMS OTP)

POST /restaurants/{id}/customer/otp/request
POST /restaurants/{id}/customer/otp/verify

Bir telefon numarası için bir kod isteyin, ardından doğrulayın. Doğrulama müşteriyi bulur veya oluşturur ve bir belirteç döndürür. Kimlik doğrulama uç noktaları hız sınırlıdır (giriş/kayıt 10/dk, OTP isteği 6/dk).

Müşteri uygulaması API

Müşteri belirteci ile kimlik doğrulayın. Temel yol https://mail.menubarcode.com/api/v1/customer. Her şey kimliği doğrulanmış müşteriyle sınırlıdır — sipariş gövdesi asla başka bir müşterinin kimliğini taklit edemez.

Authorization: Bearer RAW_CUSTOMER_TOKEN
GET /customer/me
PUT /customer/me

Profil okuma / güncelleme (ad, e-posta, telefon, doğum günü, onaylar).

POST /customer/orders

Bu müşteri olarak bir sipariş verin (satıcı oluşturma uç noktasıyla aynı öğe biçimi; kimlik belirteçten alınır). Siparişi şunu ile birlikte döndürür: track_token.

GET /customer/orders

Müşterinin kendi sipariş geçmişi, sayfalandırılmış.

GET /customer/addresses
POST /customer/addresses
DELETE /customer/addresses/{id}

Kayıtlı teslimat adresleri (ilki varsayılan olur; şunu destekler: lat/lng).

POST /customer/logout

İstek için kullanılan belirteci iptal eder (yalnızca o cihaz).

Sipariş takibi Genel

Kimlik doğrulaması yok — erişim siparişin tahmin edilemez şeyi ile kısıtlanır: track_token (sipariş oluşturulduğunda döndürülür). Bu bir şeyi çalıştırır: müşteri uygulaması canlı takip ekranı.

GET /track/{token}
{
  "id": 5501, "status": "preparing", "delivery_status": "out_for_delivery",
  "is_paid": true, "total": 42.00,
  "timeline": { "preparing_at": "...", "out_for_delivery_at": "..." },
  "items": [ { "name": "Margherita", "quantity": 2 } ],
  "driver": { "name": "Alex", "lat": 25.2, "lng": 55.27, "location_updated_at": "..." }
}

Sürücü bloğu (canlı koordinatlarla) yalnızca sipariş teslim alındığında / teslimata çıktığında görünür.

Personel Girişi

A personel uygulaması (POS / KDS / garson) her personeli personel başına bir belirteçle doğrular. İki yol panoyu yansıtır: e-posta + parola veya hızlı bir sayısal PIN paylaşılan mutfak tabletleri için. Personel restoran başına kapsamlıdır.

POST /restaurants/{id}/staff/login
POST /restaurants/{id}/staff/pin
curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/staff/pin \
  -H "Content-Type: application/json" -d '{"pin":"4321","device":"Kitchen iPad"}'

# → { "token": "RAW_STAFF_TOKEN",
#     "staff": { "id": 3, "role": "kitchen", "permissions": ["kds"] } }

Yanıt, personelin etkin şeyini listeler: İzinler — şunun bir alt kümesi: orders, menu_edit, coupons, analytics, kds, customers rollerinden türetilir (yönetici / kasiyer / mutfak / garson) artı personel başına geçersiz kılmalar. Uç noktalar izinle kısıtlanır (403 aksi takdirde).

Personel uygulaması API

Personel belirteci ile kimlik doğrulayın. Temel yol https://mail.menubarcode.com/api/v1/staff. Tüm işlemler personelin restoranıyla sınırlıdır.

Authorization: Bearer RAW_STAFF_TOKEN
GET /staff/me

Rol ve izin listesiyle profil.

GET /staff/orders orders
PUT /staff/orders/{orderId}/status orders

Siparişleri listeleyin ve mutfak durumunu güncelleyin. Şunu gerektirir: orders izin.

GET /staff/kds kds

Siparişe göre gruplanmış, personelin istasyonuna göre filtrelenmiş canlı mutfak fişleri (veya ?station_id=). Yalnızca hâlâ şu olan öğeleri gösterir: queued|preparing|ready.

PUT /staff/kds/items/{itemId}/bump kds
PUT /staff/kds/items/{itemId}/recall kds

İlerlet (queued → preparing → ready → served) veya bir KDS durumu geri git. Üst siparişin durumu otomatik olarak yeniden senkronize edilir.

POST /staff/menu/items menu_edit
PUT /staff/menu/items/{itemId} menu_edit
DELETE /staff/menu/items/{itemId} menu_edit
PATCH /staff/menu/items/{itemId}/sold-out menu_edit
POST /staff/menu/categories menu_edit

Menüyü zeminden düzenleyin (yöneticiler). Satıcı menü uç noktalarıyla aynı yükler, personelin restoranıyla sınırlıdır.

GET /staff/analytics analytics

Personelin restoranı için satış özeti (satıcı analiz uç noktasıyla aynı biçim; ?from=&to=).

POST /staff/logout

Bu cihazın belirtecini iptal eder.

Webhook'lar — kurulum

Uç noktaları panodan şuradan kaydedin: API token'ları ve Webhook'lar. Her uç noktanın hangi olayları aldığını seçin. Kaydettiğinizde uç nokta başına bir şey alırsınız: İmzalama gizli anahtarı; Şunu kullanın: Test düğmesiyle bir şey gönderin: ping. Gizli anahtarını kaybetmeden teslimatı durdurmak için bir uç noktayı duraklatın.

Uç noktanız bir ile yanıt vermeli: 2xx durumu hızlıca (10 sn içinde). Başka herhangi bir durum — veya bir zaman aşımı — başarısızlık olarak değerlendirilir ve yeniden denenir.

Uç noktalar ayrıca şu şekilde yönetilebilir: programatik olarak (Zapier/Make REST-Hooks için) bir ile: webhooks:write belirteç:

GET    /api/v1/webhook-endpoints            # list your endpoints
POST   /api/v1/webhook-endpoints            # {"url":"https://…","events":["order.created"]} → 201 {id, secret, …}
DELETE /api/v1/webhook-endpoints/{id}       # unsubscribe → 204

Şu secret döndürülür yalnızca oluşturmada — imzayı doğrulamak için saklayın. url herkese açık bir HTTPS uç noktası olmalıdır (SSRF korumalı); events aşağıdaki listeden olmalıdır (veya *).

Webhook olayları

OlayNe zaman tetiklenir
order.createdYeni bir sipariş verildiğinde (pano veya API).
order.status_changedBir siparişin mutfak durumu değiştiğinde (pano, POS veya API).
order.paidBir sipariş tamamen ödenmiş olarak işaretlendiğinde (ödeme geçidi veya hesap bölme).
order.driver_assignedBir teslimata bir sürücü atandığında.
order.out_for_deliverySürücü müşteriye doğru yola çıktığında.
order.deliveredTeslimat tamamlandığında.
order.delivery_failedTeslimat tamamlanamadığında.
refund.completedBir sipariş için iade tamamlandı.
reservation.createdBir masa rezervasyonu oluşturuldu.
reservation.cancelledBir masa rezervasyonu iptal edildi.
customer.createdYeni bir müşteri kaydı oluşturuldu.
shift.openedBir kasa / POS vardiyası açıldı.
shift.closedBir kasa / POS vardiyası kapatıldı.
menu.updatedBir menü öğesi veya kategori oluşturulduğunda, güncellendiğinde veya silindiğinde (herhangi bir yüzey). Yük: {restaurant_id, change, entity, id}.
entitlement.changedÇalışma alanı için bir özellik yetkisi verildiğinde veya iptal edildiğinde (plan değişikliği, eklenti, uygulama kurulumu/kaldırılması, yönetici geçersiz kılması). Yük: {action, feature_key, source_type, source_id, user_id, occurred_at} şurada action şudur granted veya revoked.
subscription.*Abonelik yaşam döngüsü: subscription.paused, .resumed, .renewed, .expired, .plan_changed, .past_due, .expiring, .trial_ending.
app.uninstalledBir pazar yeri uygulaması kaldırıldığında (uygulamanın uç noktasına teslim edilir).
*Yukarıdaki her olaya abone olun.
pingŞu tarafından gönderildi: Test bağlantıyı doğrulamak için düğme.

Uç noktanız kapalıyken bir teslimat başarısız mı oldu? Şunu kullanın: Yeniden teslim et panonun Son teslimatlar günlüğündeki herhangi bir satırda, onu yeni bir ile yeniden kuyruğa almak için: webhook-id.

Webhook yükü

Her teslimat bir POST bu JSON zarfı ve bu üstbilgilerle:

POST /your-endpoint HTTP/1.1
Content-Type: application/json
webhook-id: msg_a1b2c3d4e5f6g7h8i9j0k1l2
webhook-timestamp: 1751472240
webhook-signature: v1,K5f...base64...==
X-Webhook-Event: order.created          (legacy)
X-Webhook-Signature: 9a3f...hex...      (legacy, HMAC of body only)

{
  "id": "msg_a1b2c3d4e5f6g7h8i9j0k1l2",
  "event": "order.created",
  "created_at": "2026-07-02T18:04:00+00:00",
  "data": { "order_id": 5501, "total": "42.00" }
}

Şu id teslimat başına benzersizdir. Yeniden denemeler aynı şeyi yeniden kullandığından: id, işleyicinizi etkisiz (idempotent) yapmak için kullanın.

İmzayı doğrulama

Şu webhook-signature üstbilgisi bir HMAC-SHA256'dır, base64 ile kodlanmış, şu üzerinde hesaplanmış: {id}.{timestamp}.{body} uç noktanızın imzalama gizli anahtarını kullanarak. Kimliği ve zaman damgasını imzaya bağlamak, yakalanmış bir isteği yeniden oynatmaya karşı güvenli kılan şeydir. Şu değeri olan herhangi bir isteği reddedin: webhook-timestamp yaklaşık 5 dakikadan daha eskidir.

PHP

$secret  = 'whsec_from_dashboard';
$id      = $_SERVER['HTTP_WEBHOOK_ID'];
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body    = file_get_contents('php://input');
$sent    = explode(',', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])[1] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $secret, true));
if (!hash_equals($expected, $sent)) { http_response_code(401); exit; }

// verified — process $body
http_response_code(200);

Node.js

const crypto = require('crypto');

function verify(req, secret) {
  const id  = req.headers['webhook-id'];
  const ts  = req.headers['webhook-timestamp'];
  const sig = (req.headers['webhook-signature'] || '').split(',')[1];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${id}.${ts}.${req.rawBody}`)
    .digest('base64');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig || ''));
}
eski bir X-Webhook-Signature üstbilgisi (gövdenin düz HMAC-SHA256'sı, onaltılık) geriye dönük uyumluluk için de gönderilir. Yeni entegrasyonlar şunu kullanmalıdır: webhook-signature.

Yeniden denemeler ve teslimat günlüğü

Teslimat eşzamansızdır ve başarısızlıkta üstel geri çekilme artı titreme ile yeniden denenir: kabaca 1m → 5m → 15m → 1h (toplam 5 denemeye kadar). Her deneme — başarı veya başarısızlık — panonuzdaki teslimat günlüğüne HTTP durumu, deneme numarası ve yanıt parçası ile kaydedilir.

Teslimat şudur: en az bir kez. Şu üzerinde yinelemeleri kaldırın: webhook-id zaman zaman tekrarları ele almak için.

MCP sunucuları

Yeni her istemci için tek sayfalık, kopyala-yapıştır bir kurulum kılavuzu şurada bulunur: /mcp — istemci başına kurulum komutları, tek tıklamalı derin bağlantılar, araç kataloğu ve örnek istemler. Bu sayfa ayrıntılı referans olarak kalır.

Beş Model Context Protocol sunucusu AI ajanlarını (ChatGPT, Claude, Cursor) platforma bağlar — kitlenize uyanı seçin. Hepsi HTTP üzerinden JSON-RPC 2.0 konuşur ve protokol sürümlerini müzakere eder 2024-11-05 / 2025-03-26 / 2025-06-18.

SunucuUç noktaKitleKimlik doğrulamaAraçlar
Adminhttps://mail.menubarcode.com/mcpMağaza sahipleri — mağazayı yönetAPI token'ı (Bearer)23
Storefronthttps://mail.menubarcode.com/mcp/storefrontBir müşterinin ajanı — bir mağazadan alışveriş yap ve sipariş verVitrin token'ı (aracı kapsamı)12
Customerhttps://mail.menubarcode.com/mcp/customerGiriş yapmış bir müşteri — kendi siparişleriMüşteri token'ı (OTP ile giriş)5
Cataloghttps://mail.menubarcode.com/mcp/catalogHerkes — platform genelinde mağazaları keşfetGenel3
Devhttps://mail.menubarcode.com/mcp/devAI kodlama araçları — temalar/entegrasyonlar oluşturGenel7

Hızlı başlangıç: şuraya atla Admin, Catalog, Customer, veya Dev. Storefront sunucusu, Admin bağlantı desenini bir ile paylaşır: X-Storefront-Token Bearer belirteci yerine üstbilgisi.

MCP sunucusu (Admin)

MCP uyumlu bir AI istemcisi (Claude, ChatGPT, Cursor) aynı API belirteçlerini kullanarak restoranınızı doğal dilde işletebilir. Onu şuna yönlendirin:

POST https://mail.menubarcode.com/mcp JSON-RPC 2.0

Şununla kimlik doğrulayın: Authorization: Bearer YOUR_TOKEN. Her araç ihtiyaç duyduğu ayrıntılı yetkiyi bildirir (resource:action); eski bir read belirteci her şeyi kapsar: :read araç ve write her şeyi kapsar. Tüm çağrılar restoranlarınızla sınırlıdır ve hız sınırlıdır. Yetkiye sahip olmadığınız araçlar şundan gizlenir: tools/list.

Bağlan (Claude Code)

claude mcp add --transport http platform-admin https://mail.menubarcode.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Araçları listele

curl -X POST https://mail.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Bir aracı çağır (ör. bir menü öğesi ekle)

curl -X POST https://mail.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"add_menu_item",
                 "arguments":{"restaurant_id":12,"name":"Latte","price":4.5}}}'

Araçlar

AraçYetkiNe yapar
list_restaurantsreadSahip olduğunuz restoranlar.
get_menureadBir restoranın kategorileri ve öğeleri.
list_categoriesmenu:readÖğe sayılarıyla kategoriler.
add_categorymenu:writeBir kategori oluştur.
update_categorymenu:writeBir kategoriyi yeniden adlandır / yeniden sırala.
delete_categorymenu:writeBir kategoriyi sil (öğeleri varsa reddeder).
add_menu_itemwriteBir menü öğesi oluştur (plan limiti kontrol edilir).
update_menu_itemwriteBir ürünün adını/fiyatını/açıklamasını düzenleyin.
delete_menu_itemmenu:writeBir ürünü kalıcı olarak silin.
set_item_availabilitymenu:writeBir öğeyi stokta var/yok olarak işaretle (86 değiştirici).
list_ordersorders:readSiparişler en yeni önce; durum/tarih/arama filtreleri.
get_orderorders:readSatır öğeleri dahil tam sipariş ayrıntısı.
update_order_statuswriteBir siparişin mutfak durumunu ilerlet.
list_customerscustomers:read + crm_suiteCRM listesi; ad/telefon/e-posta ara. Yetki olmadan tools/list'ten gizlenir.
get_customercustomers:read + crm_suiteBir müşterinin tam kaydı. Yetki olmadan tools/list'ten gizlenir.
sales_reportanalytics:readBir aralık için gelir + sipariş sayıları + en çok satan öğeler.
get_restaurant_settingsrestaurants:readProfil ve sipariş ayarlarının anlık görüntüsü.
update_business_hoursrestaurants:writeÇalışma saatleri metnini ayarla.
list_couponsorders:readİndirim kuponlarınız.
create_couponorders:writeYüzdelik/sabit bir kupon oluştur.
update_couponorders:writeBir kuponu düzenleyin.
delete_couponorders:writeBir kuponu silin.

Catalog MCP (restoranları keşfet)

AI ajanlarının tüm platform genelinde restoranları ve yemekleri keşfetmesine, ardından sipariş vermek için belirli bir mağazaya derin bağlantı yapmasına olanak tanıyan herkese açık, salt okunur bir MCP sunucusu. Kimlik doğrulaması yok, hız sınırlı.

POST https://mail.menubarcode.com/mcp/catalog JSON-RPC 2.0 · public

Bağlan (Claude Code)

claude mcp add --transport http platform-catalog https://mail.menubarcode.com/mcp/catalog
AraçNe yapar
search_storesAnahtar kelimeye/şehre göre restoran bul (ad, adres, menu_url, storefront_mcp ipucu).
search_itemsTüm mağazalarda yemek bul (sorgu/diyet/maks_fiyat/şehir), mağazaya göre gruplanmış.
get_storeSlug veya kimliğe göre bir mağaza için tam herkese açık ayrıntı.
list_starter_menusYeni bir mağazanın başlangıç için kullanabileceği paket başlangıç menüsü hazır ayarları (kafe, pizzacı, burger, fırın, lounge).

Yalnızca aktif, herkese açık listelenen mağazalar görünür; sahipler mağaza ayarlarından çıkabilir. Hiçbir sahip iletişim ayrıntısı asla döndürülmez. Sipariş vermek için mağazanın şunu kullanın: mağaza MCP mağaza başına bir ajan belirteci ile.

Müşteri Hesabı MCP

Bir müşterinin AI asistanının okumasına, takip etmesine ve yeniden sipariş vermesine olanak tanır: kendi siparişleri. Mevcut OTP girişinden müşteri başına bir belirteçle kimliği doğrulanır; müşteri kimliği yalnızca belirteçten gelir — bir telefon veya müşteri kimliği asla bir argüman olarak kabul edilmez.

POST https://mail.menubarcode.com/mcp/customer JSON-RPC 2.0 · customer token

Bir belirteç al (OTP akışı)

# 1) request a one-time code (sent to the customer's phone)
curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/customer/otp/request \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567"}'

# 2) verify the code → returns a customer bearer token
curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/customer/otp/verify \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567","code":"123456"}'

Bağlan (Claude Code)

claude mcp add --transport http my-orders https://mail.menubarcode.com/mcp/customer \
  --header "Authorization: Bearer CUSTOMER_TOKEN"
AraçNe yapar
my_ordersSon siparişleriniz (en yeni önce).
order_detailSiparişlerinizden biri için tam ayrıntı + satır öğeleri.
track_orderSipariş kimliği veya takip belirtecine göre canlı durum.
reorderGeçmiş bir siparişi sepet taslağı olarak yeniden oluştur (tükenen öğeleri atlar).
my_profileAdınız, telefonunuz ve sipariş sayınız.
my_bookingsBu mekandaki kendi otel oda rezervasyonlarınız (kod, durum, tarihler, oda türü, toplam).
curl -X POST https://mail.menubarcode.com/mcp/customer \
  -H "Authorization: Bearer CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"my_orders","arguments":{"limit":5}}}'

AI editörünüzü bağlayın

Claude Code, Cursor veya VS Code ile bir tema veya entegrasyon mu geliştiriyorsunuz? Onu herkese açık şuna yönlendirin: Dev MCP sunucusu — AI aracınız canlı platform dokümanlarını, oluşturulan Liquid beyaz listesini ve sunucu tarafı tema doğrulamasını alır. Belirteç gerekmez.

POST https://mail.menubarcode.com/mcp/dev JSON-RPC 2.0 · public

Claude Code

claude mcp add --transport http platform-dev https://mail.menubarcode.com/mcp/dev

Cursor.cursor/mcp.json

{ "mcpServers": { "platform-dev": { "url": "https://mail.menubarcode.com/mcp/dev" } } }

VS Code.vscode/mcp.json

{ "servers": { "platform-dev": { "type": "http", "url": "https://mail.menubarcode.com/mcp/dev" } } }

Araçlar learn_platform (buradan başla), search_docs / fetch_full_doc, get_liquid_reference, get_section_schema, validate_theme, list_webhook_events. Önerilen ajan iş akışı: öğren → oluştur → doğrula → teslim et.

Yukarıdaki kimliği doğrulanmış MCP sunucusu (https://mail.menubarcode.com/mcp) restoran verilerinizi işletir; bu ise dokümantasyon ve doğrulama sunar ve herkese açık olarak paylaşmak güvenlidir.

Değişiklik günlüğü

TarihDeğiştir
2026-08-20Otel PMS + büyüme sürümü: refund.completed, reservation.created, reservation.cancelled, customer.created, shift.opened, shift.closed webhook olayları; personel push cihazı kaydı + 2fa uç noktalar; yeni MCP araçları hotel_availability, my_bookings, list_starter_menus, list_webhook_events.
2026-07-28Yönlendirici tarafından oluşturulan keşif dizini + OpenAPI 3.1 spesifikasyonu (her zaman dağıtılan API ile eş); Idempotency-Key sipariş oluşturmada; belirteç başına API hız sınırları; subscription.* + app.uninstalled webhook olayları + teslimat Yeniden teslim et.
2026-07-07Genel Dev MCP sunucusu AI kodlama araçları için: canlı doküman araması, oluşturulan Liquid referansı, sunucu tarafı tema doğrulaması.
2026-07-02Ayrıntılı belirteç kapsamları (resource:action); personel menü düzenleme + analiz uç noktaları.
2026-07-02Personel uygulaması: personel başına belirteç kimlik doğrulaması (parola + PIN), rol-izin kısıtlaması, sipariş durumu, KDS ilerlet/geri çağır.
2026-07-02Bağımsız müşteri uygulaması: müşteri başına belirteç kimlik doğrulaması (kayıt/giriş/OTP), profil, sipariş verme + geçmiş, kayıtlı adresler, herkese açık menü tarama.
2026-07-02Tam yönetim API'si: menü CRUD, sipariş oluşturma, sürücüler + teslimat yaşam döngüsü, sürücü uygulaması belirteç API'si, herkese açık sipariş takibi, satış analizleri, müşteriler. Yeni teslimat webhook olayları.
2026-07-02Yeniden denemelerle kuyruğa alınmış webhook teslimatı; Standard-Webhooks imzalama (webhook-id/timestamp/signature); order.paid olayı; herkese açık dokümanlar.
2026-06-26İlk v1 REST API, belirteçler ve webhook uç noktaları.

Şuraya dön: Menubarcode

Menubarcode API v1 · Temel URL https://mail.menubarcode.com/api/v1

Bize Ulaşın

Bizi takip edin