ERP ile Web Entegrasyonu: Senkron API, Webhook ve Kuyruk Desenleri

ERP ile web sitesi arasındaki entegrasyon genellikle sipariş kaybolduğunda ya da tükenmiş bir ürün satıldığında gündeme gelir. Sahada gördüğümüz arızaların çoğu kodlama hatası değil, yanlış desen seçimidir: anlık olması gereken veri gece aktarılır, gece aktarılabilecek veri her sayfa açılışında ERP’ye sorulur. Stok, fiyat, sipariş ve cari bilgisi için senkron API, webhook, mesaj kuyruğu ve toplu aktarım arasında seçimi, her veri türü için gerekçesini yazabileceğiniz şekilde yapmak gerekir.

Deseni belirleyen dört veri özelliği

Tartışmaya “hangi teknolojiyi kullanalım” sorusuyla başlarsanız, ERP’nin sunduğu ilk arayüz her akışa uygulanır. Sonra o arayüzün zayıf yanı her akışta ayrı ayrı patlar. Bunun yerine her veri akışı için önce dört soruyu yanıtlayın:

• Tazelik gereksinimi: Veri web tarafında ne kadar eski olabilir? Ürün açıklamasında bir gün sorun değildir; son birkaç adedi kalmış stokta dakikalar bile fazla satış demektir.
• Değişim sıklığı ve hacmi: Fiyat listesi yılda birkaç kez topluca değişir; stok her sevkiyatta ve her satışta değişir. Sık ve küçük değişiklikle seyrek ve büyük değişiklik aynı desenle taşınmaz.
• Kayıp ve tekrar toleransı: Kaybolan sipariş kabul edilemez. Mutlak değer taşıyan bir stok güncellemesinin iki kez gelmesi ise zararsızdır.
• Yön ve sahiplik: Veri tek yönlü mü akıyor, iki sistem de aynı kaydı değiştirebiliyor mu? Çift yönlü akış, desen seçiminden önce bir sahiplik kuralı ister.

Bu yanıtlar desenin büyük kısmını belirler. İkinci filtre ERP’nin kendi kısıtlarıdır: API var mı, eşzamanlı oturum lisansı kaç kullanıcıya izin veriyor, bakım penceresi ne zaman. Lisans limiti çoğu projede geç fark edilir. Pahalıya patlar.

Senkron API çağrısı: nerede yeterli, nerede tehlikeli

Senkron desende web uygulaması kullanıcının isteğini işlerken ERP’nin API’sini doğrudan çağırır ve yanıtı bekler. B2B portalda bayi “sepete ekle” dediğinde, ona özel net fiyat o anda ERP’den sorgulanır. Veri her zaman günceldir, arada katman yoktur.

Bedeli, iki sistemin erişilebilirliğinin birbirine bağlanmasıdır. ERP gece bakımdaysa, yavaşsa ya da lisans limitine takıldıysa web sitesi de yavaşlar veya hata verir. Trafik arttığında yük doğrudan ERP’ye biner; kampanya günü muhasebe kullanıcılarının ekranı donar. Sahada en sık gördüğümüz tablo budur: sorun web’de görünür, kök neden ERP’nin oturum havuzudur. Senkron çağrı şu koşullarda makuldür:

• Sorgu düşük hacimliyse ve kimliği doğrulanmış kullanıcılarla sınırlıysa (bayiye özel fiyat, cari bakiye).
• Yanıt kısa süre önbelleğe alınabiliyorsa ve ERP erişilemezken anlamlı bir yedek davranış varsa (“fiyat teyidi için satış temsilcinizle iletişime geçin”).
• Zaman aşımı açıkça tanımlıysa. Web isteği ERP’yi sınırsız beklememeli.

Anonim ziyaretçilerin açtığı ürün listeleme sayfalarında her istekte ERP’ye gitmek neredeyse her zaman yanlıştır. Veri web tarafında bir kopyada tutulur ve aşağıdaki desenlerden biriyle güncellenir. Zaman aşımı ve yeniden deneme kurallarının ayrıntısı için API hata yönetimi, retry ve backoff rehberine bakın.

