API Geliştirme ve Sistem Entegrasyonu

Sistem entegrasyonu tam olarak neyi çözer?

Büyüyen her işletmede aynı tablo ortaya çıkar: web sitesi bir yerde, muhasebe programı başka yerde, depo takibi elektronik tabloda, kargo firmasının paneli ayrı bir sekmede durur. Aynı sipariş bilgisi gün içinde üç-dört yere elle girilir. Bu, hem zaman kaybıdır hem de hata kaynağıdır; bir rakamın yanlış yazılması gün sonunda hiç anlaşılmayan bir stok farkı olarak ortaya çıkar.

Entegrasyon, bu sistemler arasına veriyi otomatik taşıyan bir katman koymaktır. Sipariş sitede oluştuğunda muhasebeye fatura kaydı açılır, depoda stok düşer, kargo etiketi üretilir ve müşteriye takip bilgisi gider. İnsan yalnızca istisnalarla ilgilenir.

Entegrasyon nasıl planlanıyor?

İşin en kritik kısmı kod yazmak değil, veriyi doğru tanımlamaktır. Planlamada şu soruları sırayla cevaplıyoruz:

• Hangi sistem gerçeğin kaynağı? Ürün fiyatı hangi sistemde belirlenir, diğerleri onu mu takip eder? Bu soru netleşmeden çift yönlü eşitleme yazmak, iki sistemin birbirini sürekli ezmesiyle sonuçlanır.
• Akış tek yönlü mü, çift yönlü mü? Tek yönlü akışlar çok daha güvenlidir ve çoğu ihtiyacı karşılar. Çift yönlü eşitleme gerçekten gerekliyse çakışma kuralları yazılır.
• Ne sıklıkta eşitlenecek? Anlık mı, beş dakikada bir mi, gece toplu mu? Stok için anlık, muhasebe için günlük çoğunlukla yeterlidir. Gereksiz sıklık hem kaynak tüketir hem de hız sınırlarına takılır.
• Alanlar nasıl eşleşecek? Bir sistemde tek satır olan adres, diğerinde beş ayrı alandır. Para birimi, ondalık ayıracı, tarih formatı, vergi oranı ve birim farkları tablo hâlinde yazılır.

Bir soru daha var ki genellikle en sona bırakılıyor: kaydın benzersiz kimliği hangi alan üzerinden kurulacak. İki sistemde de aynı kaydı işaret eden güvenilir bir anahtar yoksa eşleştirme ad, telefon veya e-posta üzerinden tahminle yapılır ve bu yaklaşım hacim büyüdükçe hatalı birleştirmelere yol açar. Bu yüzden entegrasyonun ilk adımlarından biri, karşılıklı kimlik alanlarının belirlenmesi veya gerekiyorsa yeni bir eşleştirme tablosu kurulmasıdır.

Bu çalışmanın çıktısı alan eşleme tablosudur ve projenin sözleşmesi gibi işler. Sonraki tüm tartışmalar bu tabloya bakılarak çözülür.

Karşı sistemin API'si yoksa ne oluyor?

Sık karşılaşılan bir durum. Üç yol var. Birincisi, sistemin veritabanına doğrudan okuma erişimi almak; yazma işlemi yapmadığımız sürece güvenli ve hızlı bir çözümdür. İkincisi, sistemin dışa aktardığı dosyalar üzerinden çalışmak: belirli aralıklarla üretilen XML veya CSV dosyalarını izleyip işlemek. Üçüncüsü, üreticinin sunduğu ara modülü satın almak.

Dosya tabanlı entegrasyonlarda dikkat ettiğimiz noktalar: dosyanın tam yazıldığından emin olmadan işleme başlamamak, işlenen dosyayı arşive taşımak, aynı dosyanın iki kez işlenmesini engellemek ve bozuk satırları tüm aktarımı durdurmadan ayrı bir hata dosyasına almak. Bu ayrıntılar olmadan kurulan dosya entegrasyonları ilk aksaklıkta veri kaybıyla sonuçlanıyor.

Hata olursa ne oluyor?

Entegrasyonlarda soru "hata olur mu" değil, "hata olduğunda ne olacak"tır. Karşı sistem bakıma girer, ağ kopar, hız sınırı aşılır, beklenmeyen bir alan boş gelir. Tasarımımız bu durumları normal kabul eder.

Kurduğumuz yapı şu katmanlardan oluşuyor:

• Kuyruk: İşlemler doğrudan çalıştırılmaz, kuyruğa alınır. Böylece yoğunlukta istekler birikmez ve sırayla işlenir.
• Artan aralıklı yeniden deneme: Başarısız istek hemen değil, giderek uzayan aralıklarla tekrar denenir. Geçici kesintiler böylece kendiliğinden çözülür.
• Ölü mektup kuyruğu: Belirli sayıda denemeden sonra hâlâ başarısız olan kayıtlar silinmez, ayrı bir kuyruğa alınır ve elle incelenebilir.
• Tekrarlı işlem koruması: Her işleme benzersiz bir anahtar verilir; aynı kayıt iki kez gelirse ikinci istek yok sayılır. Ödeme ve sipariş akışlarında bu koruma zorunludur.
• Uyarı: Belirli eşiği aşan hata oranında ilgili kişilere e-posta veya anlık bildirim gider.

