Teslimat Platformları

Operatör menü yolu: Ayarlar → Online Sipariş  •  URL: /admin/settings/online-orders Erişim: ADMIN (yapılandırma), MANAGER (görüntüleme/test/dükkân aç-kapat) • Plan: deliveryIntegration özelliği olan planlar

Bu entegrasyon restoranınızı Yemeksepeti, Getir, Trendyol Yemek ve Migros Yemek platformlarına bağlar. Gelen siparişler doğrudan bir HummyTummy Order kaydına dönüşür, mutfak ekranına (KDS) düşer ve mutfak yazıcısına otomatik basılır. Tüm akış tek bir module (delivery-platforms) içinde toplanmıştır; siparişler, menü senkronu ve dükkân aç/kapat aynı adaptör katmanı üzerinden çalışır.

1. Platform başına bağlantı

Her platform için tenant başına tek bir yapılandırma (DeliveryPlatformConfig) tutulur. Operatör, kimlik bilgilerini Ayarlar → Online Sipariş ekranından girer; sunucuda şifrelenerek saklanır (yanıtlarda asla geri dönmez, yalnızca hasCredentials / hasAccessToken bayrakları döner).

Yapılandırma alanları

Platforma göre kimlik bilgileri

Her adaptör farklı bir kimlik doğrulama yöntemi kullanır:

credentials = { clientId, clientSecret, chainCode?, posVendorId? }

credentials = { appSecretKey, restaurantSecretKey }

credentials = { apiVersion: "v1" | "v2", username?, password?, integratorId?, integratorSecret? }

credentials = { apiKey }

2. Sandbox / test modu

Canlı bir platform hesabı hiç bağlanmadan tüm ingest → KDS → yazıcı hattını doğrulayabilirsiniz. Yapılandırmanın environment alanını sandbox yapın ve test siparişi tetikleyin.

POST /delivery-platforms/test-order/:platform   (ADMIN)

{ "simulated": true, "orderId": "...", "orderNumber": "YEM-...", "externalOrderId": "TEST-<uuid>", "status": "PENDING_APPROVAL" }

3. Gelen sipariş yaşam döngüsü

Taşıma: webhook vs. yoklama (polling)

İki taşıma da aynı yere iner: adaptör ham gövdeyi NormalizedOrder biçimine çevirir, processIncomingOrder bunu bir Order’a dönüştürür. Dedup garantisi orders(tenantId, source, externalOrderId) üzerindeki kısmi benzersiz index’tir (eşzamanlı çift webhook P2002 ile sessizce yutulur).

Yönlendirme, otomatik kabul ve onay kapısı

• Şube routing: config.branchId bu tenant’ın aktif bir şubesini gösteriyorsa sipariş oraya; aksi halde en eski aktif şubeye düşer.
• Otomatik kabul: autoAccept açıksa sipariş PENDING (mutfak kuyruğunda) oluşturulur ve platform tarafında da kabul edilir.
• Onay zorlama: autoAccept kapalıysa veya eşlenmemiş kalem varsa veya platform toplamları kalem toplamından %5’ten (veya 1₺‘den) fazla saparsa sipariş PENDING_APPROVAL olur — bir operatör onaylayana dek mutfağa girmez.

Operatör aksiyonları

POST /delivery-platforms/orders/:orderId/accept     { prepTimeMinutes? }
POST /delivery-platforms/orders/:orderId/reject      { reason }     (zorunlu)
POST /delivery-platforms/orders/:orderId/prep-time   { minutes }    (1–240)

• Kabul: PENDING_APPROVAL → PENDING; platforma acceptOrder gönderilir. İsteğe bağlı hazırlık süresiyle birlikte yapılabilir. Zaten kabul edilmiş sipariş için no-op (alreadyAccepted: true).
• Ret: reason zorunludur ve platforma iletilir (müşteri/kurye nedeni görür). Yalnızca PENDING_APPROVAL/PENDING reddedilebilir; sonrası iptal akışıdır.
• Hazırlık süresi: platforma markPreparing gönderir ve siparişi PREPARING’e ilerletir.

Dürüstlük sözleşmesi: adaptör çağrısı başarısız olursa hata yukarı taşınır, iç durum ilerletilmez ve hata kaydedilir (log + devre kesici).

İptal, değişiklik ve iade (gelen)

Bu olaylar yalnızca webhook’lu iki platformda (Yemeksepeti, Trendyol) uç nokta olarak vardır; Getir + Migros’ta yoklama üzerinden yüzeye çıkar.