Webhook ile olay tabanlı aktarım

Webhook’ta kaynak sistem, bir değişiklik olduğunda hedef sistemin verdiği HTTP uç noktasına bildirim gönderir. Bazı ERP ve CRM’ler “sipariş oluşturuldu”, “stok değişti” gibi olaylar için webhook sunar; ödeme kuruluşları ve kargo firmaları durum değişikliklerini genellikle bu yolla iletir.

Webhook düşük gecikmeyi yoklama (polling) maliyeti olmadan verir. Ama üç sınırı vardır ve üçü de sahada karşınıza çıkar:

1. Teslim garantisi gönderene bağlıdır. Alıcı erişilemezken kaç kez ve ne kadar süre yeniden deneneceğini gönderen belirler. Süre dolarsa olay kaybolur.
2. Sıra garantisi yoktur. Aynı kayda ait iki olay ters sırada gelebilir.
3. Tekrar mümkündür. Gönderen, yanıtını alamadığı olayı yeniden gönderir; tekrarları alıcı ayıklamalıdır.

Bu yüzden webhook’u tek doğruluk kaynağı yapmayın. Kaçırılan olayları yakalayan periyodik bir mutabakat işiyle birlikte kurun. Alıcı uç noktanın imza doğrulama, tekrar eleme ve sıralama tarafı webhook alıcısı tasarımı rehberinde ayrıntılı olarak anlatılıyor.

Mesaj kuyruğu ile ara katman

Kuyruk deseninde web ve ERP birbirini doğrudan çağırmaz. Araya RabbitMQ, Azure Service Bus, Amazon SQS gibi bir mesaj aracısı ya da veritabanı tablosuyla kurulmuş basit bir iş kuyruğu girer. Web sitesi siparişi kendi veritabanına yazar ve kuyruğa bir mesaj bırakır; tüketici süreç mesajı alır, ERP’ye aktarır, başarılıysa mesajı onaylar.

Kazanç, iki sistemin zamanda ayrışmasıdır. ERP iki saat bakımda kalsa da web sipariş almaya devam eder; mesajlar birikir, ERP döndüğünde sırayla işlenir. Tüketici sayısı ERP’nin kaldırabileceği eşzamanlılığa göre ayarlanır ve ERP yük altında korunur (queue-based load leveling). Lisans limiti olan ERP’lerde bu ayar asıl koruma mekanizmasıdır.

Sık atlanan nokta şudur: veritabanına kayıt ile kuyruğa mesaj bırakma tek bir işlem (transaction) değildir. Sipariş kaydedilir, mesaj gönderilemez, sipariş ERP’ye hiç ulaşmaz. Kimse de fark etmez. Yaygın çözüm transactional outbox desenidir: mesaj, siparişle aynı veritabanı işleminde bir outbox tablosuna yazılır; ayrı bir süreç bu tabloyu okuyup aracıya iletir.

BEGIN;
INSERT INTO orders (id, customer_id, total, status)
  VALUES (10452, 'C-0193', 18450.00, 'received');
INSERT INTO outbox (aggregate_id, event_type, payload, created_at)
  VALUES (10452, 'order.created', '{"order_id":10452}', NOW());
COMMIT;
-- Ayrı bir yayıncı süreç: outbox'tan gönderilmemiş kayıtları okur,
-- aracıya iletir ve kaydı "sent" olarak işaretler.

Çoğu mesaj aracısı “en az bir kez” (at-least-once) teslim sağlar; tüketici aynı mesajı birden fazla alabilir. ERP tarafındaki kayıt işlemi, web sipariş numarası gibi bir dış referansla idempotent yapılmalıdır. Aynı referansla ikinci kez gelen sipariş yeni kayıt açmaz. Mükerrer faturaların sahadaki en yaygın nedeni bu kontrolün eksik olmasıdır.

Zamanlanmış toplu aktarım ve dosya tabanlı entegrasyon

