Çoklu Pazaryeri Entegrasyonunda Tek Sipariş Modeli Nasıl Kurulur?

Çoklu Pazaryeri Entegrasyonunda Tek Sipariş Modeli Nasıl Kurulur?

Bir restoran yazılımına ikinci pazaryeri entegrasyonunu eklediğiniz gün, ilk entegrasyonun mimarisinin yanlış olduğunu anlarsınız. Üçüncüsünde ise kodun büyük bölümünü yeniden yazarsınız.

Bunun sebebi API'lerin zor olması değildir. Sebep, çoğu entegrasyonun ilk pazaryerinin veri modelini çekirdek model sanarak başlamasıdır. Bu yazıda, farklı pazaryerlerinin birbirine benzemeyen sipariş şemalarını tek bir kanonik modelde birleştiren mimariyi anlatıyoruz.

Hedef okuyucu, kendi restoran yazılımına veya POS ürününe pazaryeri entegrasyonu ekleyen yazılım firmalarıdır. Yazı belirli bir pazaryerinin API dokümantasyonunu anlatmaz; o dokümanlar değişir. Anlattığımız şey, hangi pazaryeri olursa olsun karşınıza çıkacak problem sınıfları ve bunların mimari karşılıklarıdır.

Problem: her pazaryeri kendi dünyasını dayatır

Yemek pazaryerleri birbirinden bağımsız ürünler olarak geliştiği için sipariş kavramını farklı modellemiştir. Entegrasyon yazarken karşınıza çıkan farklılıklar genellikle şu başlıklarda toplanır:

• Sipariş kimliği. Kimi platform tek bir kimlik verir, kimi platform müşteriye gösterilen kısa kod ile sistem kimliğini ayırır. İkisini karıştırmak, destek ekibinin siparişi bulamamasına yol açar.
• Durum akışı. Bir platformda "hazırlanıyor" diye tek bir durum varken, diğerinde "onaylandı", "mutfakta" ve "pakete hazır" diye üç ayrı durum olabilir. Durum sayıları farklı olduğu gibi, geçiş kuralları da farklıdır.
• Teslimat sorumluluğu. Bazı siparişlerde kuryeyi platform sağlar, bazılarında işletme kendi kuryesiyle teslim eder. Bu ikisi aynı veri yapısında temsil edilirse, kurye ataması gereken siparişle gerekmeyeni ayırt edemezsiniz.
• Ürün ve seçenek yapısı. Bir platform ürün üzerindeki ek malzemeyi ayrı bir satır olarak gönderirken, diğeri ürünün alt nesnesi olarak gönderebilir. Fiyatın hangi satıra yazıldığı da değişir.
• Tutar kırılımı. Ara toplam, indirim, teslimat ücreti, servis bedeli ve komisyonun hangi alanlarda ve hangi işaretle geldiği platformdan platforma değişir.
• İptal ve iade. Siparişin ne zaman, kim tarafından ve hangi aşamaya kadar iptal edilebileceği her platformda farklı kurala bağlıdır.

Bu farklılıkları tek tek koşul bloklarıyla yönetmeye çalışan bir kod tabanı, dördüncü entegrasyonda bakılamaz hale gelir. Çözüm, farklılıkları çekirdeğe sokmamaktır.

Kanonik sipariş modeli nedir?

Kanonik sipariş modeli, uygulamanızın içinde siparişin tek ve değişmez temsilidir. Pazaryerlerinin şemalarından bağımsızdır ve yalnızca sizin iş kurallarınızın ihtiyaç duyduğu alanları içerir.

Kuralı tek cümleyle şöyle koyabilirsiniz: çekirdek kod hiçbir zaman hangi pazaryerinden geldiğini bilmek zorunda kalmamalıdır. Çekirdek kodda "eğer Yemeksepeti ise" gibi bir koşul görüyorsanız, o mantık yanlış katmandadır.

Kanonik model şu soruları cevaplayacak kadar zengin, pazaryerlerinin tüm alanlarını taşıyacak kadar şişkin olmayacak şekilde tasarlanmalıdır:

• Bu sipariş hangi şubeye ait?
• Hangi ürünler, hangi miktarda, hangi seçeneklerle sipariş edilmiş?
• Teslimatı kim yapacak?
• Hangi tutar işletmeye kalacak?
• Sipariş şu an hangi aşamada ve bir sonraki geçerli aşama ne?

Katman mimarisi: adaptör, çevirici, çekirdek

Çalışan entegrasyonların neredeyse tamamı üç katmana ayrılır.