• Durum güncellemesi / iptal — PICKED_UP/DELIVERED → SERVED; CANCELLED/REJECTED → CANCELLED. Atomik ve idempotenttir; terminal bir siparişi geri sektirmez. Yalnızca iç durumu değiştirir, platforma geri bildirim göndermez.
• Değişiklik (amendment) — platform, mutfak işlemeden önce sipariş kalemlerini değiştirir. Tam sepet yeniden çözümlenir, toplamlar aynı drift-güvenli mantıkla yeniden hesaplanır, KDS’e yeniden yayınlanır. Sipariş READY/SERVED/PAID/CANCELLED ise reddedilir (kâğıt fiş ile pişen yemeğin senkronu bozulmasın diye); platform iptal + yeniden sipariş etmelidir.
• İade (refund) — platform iadeyi başlatır (parayı platform tutar). Biz yalnızca yansıtırız, geri bildirim göndermeyiz:
  • Tam iade → sipariş CANCELLED olur (cancelledAt işlenir).
  • Kısmi iade → durum korunur.

4. Webhook URL’leri ve imzalar

Webhook uç noktaları Public ama WebhookAuthGuard ile korunur ve dakikada 60 istekle hız sınırlıdır. :remoteId her zaman remoteRestaurantId’dir.

POST /webhooks/delivery/yemeksepeti/order/:remoteId
PUT  /webhooks/delivery/yemeksepeti/:remoteId/order/:remoteOrderId/status
POST /webhooks/delivery/yemeksepeti/:remoteId/order/:remoteOrderId/refund
PUT  /webhooks/delivery/yemeksepeti/:remoteId/order/:remoteOrderId/amend

POST /webhooks/delivery/trendyol/order/:remoteId
PUT  /webhooks/delivery/trendyol/:remoteId/order/:remoteOrderId/status
POST /webhooks/delivery/trendyol/:remoteId/order/:remoteOrderId/refund
PUT  /webhooks/delivery/trendyol/:remoteId/order/:remoteOrderId/amend

Menü / uygunluk / dükkân-durum senkronu (giden)

GET    /delivery-platforms/menu-mappings?platform=
POST   /delivery-platforms/menu-mappings           { productId, platform, externalItemId, externalData? }
DELETE /delivery-platforms/menu-mappings/:id
POST   /delivery-platforms/menu-sync/:platform                      (ADMIN)
POST   /delivery-platforms/configs/:platform/toggle-restaurant      { open: boolean }
POST   /delivery-platforms/configs/:platform/test                   (bağlantı testi)

• Menü eşleme: her ürün, platformdaki karşılığına (externalItemId) bağlanır. Menü senkronu yalnızca eşlenmiş ürünleri gönderir; ad, fiyat (₺) ve uygunluk (isAvailable && isActive) yazılır.
• Uygunluk: tek bir kalem updateItemAvailability ile açılıp kapatılabilir.
• Dükkân aç/kapat: toggle-restaurant, restoranı yalnızca ilgili platform tarafında açık/kapalı işaretler — yoğunlukta yeni sipariş almayı durdurmak için (entegrasyonu kapatmadan).

Mutabakat (reconciliation)

DeliveryReconciliationService düşük frekanslı, salt-okunur bir drift taramasıdır. Hiçbir adaptör mutabakat raporu sunmadığından platform-tarafı sayımları karşılaştırılmaz; bunun yerine kendi durumumuzdan:

• Bayatlık: etkin bir yoklama yapılandırmasının lastOrderPollAt’i 1 saatten eskiyse (genelde devre kesici tripi veya token ölümü) işaretlenir; menü senkronu 7 günden eski ise bilgilendirme amaçlı işaretlenir.
• Sayım driftı: son 24 saatte ingest edilen teslimat siparişleri ve externalOrderId’si olmayanlar (platforma geri senkronlanamaz).

Bulgular loglanır ve tek bir delivery.reconciliation.v1 outbox özetine toplanır.

Sorun giderme

• Devre kesici / otomatik kapanma: bir yapılandırmada hata sayısı 10’a ulaşırsa entegrasyon otomatik devre dışı bırakılır (platformu ve log tablosunu spam’lemeyi durdurur). delivery.platform.auto_disabled.v1 olayı yayınlanır. Operatör nedeni (lastError) düzeltip yapılandırmayı elle yeniden etkinleştirmelidir. Kimlik bilgisini güncellemek hata sayacını sıfırlar.
• Ölü-mektup kuyruğu (DLQ): başarısız giden işlemler üstel geri çekilmeyle yeniden denenir (varsayılan 3 deneme, en fazla 1 saat). Denemeler tükenince satır DLQ terminal durumuna düşer (success:false AND nextRetryAt:null AND retryCount>=maxRetries). DLQ derinliği delivery_dlq_depth metriğiyle izlenir; satırlar operatör/superadmin tarafından yeniden kuyruğa alınabilir.
• restaurant not configured: webhook, etkin bir yapılandırmaya eşlenmeyen bir remoteId ile geldi — remoteRestaurantId’yi ve entegrasyonun açık olduğunu doğrulayın.
• PII maskeleme: gelen ham gövdelerdeki kişisel veriler (telefon/e-posta/adres/ad) hem logdan hem siparişin externalData blob’undan kalıcı saklama öncesi maskelenir.

İlgili sayfalar

• Operatör kurulumu: Online Sipariş
• Mutfak akışı: KDS (Mutfak Ekranı)
• Menü kurulumu: Menü Yönetimi