Her veri gerçek zamanlı olmak zorunda değil. Ürün kartları, kategori ağacı, fiyat listeleri ve cari kartlar için gece ya da saatlik çalışan toplu aktarım (ETL) çoğu zaman en sağlam ve en kolay işletilen çözümdür. ERP’nin API’si yoksa ya da API lisansı sınırlıysa, CSV/XML dosyasının SFTP üzerinden bırakılması hâlâ geçerli bir yöntemdir. Eski yöntemdir. Ama çalışır.

Dosya tabanlı entegrasyonda kırılma noktaları bellidir:

• Atomik dosya teslimi: Dosya önce geçici adla (stok.csv.tmp) yazılır, tamamlanınca yeniden adlandırılır. Alıcı yarım dosyayı işlemez. Bu adım atlandığında tipik belirti, “rastgele” eksik ürünlerdir.
• Delta mı tam liste mi: Tam liste basittir ve kendini düzeltir. Delta hacmi düşürür, ama kaçırılan tek bir dosya kalıcı tutarsızlık yaratır. Delta kullanıyorsanız haftalık tam listeyle mutabakat yapın.
• Silinen kayıtlar: Delta dosyası silinen ürünleri taşımıyorsa web’de “hayalet” ürünler kalır. Pasifleştirme bilgisini açık bir alan olarak taşıyın.
• Karakter kodlaması ve ayırıcı: UTF-8, ondalık ve alan ayırıcısı sözleşmede yazılı olmalı. Türkçe karakterler ve virgüllü ondalıklar en sık kırılan yerdir; “1.250,00” bir tarafta bin iki yüz elli, diğer tarafta bir virgül iki beş olarak okunur.

Ana veri sahipliği ve çakışma çözümü

Çift yönlü senkronizasyonda en sık sorun, iki sistemin aynı alanı değiştirmesi ve son yazanın diğerini ezmesidir. Bunu desen çözmez. Sahiplik kuralı çözer: her veri alanı için tek bir “yazma yetkili” sistem tanımlanır, diğer sistem o alanı yalnızca okur.

Veri	Sahip sistem	Diğer sistemin rolü
Ürün kodu, birim, vergi	ERP	Web yalnız okur
Ürün açıklaması, görseller, SEO alanları	Web / PIM	ERP’ye aktarılmaz
Stok miktarı	ERP	Web rezervasyon tutabilir, miktarı değiştirmez
Sipariş (oluşturma)	Web	ERP’ye bir kez aktarılır
Sipariş durumu, fatura	ERP	Web’e geri bildirilir
Cari adres	Sözleşmeyle belirlenir	Değişiklik talebi akışı tanımlanır

Aynı kaydın farklı alanlarının farklı sahipleri olabilir; önemli olan kuralın alan düzeyinde yazılı olmasıdır. Cari adres gibi iki tarafta da değişebilen alanlarda “web’de değişiklik talebi oluştur, ERP’de onaylanınca geri senkronize et” yaklaşımı, son yazanın kazandığı (last-write-wins) modele göre çok daha az sürpriz üretir. Stok için ek bir uyarı: web tarafında “ERP stoku eksi açık siparişler” hesabı yapılıyorsa, açık sipariş ERP’ye aktarıldığı anda bu düşüm iki kez yapılmamalıdır. Bu hata stoku olduğundan düşük gösterir ve satılabilir ürün “tükendi” görünür.

Desen karşılaştırması ve karar sırası

Desen	Gecikme	Hata toleransı	Tipik kullanım
Senkron API	Anlık	Düşük; ERP kesintisi web’e yansır	Bayiye özel fiyat, bakiye sorgusu
Webhook	Saniyeler	Gönderenin yeniden deneme politikasına bağlı	Ödeme, kargo, sipariş durumu
Mesaj kuyruğu	Saniyeler–dakikalar	Yüksek; mesajlar birikir, kaybolmaz	Sipariş aktarımı, stok değişimi
Toplu aktarım / dosya	Dakikalar–saatler	Yüksek; tam liste kendini düzeltir	Ürün kartı, fiyat listesi, cari kart