Adaptör katmanı. Her pazaryeri için ayrı bir adaptör yazılır. Bu katmanın tek işi, o platformun protokolüyle konuşmaktır: kimlik doğrulama, imza doğrulama, yeniden deneme, hız sınırı yönetimi ve ham yükün alınması. Adaptör iş mantığı içermez.

Çevirici katmanı. Ham yükü kanonik modele dönüştürür ve kanonik komutları o platformun beklediği biçime geri çevirir. İş kurallarının değil, eşleştirmenin yeridir. Her platform için iki yönlü bir çevirici bulunur.

Çekirdek. Yalnızca kanonik modeli tanır. Sipariş akışı, kurye ataması, stok düşümü, fiş yazdırma ve raporlama burada yaşar.

Bu ayrımın pratik faydası şudur: yeni bir pazaryeri eklemek, bir adaptör ve bir çevirici yazmak demektir. Çekirdeğe dokunulmaz. Dokunmak zorunda kalıyorsanız, kanonik modeliniz eksik demektir.

Ham yükü mutlaka saklayın. Çevirici bir alanı yanlış yorumladığında, ham yük olmadan geriye dönüp düzeltemezsiniz.

Kanonik sipariş şemasında bulunması gereken alanlar

Aşağıdaki iskelet, yemek ve market siparişlerinin ortak paydasını temsil eder. Alan adları size aittir; önemli olan ayrımların kendisidir.

{
  "siparis_id": "kendi urettiginiz kimlik",
  "kanal": {
    "ad": "pazaryeri_kodu",
    "harici_id": "platformun sistem kimligi",
    "gorunen_kod": "musteriye gosterilen kisa kod"
  },
  "sube_id": "kendi sube kimliginiz",
  "olusturma_zamani": "2026-10-13T14:32:00+03:00",
  "teslimat": {
    "tur": "kurye | gel_al | masada",
    "sorumlu": "platform | isletme",
    "talep_edilen_zaman": null,
    "adres": { "metin": "", "konum": null }
  },
  "kalemler": [
    {
      "kalem_id": "satir kimligi",
      "harici_urun_kodu": "platformdaki urun kodu",
      "eslesen_urun_id": "kendi urun kimliginiz veya null",
      "ad": "urun adi",
      "adet": 1,
      "birim_fiyat": 0,
      "secenekler": [
        { "harici_kod": "", "ad": "", "adet": 1, "birim_fiyat": 0 }
      ],
      "not": ""
    }
  ],
  "tutarlar": {
    "ara_toplam": 0,
    "indirim": 0,
    "teslimat_ucreti": 0,
    "servis_bedeli": 0,
    "genel_toplam": 0,
    "isletmeye_kalan": null,
    "para_birimi": "TRY"
  },
  "odeme": {
    "yontem": "online | kapida_nakit | kapida_kart",
    "tahsil_eden": "platform | isletme"
  },
  "durum": "ALINDI",
  "ham_yuk_referansi": "arsiv kaydinin kimligi"
}

Birkaç tasarım kararının gerekçesini açalım.

eslesen_urun_id ayrı bir alan olmalıdır ve boş olabilmelidir. Platformdaki ürün kodu ile sizin ürün kimliğiniz farklı şeylerdir. Eşleştirme kurulmadığında sipariş reddedilmemeli, eşleşmemiş olarak işaretlenip operasyona bildirilmelidir.

teslimat.sorumlu alanı zorunludur. Kuryeyi platformun sağladığı siparişle işletmenin sağladığı sipariş, aynı tabloda ama farklı davranışla yaşamalıdır. Bu ayrımı sonradan eklemek, kurye atama mantığının tamamını etkiler.

odeme.tahsil_eden alanı mutabakatın temelidir. Parayı platformun mu işletmenin mi tahsil ettiği, gün sonu kasa mutabakatını belirler. Bu alan yoksa, mutabakat her ay elle yapılır.

isletmeye_kalan alanı boş bırakılabilir olmalıdır. Her platform bu bilgiyi sipariş anında vermez. Hesaplanamıyorsa tahmin üretmek yerine boş bırakın; yanlış bir net tutar, boş bir alandan daha zararlıdır.

Durum makinesi: işin en zor kısmı

Mimarinin en çok hata üreten yeri durum eşleştirmesidir.

Doğru yaklaşım, kendi kanonik durum kümenizi mümkün olduğunca küçük tutmak ve her platformun durumlarını bu kümeye eşlemektir. Örnek bir kanonik küme:

ALINDI -> ONAYLANDI -> HAZIRLANIYOR -> HAZIR -> YOLDA -> TESLIM_EDILDI
       \-> REDDEDILDI
                                      \-> IPTAL_EDILDI

