Entegrasyon Projelerinde Veri Haritası Neden İlk Adımdır?

Entegrasyon projeleri genellikle teknik bir soruyla başlar: "Bu iki sistemi bağlayabilir miyiz?" Cevap çoğu zaman evettir. Asıl sorun bağlantının kurulup kurulamayacağı değil, bağlandıktan sonra hangi verinin doğru kabul edileceğidir.

Bu netleşmeden kurulan entegrasyonlar çalışır görünür, sonra sessizce yanlış veri üretmeye başlar.

Veri haritası nedir?

Veri haritası, her veri alanı için üç soruyu cevaplayan bir tablodur:

1. Bu bilgi nerede üretiliyor?
2. Nerelerde kullanılıyor?
3. İki yerde farklıysa hangisi doğru kabul edilecek?

Üçüncü soru en kritik olanıdır ve en sık atlananıdır.

"Doğru kaynak" kavramı

Bir ürünün fiyatı hem e-ticaret sitesinde hem ERP'de tutuluyor olabilir. Site üzerinden bir kampanya fiyatı girildi, ERP'de eski fiyat duruyor. Senkronizasyon çalıştığında ne olmalı?

Cevap teknik değil, ticari bir karardır:

• Fiyatın tek doğru kaynağı ERP ise, sitedeki kampanya fiyatı ezilir. O hâlde kampanya da ERP'den yönetilmelidir.
• Site kampanya fiyatlarını kendi yönetecekse, senkronizasyon fiyat alanını dışarıda bırakmalıdır.

Her alan için bu kararın verilmiş olması gerekir. "Sonra bakarız" denen her alan, ilk yoğun günde sorun çıkarır.

Alan eşleştirmesi göründüğünden zordur

İki sistemde aynı adı taşıyan alanlar aynı şeyi ifade etmeyebilir.

• Bir sistemde "stok" satılabilir adedi, diğerinde depodaki fiziksel adedi gösteriyor olabilir. Rezerve edilmiş ürünler farkı yaratır.
• Bir sistemde fiyat KDV dahil, diğerinde hariç tutuluyor olabilir.
• Tarih alanları farklı zaman dilimlerinde saklanıyor olabilir.
• Bir sistemde zorunlu olan bir alan, diğerinde boş bırakılabiliyor olabilir.

Eşleştirme tablosunu yaparken alan adına değil, alanın içeriğine bakın. Gerçek kayıt örnekleri üzerinden kontrol edin.

Yön ve sıklık kararı

Her alan için akış yönünü belirleyin:

• Tek yönlü: ERP → site. Basit ve öngörülebilir; çakışma riski yoktur.
• Çift yönlü: site ↔ ERP. Güçlüdür ama çakışma kurallarını gerektirir.

Sıklık de ayrı bir karardır. Her şeyi anlık senkronize etmek cazip görünür ama karşı sistemin hız sınırlarını zorlar ve gereksiz yük üretir.

Pratik bir ayrım:

• Anlık (olay tabanlı): stok, sipariş durumu, ödeme onayı gibi kritik alanlar
• Sık (dakikalık): fiyat güncellemeleri
• Planlı (günlük): ürün açıklamaları, kategori yapısı, raporlama verisi

Hata durumunda ne olacak?

Entegrasyonun en önemli özelliği, her şey yolundayken nasıl çalıştığı değil, bir şey ters gittiğinde ne yaptığıdır.

Baştan tanımlanması gerekenler:

• Yeniden deneme politikası. Karşı sistem yanıt vermezse kaç kez, hangi aralıklarla denenecek? Artan aralıklı yeniden deneme, karşı sistemi daha da zorlamamak için önemlidir.
• Tekillik kontrolü. Aynı sipariş iki kez gönderilirse ikinci istek yeni kayıt oluşturmamalı. Bunun için her işlemin benzersiz bir kimliği olmalı.
• Kuyruk. Başarısız aktarımlar kaybolmamalı; kuyrukta beklemeli ve sistem düzelince işlenmeli.
• Bildirim. Bir aktarım kalıcı olarak başarısız olduğunda kimin haberi olacak? Sessizce loglara yazılan hata, hata değil zaman bombasıdır.
• İzlenebilirlik. Hangi kaydın ne zaman, hangi yöne aktarıldığı sonradan sorgulanabilmeli.

Test ortamı olmadan başlamayın

Entegrasyon çalışması her zaman test ortamında başlar. Canlı veriye ilk yazma işlemi, sınırlı bir kayıt setiyle ve geri alınabilir biçimde yapılır.

Kademeli geçiş planı şöyle işler:

1. Yalnızca okuma — veriler doğru geliyor mu?
2. Sınırlı yazma — tek bir kategori veya birkaç kayıt üzerinde
3. Tam kapsam — doğrulama tamamlandıktan sonra
4. İzleme dönemi — ilk haftalarda günlük kontrol

Kimlik bilgileri ve güvenlik

Entegrasyon anahtarları kod içine yazılmaz. Ortam değişkenlerinde tutulur, sürüm kontrolüne girmez ve düzenli olarak yenilenir.

Ayrıca her entegrasyon için mümkün olan en dar yetki verilmelidir. Yalnızca ürün okuyacak bir bağlantının sipariş silme yetkisi olmamalıdır.

Devir: belge olmadan bitmiş sayılmaz

Entegrasyon tamamlandığında elinizde şunlar olmalı:

• Alan eşleştirme tablosu
• Yön ve sıklık kararlarının listesi
• Hata yönetimi kuralları
• Aktarım kayıtlarına nasıl bakılacağının anlatımı
• Anahtarların nerede saklandığı ve nasıl yenileneceği

Bu belge olmadan entegrasyon, onu yazan kişiye bağımlı bir kara kutudur. Belgeyle birlikte ise devredilebilir bir sistemdir.

Sonuç

Entegrasyon projelerinde harcanan zamanın büyük kısmı kod yazmakla değil, karar vermekle geçer — ve bu doğrudur. Kod, verilmiş kararların uygulanmasıdır. Kararlar netse uygulama hızlıdır; net değilse kod yazılır, sonra silinir, sonra yeniden yazılır.

Bu yüzden bir entegrasyon çalışmasına "hangi API'yi kullanacağız" sorusuyla değil, "hangi veri nerede doğru kabul edilecek" sorusuyla başlıyoruz.