Karar verirken şu sırayı izleyin:

1. Veri kaybı kabul edilemez mi (sipariş, tahsilat)? Evet ise kuyruk veya outbox tabanlı aktarım kullanın; senkron çağrıyı tek mekanizma yapmayın.
2. Veri dakikalar içinde güncel olmalı mı? Hayır ise toplu aktarım yeterlidir. Gereksiz gerçek zamanlılık işletme maliyetini artırır.
3. Kaynak sistem olay yayınlayabiliyor mu? Evet ise webhook veya aracı üzerinden olay alın, kaçırılanlar için periyodik mutabakat ekleyin. Hayır ise kısa aralıklı, “son değişiklik zamanı” filtresiyle çalışan yoklama kullanın.
4. Veri kullanıcıya özel ve anlık mı (net fiyat, kredi limiti)? Senkron çağrı uygundur; zaman aşımı, kısa önbellek ve yedek davranış tanımlayın.

Gerçek projelerde tek desen olmaz; veri türüne göre birkaçı birlikte çalışır: ürün kartları gece toplu, stok kuyruk üzerinden, siparişler outbox ile, sipariş durumu webhook ile, bayi fiyatı senkron sorguyla. Bu kadar akışın olduğu yerde hangisinin sessizce durduğunu görmek için ayrı bir izleme katmanı gerekir; bunu entegrasyon izleme ve mutabakat rehberinde anlatıyoruz. Desen seçimi ve uygulamasında destek gerekiyorsa ERP, CRM ve API entegrasyonları sayfamızdan kapsamı inceleyebilirsiniz; WooCommerce tarafındaki sipariş ve stok akışları için WooCommerce e-ticaret çözümleri sayfası da ilgili olabilir. Mesajlaşma, kuyruk ve idempotent alıcı gibi temel desenlerin genel tarifi Enterprise Integration Patterns kaynağında bulunur; transactional outbox bu kataloğun değil, sonraki mikroservis literatürünün bir desenidir.

Sık sorulan sorular

ERP ile web sitesi arasında stok kaç dakikada bir güncellenmeli?

Sabit bir doğru değer yok; stok devir hızına ve fazla satışın maliyetine bakılır. Az stoklu, hızlı dönen ürünlerde değişiklik olayı ya da kısa aralıklı kuyruk tabanlı aktarım gerekir. Bol stoklu ürünlerde saatlik toplu aktarım çoğu zaman yeter. Kabul edilebilir en eski stok bilgisini iş birimiyle birlikte yazılı olarak belirleyin; aralık o rakamdan çıkar.

ERP’nin API’si yoksa entegrasyon mümkün mü?

Evet. ERP’nin dışa aktarım özelliği veya zamanlanmış rapor çıktısıyla CSV ya da XML üretilir ve SFTP üzerinden taşınır. Sipariş yönünde ERP’nin içe aktarım şablonu kullanılır. Bu yöntemde atomik dosya teslimi, karakter kodlaması ve silinen kayıtların nasıl taşınacağı sözleşmede açıkça yazılmalıdır.

Çift yönlü senkronizasyonda çakışmalar nasıl önlenir?

Her alan için tek bir yazma yetkili sistem belirlenir; diğer sistem o alanı yalnızca okur. İki tarafta da değişmesi gereken alanlarda doğrudan yazma yerine değişiklik talebi ve onay akışı kurulur. Son yazanın kazandığı model ancak alan iş açısından önemsizse kabul edilebilir.

Webhook varsa ayrıca periyodik senkronizasyona gerek var mı?

Genellikle evet. Webhook teslimi gönderenin yeniden deneme politikasına bağlıdır; alıcı uzun süre erişilemezse olaylar kaybolur. Saatlik veya günlük bir mutabakat işi iki taraftaki kayıtları karşılaştırır, kaçırılan olayları yakalar ve tutarsızlığın kalıcı hâle gelmesini engeller.