Eşleştirme tablosu her platform için ayrı tutulur ve çevirici katmanında yaşar.

Durum sorunu	Yanlış çözüm	Doğru çözüm
Platformda sizdeki duruma karşılık yok	Duruma yeni bir kanonik değer eklemek	En yakın kanonik duruma eşlemek, ham durumu ayrı alanda saklamak
Platform durum atlayarak geliyor	Ara durumları uydurmak	Atlanan geçişi geçerli kabul etmek, geçiş kurallarını buna göre yazmak
Geriye dönük durum bildirimi geliyor	Son geleni yazmak	Zaman damgasına bakıp eski bildirimi yok saymak
İki durum aynı anda geliyor	Sırayla işlemek	Sıra numarası veya zaman damgasıyla sıralamak

Son iki satır kritiktir. Bildirimler sırasız gelebilir. Durum alanını körü körüne güncelleyen bir kod, teslim edilmiş bir siparişi "hazırlanıyor" durumuna geri düşürür. Her durum güncellemesini, taşıdığı zaman damgası kayıttaki son damgadan yeniyse uygulayın.

Sipariş karışıklıklarının operasyon tarafındaki sonuçlarını Sipariş Karışıklıklarını Önlemenin En Etkili Yolu Nedir? yazımızda ele almıştık; burada anlattığımız durum makinesi, o sorunun kod tarafındaki karşılığıdır.

Kimlik eşleştirme: şube, ürün, seçenek

Entegrasyonun görünmeyen ama en çok destek talebi üreten tarafı budur.

Üç ayrı eşleştirme tablosuna ihtiyacınız vardır:

• Şube eşleştirmesi. Platformdaki mağaza kimliği ile sizin şube kimliğiniz. Çoklu şubeli işletmelerde bu tablo olmadan sipariş yanlış şubeye düşer.
• Ürün eşleştirmesi. Platformdaki ürün kodu ile sizin ürün kimliğiniz. Menü platformda güncellendiğinde bu tablo eskir.
• Seçenek eşleştirmesi. Ek malzeme, porsiyon boyu ve benzeri seçenekler. En çok ihmal edilen tablodur ve stok düşümünü doğrudan etkiler.

Eşleştirme tablolarını otomatik kurmaya çalışmayın. İsim benzerliğine göre eşleştirme yapan kod, "Tavuk Döner" ile "Tavuk Döner Porsiyon" ürünlerini birbirine karıştırır ve bu hata aylarca fark edilmez. Doğru yaklaşım, otomatik öneri üretip onayı kullanıcıya bırakmaktır.

Eşleşmemiş ürün geldiğinde siparişi reddetmeyin. Sipariş kabul edilsin, kalem eşleşmemiş olarak işaretlensin ve panelde uyarı çıksın. Reddedilen sipariş işletmenin cirosudur; eşleşmemiş kalem ise yalnızca bir veri eksiğidir.

Idempotency: aynı siparişi iki kez yazmamak

Pazaryerleri bildirimleri tekrar gönderebilir. Yanıtınız geç dönerse, ağ koparsa veya platform tarafında yeniden deneme tetiklenirse aynı sipariş birden çok kez gelir.

Çözüm basittir ve pazarlık kabul etmez: her gelen bildirim için bir idempotency anahtarı üretin ve bu anahtarı benzersiz indeksle saklayın. Anahtar, kanal kodu ile platformun sipariş kimliğinin birleşimi olabilir; durum bildirimleri için buna durum ve zaman damgası eklenir.

İkinci kez gelen bildirimde işlem yapmayın ve başarı yanıtı dönün. Hata dönerseniz platform yeniden denemeye devam eder.

Aynı disiplin giden istekler için de geçerlidir. Durum güncellemesi gönderirken bağlantı koparsa, isteğin karşı tarafa ulaşıp ulaşmadığını bilemezsiniz. Bu yüzden gönderim kayıtlarını da tekil tutun.

Zaman, para ve yuvarlama

Üç küçük konu, canlıda büyük sorun çıkarır.

Zaman. Tüm zamanları saat dilimi bilgisiyle birlikte saklayın ve karşılaştırmaları tek bir referans üzerinden yapın. Platformların bir kısmı yerel saat, bir kısmı UTC gönderir. Saat dilimi taşımayan bir zaman alanı, gün sonu raporunu bozar.

Para. Tutarları ondalık sayı olarak değil, en küçük birim cinsinden tam sayı olarak saklayın. Kayan noktalı sayılarla yapılan toplama, binlerce siparişte kuruş farkları üretir ve mutabakat tutmaz.

