Sipariş Event Yapısı (IntegrationOrderEvent)¶

Bu sayfa, MuditaKurye'nin iç sisteminde sipariş oluşturmak için kullandığı IntegrationOrderEvent veri modelini açıklar. Üçüncü taraf entegratörlerin gönderdiği sipariş payload'ı bu yapıya dönüştürülür.

Temel Alanlar¶

Alan	Tip	Zorunlu	Açıklama
`provider`	string	Evet	Entegrasyon sağlayıcısı. 3. parti için `THIRD_PARTY`
`providerOrderId`	string	Evet	Sizin sisteminizdeki sipariş ID'si
`providerRestaurantId`	string	Evet	MuditaKurye'den aldığınız restoran ID'si
`restaurantSecretKey`	string	Evet	API Key veya Basic Auth bilgileri
`orderNumber`	string	Hayır	Sipariş numarası (boş bırakılırsa `providerOrderId` kullanılır)
`confirmationCode`	string	Hayır	Onay kodu (varsa)

Aksiyon Alanları¶

Alan	Tip	Açıklama
`action`	string	İşlem türü: `NEW_ORDER` (varsayılan) veya `CANCEL`
`cancelReason`	string	İptal nedeni (action=CANCEL ise)
`cancelReasonCode`	string	İptal neden kodu (action=CANCEL ise)

İptal Akışı

action: "CANCEL" olarak gönderilen event'ler IntegrationOrderService.cancelFromEvent() metodu ile işlenir. Mevcut sipariş bulunur ve iptal edilir.

Müşteri Bilgileri¶

Alan	Tip	Açıklama
`customerName`	string	Müşteri adı soyadı
`customerPhone`	string	Müşteri telefonu (E.164 formatı önerilir)

Telefon Numarası Formatı

Telefon numaraları otomatik olarak +90XXXXXXXXXX formatına dönüştürülür. Getir/Getir Su hariç tüm sağlayıcılar için bu formatlama uygulanır.

Teslimat Bilgileri¶

Alan	Tip	Açıklama
`deliveryAddress`	string	Tam teslimat adresi
`deliveryLatitude`	BigDecimal	Teslimat noktası enlemi
`deliveryLongitude`	BigDecimal	Teslimat noktası boylamı
`deliveryType`	integer	Teslimat türü kodu
`isPickup`	boolean	Gel-al siparişi mi?
`pickupCode`	string	Gel-al kodu (varsa)
`isRestaurantDelivers`	boolean	Restoran kendi kurye ile mi teslim edecek?
`scheduled`	boolean	Zamanlanmış sipariş mi?
`scheduledDeliveryTime`	OffsetDateTime	Planlı teslimat zamanı (ISO-8601)

Otomatik Geocoding

Koordinat bilgisi (deliveryLatitude/deliveryLongitude) yoksa, sistem Google Geocoding API ile otomatik olarak adres→koordinat dönüşümü yapar. Restoran konumu bias olarak kullanılır. 50 km yarıçap sınırı uygulanır — daha uzak koordinatlar restoran yönünde 50 km'ye clamp edilir.

Ödeme Bilgileri¶

Alan	Tip	Açıklama
`paymentMethod`	string	Ödeme yöntemi (aşağıdaki tabloya bakın)
`paymentCaptured`	boolean	Ödeme alındı mı?

Ödeme Yöntemi Eşleşmesi¶

Gönderdiğiniz ödeme yöntemi otomatik olarak MuditaKurye standart tipine dönüştürülür:

Gönderilen	Dönüştürülen	Açıklama
`CASH`, `nakit`	`CASH`	Nakit ödeme
`ONLINE_PREPAID`, `online`	`ONLINE_PREPAID`	Online ön ödeme
`CARD_POS`, `kredi kart`, `credit card`	`CARD_POS`	Kapıda kredi kartı
`MEAL_CARD`, `yemek kartı`	`MEAL_CARD`	Yemek kartı

Eşleşme bulunamazsa, tenant bazlı PaymentTypeMapping tablosu kontrol edilir. Bulunamazsa orijinal değer korunur (max 30 karakter).

Fiyatlandırma¶

Alan	Tip	Açıklama
`total`	BigDecimal	Toplam tutar (KDV dahil nihai tutar)
`serviceFee`	BigDecimal	Hizmet bedeli
`discount`	BigDecimal	İndirim tutarı
`taxAmount`	BigDecimal	Vergi tutarı
`currency`	string	Para birimi (varsayılan: `TRY`)