Ayrıca her akış için günlük özet raporu üretiyoruz: kaç kayıt aktarıldı, kaçı başarısız oldu, hangi nedenle. Bu rapor entegrasyonun sessizce bozulmasını engelliyor.

Kendi API'mizi de yayınlayabilir miyiz?

Evet. Bayilerinizin, iş ortaklarınızın veya kendi mobil uygulamanızın veriye erişmesi gerekiyorsa kendi API katmanınızı geliştiriyoruz. Bu tarafta uyguladığımız standartlar şunlar: kaynak odaklı REST yapısı, tutarlı HTTP durum kodları, sayfalama ve filtreleme, sürümleme, OAuth 2.0 veya kişisel erişim jetonuyla kimlik doğrulama, istemci bazlı hız sınırlaması ve her uç nokta için örnekli dokümantasyon.

Anlık bildirim gerektiren senaryolarda ise karşı tarafın sürekli sorgu yapması yerine olay tabanlı bildirim kuruyoruz. Bu bildirimlerde imza doğrulaması ve tekrar gönderim mekanizması standarttır; aksi hâlde bildirimlerin doğruluğu ve teslimi garanti edilemez.

Güvenlik ve kişisel veri tarafında nelere dikkat ediliyor?

Entegrasyonlar genellikle müşteri adı, telefon, adres gibi kişisel veri taşır. Bu nedenle KVKK yükümlülükleri doğrudan devreye girer. Uyguladığımız ilkeler: yalnızca gerekli alanların taşınması, aktarımın şifreli kanal üzerinden yapılması, API anahtarlarının kod içinde değil ortam değişkenlerinde saklanması, günlük kayıtlarında hassas alanların maskelenmesi ve saklama süresi dolan kayıtların otomatik silinmesi.

Yurt dışındaki bir servise veri aktarılıyorsa bunu keşif aşamasında açıkça belirtiyoruz; aktarımın hukuki dayanağı sizin veri envanterinizde tanımlanmalıdır. Teknik çözüm mevzuata uygunluğun yerine geçmez, ama hangi verinin nereye gittiğini şeffaf biçimde belgeleyebiliriz.

Ne kadar sürer, fiyat nasıl belirlenir?

Tek bir sistemle tek yönlü basit bir entegrasyon 2-3 haftada tamamlanabilir. Birden fazla sistemi kapsayan, çift yönlü çalışan ve yüksek hacimli akışlarda süre 8-10 haftaya çıkar. Fiyatı belirleyen unsurlar: bağlanacak sistem sayısı, karşı tarafın API kalitesi ve dokümantasyonu, veri hacmi, eşitleme sıklığı ve iş kurallarının karmaşıklığı.

Karşı tarafın dokümantasyonu zayıfsa süre uzuyor; çünkü davranışı deneyerek çıkarmak gerekiyor. Bu yüzden teklif aşamasında karşı sistemin test ortamına erişim istiyoruz. Erişim sağlanamıyorsa süreyi aralık olarak veriyor, gerekçesini yazıyoruz.

Veri hacmi büyüdüğünde entegrasyon ne oluyor?

Beş yüz kayıtla sorunsuz çalışan bir entegrasyon, iki yüz bin kayıtta tamamen farklı davranır. Bu yüzden mimariyi bugünkü hacme değil, öngörülen hacme göre kuruyoruz.

Büyük hacimde uyguladığımız yaklaşımlar şunlar:

• Artımlı eşitleme: Her çalışmada tüm katalog taranmaz; yalnızca son eşitlemeden bu yana değişen kayıtlar işlenir. Bunun için karşı sistemde değişiklik zaman damgası veya sürüm alanı bulunması gerekir; yoksa kendi tarafımızda özet değer karşılaştırması kuruyoruz.
• Toplu istek: Karşı sistem destekliyorsa kayıtlar tek tek değil paketler hâlinde gönderilir. Bu, hem hız sınırlarına takılmayı önler hem toplam süreyi kısaltır.
• Hız sınırı yönetimi: Her servisin dakikalık istek sınırı vardır. Sınıra yaklaşıldığında istekleri yavaşlatan, aşıldığında bekleyip tekrar deneyen bir denetleyici kuruyoruz.
• Öncelikli kuyruklar: Sipariş aktarımı ile katalog güncellemesi aynı kuyrukta beklememeli. Zaman kritik işlemler için ayrı ve öncelikli kuyruk tanımlanır.
• Gece penceresi: Ağır toplu işlemler trafiğin düşük olduğu saatlere planlanır ve süresi ölçülür. İşlem penceresi taşmaya başladığında bu, kapasite artırımı gerektiğinin ilk sinyalidir.

Ayrıca büyük hacimde veri tutarlılığını doğrulamak için düzenli mutabakat görevleri kuruyoruz: iki sistemdeki kayıt sayıları ve kritik toplamlar karşılaştırılıyor, sapma varsa rapor üretiliyor. Sessizce kaybolan birkaç kaydı fark etmenin başka bir yolu yoktur ve fark edilmeyen sapmalar aylar sonra çözülmesi çok zor sorunlara dönüşür.