Yuvarlama. İndirim ve komisyon hesaplarında yuvarlamanın hangi aşamada yapıldığını sabitleyin. Platformun gönderdiği genel toplam ile sizin hesapladığınız toplam uyuşmuyorsa, sipariş anında platformun gönderdiği değeri esas alın ve farkı ayrı bir alanda kaydedin. Kendi hesabınızı doğru sayıp platformunkini ezmek, mutabakatı imkânsız hale getirir.

Yeni pazaryeri eklerken kırılmayan yapı

Mimarinizin sağlamlığını ölçmenin tek pratik yolu vardır: yeni bir pazaryeri eklerken kaç dosyaya dokunduğunuzu sayın.

Sağlıklı bir yapıda dokunulan yerler şunlardır: yeni adaptör, yeni çevirici, yeni durum eşleştirme tablosu ve yapılandırma kaydı. Çekirdek, veri tabanı şeması ve kullanıcı arayüzü değişmez.

Şu belirtilerden biri varsa mimari borcunuz birikiyordur:

• Çekirdek kodda pazaryeri adı geçen koşul blokları var.
• Veri tabanı şemasına platforma özgü sütunlar eklenmiş.
• Her yeni entegrasyonda rapor sorguları yeniden yazılıyor.
• Bir platformun API değişikliği, diğer platformların siparişlerini etkiliyor.

Son madde en tehlikelisidir ve genellikle ortak bir yardımcı fonksiyonun platforma özgü varsayım taşımasından kaynaklanır.

Entegrasyonu canlıya almadan önce kontrol listesi

• Aynı bildirim iki kez geldiğinde tek sipariş oluşuyor mu?
• Durum bildirimleri ters sırada geldiğinde kayıt geriye düşüyor mu?
• Eşleşmemiş ürün geldiğinde sipariş kabul ediliyor mu?
• Platform kuryeli ve işletme kuryeli siparişler farklı akıyor mu?
• Tutar kırılımı platformun gönderdiği genel toplamla tutuyor mu, tutmadığında fark kaydediliyor mu?
• İptal akışı her aşamadan tetiklenebiliyor mu?
• Ham yük arşivleniyor ve sipariş kaydından erişilebiliyor mu?
• Hız sınırına takıldığınızda kuyruk devreye giriyor mu?
• Çoklu şubede sipariş doğru şubeye düşüyor mu?
• Bağlantı koptuğunda kaçırılan siparişler telafi mekanizmasıyla alınıyor mu?

Son madde çoğu entegrasyonda eksiktir. Yalnızca anlık bildirime dayanan bir sistem, bildirim kaybolduğunda siparişi hiç görmez. Periyodik bir karşılaştırma işi, son saatlerin siparişlerini platformdan çekip sizde olmayanları tamamlamalıdır.

Bu mimari neden artık zorunlu?

Tek pazaryerine bağlı bir entegrasyon, birkaç yıl öncesine kadar yeterliydi. Pazar yapısı bunu değiştirdi.

Ticaret Bakanlığı'nın Türkiye'de E-Ticaretin Görünümü Raporu 2025 çalışmasına göre Türkiye'de e-ticaret faaliyetinde bulunan işletme sayısı 634.611'dir ve bu işletmelerin sektörlere göre dağılımında %20,3 ile yemek sektörü ilk sırada yer almaktadır. Aynı rapor, hızlı ticaret hacminin 388,7 milyar TL'ye ulaştığını ve yıllık %55,6 büyüdüğünü, bu hacmin %69,5'inin yemek sektöründen geldiğini ortaya koymaktadır.

Yazılım firması açısından bunun anlamı nettir: müşteriniz olan restoran tek kanaldan satmıyor. Birden çok pazaryerinde, kendi telefon siparişinde ve salonda aynı anda çalışıyor. Bu kanalların hepsini tek sipariş modeline indirgemeyen bir yazılım, müşterisine tek panel vaadini yerine getiremez.

Pazarın büyüklüğünü ve kırılımını Hızlı Ticaret Nedir? Ticaret Bakanlığı Verileriyle Paket Servis ve Kurye Pazarı yazımızda ayrıntılı inceledik. Aynı sorunun işletme tarafındaki görünümünü ise Yemeksepeti, Trendyol, Migros ve Getir Siparişlerini Tek Ekrandan Yönetmek Mümkün mü? yazımızda ele aldık.

Kendiniz yazmak ile hazır altyapı kullanmak

Bu yazıdaki mimariyi kurmak mümkündür ve birçok firma kurar. Kararı verirken bakılması gereken şey ilk geliştirme süresi değil, bakım yüküdür.