Toplam Hesaplama Mantığı

total alanı gönderilirse grand total olarak kabul edilir ve item toplamı hesaplanmaz.
total gönderilmezse veya 0 ise, item bazlı toplam hesaplanır: subtotal = Σ(item.totalAmount), total = subtotal - discount + serviceFee
İndirimler çift sayımı önlemek için hem order-level hem item-level discount kontrolü yapılır.

Sipariş Kalemleri¶

Alan	Tip	Açıklama
`items`	List\<Item>	Sipariş kalem listesi

Item Yapısı¶

Alan	Tip	Açıklama
`productCode`	string	Ürün kodu
`productId`	UUID	Ürün ID (opsiyonel)
`productName`	string	Ürün adı
`quantity`	BigDecimal	Miktar
`unitPrice`	BigDecimal	Birim fiyat
`discountAmount`	BigDecimal	Kalem indirimi
`totalAmount`	BigDecimal	Kalem toplamı
`productNote`	string	Ürün notu (örn: "Az pişmiş")
`features`	string	Özellikler/modifikatörler (text)
`options`	List\<ItemOption>	Yapısal opsiyon listesi (detaylı)

ItemOption Yapısı (Nested)¶

Opsiyonlar ağaç yapısında (recursive) tanımlanabilir:

Alan	Tip	Açıklama
`optionId`	string	Opsiyon ID
`optionHeaderId`	string	Opsiyon başlık ID
`name`	string	Opsiyon adı
`headerName`	string	Opsiyon grup adı
`quantity`	BigDecimal	Miktar
`unitPrice`	BigDecimal	Birim fiyat
`totalPrice`	BigDecimal	Toplam fiyat
`type`	string	Tür: `OPTION`, `EXCLUDED`, `INGREDIENT`, `PRODUCT`
`excluded`	boolean	Hariç tutulan ingredient mi?
`subOptions`	List\<ItemOption>	Alt opsiyonlar (recursive nesting)

Options vs Features

options yapısal veri için kullanılır (JSON olarak serialize edilir)
features düz metin olarak kaydedilir
Her ikisi de gönderilirse options öncelik alır, JSON'a dönüştürülür ve features alanına yazılır.

Örnek: Opsiyonlu Sipariş Kalemi¶

{
  "items": [
    {
      "productCode": "PIZZA-001",
      "productName": "Margarita Pizza",
      "quantity": 1,
      "unitPrice": 65.00,
      "totalAmount": 75.00,
      "options": [
        {
          "optionId": "SIZE-L",
          "headerName": "Boyut",
          "name": "Büyük Boy",
          "unitPrice": 10.00,
          "totalPrice": 10.00,
          "type": "OPTION"
        },
        {
          "optionId": "EXTRA-CHEESE",
          "headerName": "Ekstralar",
          "name": "Ekstra Peynir",
          "unitPrice": 5.00,
          "totalPrice": 5.00,
          "type": "OPTION"
        },
        {
          "optionId": "NO-ONION",
          "headerName": "Çıkarılacaklar",
          "name": "Soğansız",
          "type": "EXCLUDED",
          "excluded": true
        }
      ]
    }
  ]
}

Özel Durumlar¶

Gel-Al (Pickup) Siparişleri¶

{
  "isPickup": true,
  "pickupCode": "A123",
  "deliveryAddress": null
}

Gel-al siparişlerinde: - Kurye ataması yapılmaz - Teslimat adresi otomatik olarak "Gel-Al" olarak ayarlanır - Pool sistemine eklenmez

Restoran Getirsin Siparişleri¶

{
  "isRestaurantDelivers": true
}

Bu flag aktif olduğunda: - MuditaKurye kurye ataması yapmaz - Restoran kendi kurye ağını kullanır

Zamanlanmış Siparişler¶

{
  "scheduled": true,
  "scheduledDeliveryTime": "2025-11-10T18:30:00+03:00"
}

Zamanlanmış siparişler: - NEW durumunda oluşturulur (otomatik onay yapılmaz) - Restoran tarafından manuel onay gerektirir - Otomatik VERIFY event'i gönderilmez

Sonraki Adım¶

Sipariş kalemleri ve opsiyonların detayları için Sipariş Kalemleri ve Opsiyonlar sayfasına bakın.