Kendiniz yazdığınızda şunlar sizin sorumluluğunuzda kalır: her platformun API değişikliklerini takip etmek, yeni platform eklendiğinde geliştirme yapmak, kesintilerde nöbet tutmak ve mutabakat farklarını ayıklamak. Bu yük, entegrasyon sayısıyla doğrusal değil, kabaca çarpan etkisiyle artar.

Paketiniz Entegre, bu katmanı hazır sunan bir altyapıdır. Ürün sayfasındaki tanıma göre webhook, REST API ve olay tabanlı yapılarla veri aktarımı sağlar, POS ve adisyon sistemleriyle entegre çalışır ve kullandığın kadar öde modeliyle sunulur. Ayrıntılar için Paketiniz Entegre ve Pazaryeri Entegrasyonları sayfalarına bakabilirsiniz.

Dürüst olmak gerekirse kendi entegrasyonunu yazmanın mantıklı olduğu durumlar da vardır. Tek bir pazaryeriyle çalışıyorsanız, iş modeliniz entegrasyon derinliğine bağlıysa veya ekibinizde bu yükü taşıyacak kapasite varsa kendi katmanınızı kurmak doğru karar olabilir. Karar, entegrasyonun ürününüzün farklılaştığı yer olup olmadığına bağlıdır.

Sık Sorulan Sorular

Kanonik sipariş modeli ile pazaryerinin modelini neden ayırmak gerekir?

Çünkü pazaryerinin modeli sizin kontrolünüzde değildir ve haber verilmeden değişebilir. Çekirdek kodunuz doğrudan o modele bağlıysa, dışarıdaki her değişiklik iç mantığınızı kırar. Kanonik model, bu değişikliklerin etkisini çevirici katmanında hapseder.

Kaç tane kanonik durum tanımlamalıyım?

Mümkün olan en az sayıda. Her platformun her durumunu temsil etmeye çalışırsanız, durum kümesi platform sayısıyla birlikte büyür ve iş mantığı yönetilemez hale gelir. Platformun ham durumunu ayrı bir alanda saklayıp kanonik kümeyi küçük tutmak daha sağlıklıdır.

Webhook mu kullanmalıyım, periyodik sorgulama mı?

İkisini birlikte kullanmalısınız. Webhook anlık akışı sağlar, periyodik sorgulama ise kaçan bildirimleri telafi eder. Yalnızca webhook'a dayanan bir sistem, bildirim kaybında siparişi hiç görmez.

Eşleşmemiş ürün geldiğinde siparişi reddetmeli miyim?

Hayır. Reddedilen sipariş işletmenin kaybettiği cirodur. Siparişi kabul edip kalemi eşleşmemiş olarak işaretlemek ve operasyona uyarı göstermek doğru davranıştır.

Tutarlar platformun gönderdiğiyle uyuşmuyorsa ne yapmalıyım?

Sipariş anında platformun gönderdiği genel toplamı esas alın, kendi hesabınızla arasındaki farkı ayrı bir alanda kaydedin ve eşiği aşan farkları raporlayın. Kendi hesabınızı doğru kabul edip platformunkini ezmek, mutabakatı imkânsız hale getirir.

Yeni bir pazaryeri eklemek ne kadar sürmeli?

Mimari doğru kurulduysa süre, o platformun dokümantasyon kalitesi ve test ortamı imkânlarıyla sınırlıdır; çekirdek kodunuzla değil. Yeni entegrasyon eklerken çekirdeğe dokunuyorsanız, süre tahmini yapmadan önce kanonik modelinizi gözden geçirin.

Şeffaflık notu

Bu yazı Paketiniz ekibi tarafından hazırlanmıştır ve kendi entegrasyon ürünümüz Paketiniz Entegre'den söz etmektedir. Yazıda belirli pazaryerlerinin API yapılarına ilişkin teknik ayrıntı verilmemiştir; anlatılan problem sınıfları ve mimari yaklaşım geneldir ve her platformun güncel dokümantasyonu esas alınmalıdır. Pazar verileri Ticaret Bakanlığı'nın kamuya açık raporundan alınmıştır. Yazı Ekim 2026 itibarıyla hazırlanmıştır.

Kaynaklar

• Ticaret Bakanlığı, Türkiye'de E-Ticaretin Görünümü Raporu 2025 (ETBİS) — etbis.ticaret.gov.tr
• Paketiniz Entegre ürün sayfası — paketiniz.com/entegre
• Pazaryeri Entegrasyonları — paketiniz.com/entegrasyonlar