API Entegrasyonu Nedir? Sistemleri Birbirine Bağlamanın Kuralları

Bir işletmede nadiren tek bir yazılım vardır. Site ayrı, yönetim paneli ayrı, muhasebe ayrı, üretim yazılımı ayrı çalışır. Bu sistemler birbiriyle konuşmadığında aradaki boşluğu bir insan doldurur: aynı veri iki yere elle girilir, bir dosya indirilip diğerine yüklenir, akşamüstü biri iki listeyi karşılaştırır.

API entegrasyonu, bu elle taşıma işini ortadan kaldırmaktır. Ama sahada gördüğümüz şu: entegrasyon projelerinin zor kısmı bağlantıyı kurmak değil, bağlantı koptuğunda ne olacağına karar vermektir. İki sistemi birbirine bağlamak birkaç günlük iştir; onları üç yıl boyunca sessizce yanlış çalışmaktan korumak bir tasarım işidir.

Bu yazıda entegrasyonun üç yolunu, hangisinin ne zaman doğru olduğunu ve canlıya almadan önce cevaplanması gereken soruları anlatıyoruz. Yazının odağı ürün değil, kural.

API entegrasyonu nedir?

API (Application Programming Interface — Uygulama Programlama Arayüzü), bir yazılımın dışarıya açtığı kapıdır. İnsan için ekran, başka bir yazılım için API vardır. API entegrasyonu, iki sistemin bu kapı üzerinden veri alışverişi yapmasıdır: biri sorar, diğeri cevaplar.

Ama entegrasyon her zaman API üzerinden kurulmaz ve kurulması da gerekmez. Karşı taraf yalnızca bir rapor dosyası üretiyorsa, o dosyayı okumak da tam anlamıyla bir entegrasyondur. Yöntem ihtiyaca göre değişir; değişmeyen tek şey şudur: veri tek bir yerde doğru olmalı ve hata sessiz kalmamalıdır.

Entegrasyonun üç yolu — hangisi ne zaman doğru?

Pratikte üç yöntem vardır ve üçü de meşrudur. Yanlış olan, ihtiyaç olmadığı hâlde en karmaşığını seçmektir.

Gerçek zamanlı API çağrısı

Olay olduğu anda karşı sisteme gidilir. Stok kontrolü, fiyat sorgusu, ödeme onayı gibi cevabı beklenen işler için doğrudur. Bedeli şudur: karşı taraf yavaşladığında sizin ekranınız da yavaşlar, çöktüğünde sizin işiniz de durur — kuyrukla korunmadıysa.

Zamanlanmış toplu aktarım

Belirli aralıklarla (saatte bir, gecede bir) biriken kayıtlar topluca aktarılır. Sipariş aktarımı, muhasebe fişi gönderimi, rapor üretimi gibi birkaç saatlik gecikmenin sorun olmadığı işlerin çoğu buraya girer. Çok daha az kırılgandır ve bakımı ucuzdur.

Dosya tabanlı aktarım

Karşı sistem yalnızca Excel, CSV veya Word çıktısı üretiyorsa dosya okunur. "İlkel" görünür ama kapalı bir programa ekran kazıyarak bağlanmaktan çok daha sağlamdır. Ekran kazıma, karşı taraf arayüzünü değiştirdiği gün sessizce bozulur; bu yüzden önermiyoruz.

Entegrasyonun değişmeyen üç kuralı

Kural 1: Her verinin tek bir sahibi olur

Aynı bilgi iki sistemde birbirinden bağımsız düzenlenebiliyorsa, er ya da geç ikisi ayrışır ve "hangisi doğru?" sorusu ortaya çıkar. Bu sorunun cevabı entegrasyonla değil, sahiplik kararıyla verilir: bir veri için bir sistem sahip, diğerleri okuyucudur.

Çift yönlü akış kulağa daha güçlü gelir ama çakışma riski taşır: aynı kayıt iki tarafta aynı anda değiştiğinde hangisinin kazanacağını yazmak zorunda kalırsınız. Çoğu ihtiyaç için tek yönlü akış hem daha sağlam hem daha anlaşılırdır.

Kural 2: Aynı işlem iki kez işlenmemeli

Ağ üzerinde bir isteğin iki kez ulaşması olağandır: bağlantı koptuğunda gönderen taraf cevabı alamaz ve tekrar dener. Karşı taraf bunu ayırt edemezse ikinci bir kayıt açar. Sonuç, entegrasyon hatalarının klasik üçlüsüdür: çift stok düşümü, çift tahsilat kaydı, aynı kişiye iki kez giden e-posta.

Çözüm idempotency — Türkçesiyle tekrar-koruma: her işlem tekil bir anahtarla işaretlenir ve aynı anahtarla gelen ikinci istek yeni kayıt açmaz, mevcut kaydın sonucunu döndürür. Bu anahtar rastgele değil, kaynak sistemdeki kaydın kimliğinden türetilir. Küçük bir tasarım detayıdır ve entegrasyonun en pahalı hatasını baştan kapatır.

Kural 3: Bağlantı koparsa iş durmamalı, hata da sessiz kalmamalı

Entegrasyonların çoğu mutlu senaryoya göre yazılır ve ilk kesintide çöker. Doğru kurgu dört parçadan oluşur:

• Kuyruk: Gönderim doğrudan yapılmaz, kuyruğa alınır ve arka planda işlenir. Kullanıcı karşı tarafın hızına bağlı kalmaz, hata ekranı görmez.
• Yeniden deneme: Başarısız iş artan aralıklarla tekrar denenir. Geçici bir kesinti kendiliğinden kapanır.
• Durum kaydı: Her aktarım durumuyla saklanır — gönderildi, kuyrukta, başarısız. Hangi kayıt ne zaman, hangi sonuçla gitti sonradan görülebilir.
• Uyarı: Kalıcı hatada bildirim çıkar. Bir entegrasyonun en tehlikeli hâli çalışmaması değil, çalışmadığının fark edilmemesidir.

Veri eşleştirme: asıl iş burada

Entegrasyon projelerinde teknik bağlantı süresinin çoğu bağlantıyı kurmaya değil, iki sistemin aynı şeyden aynı şeyi anlamasını sağlamaya gider. Geliştirmeden önce alan alan bir veri sözlüğü çıkarılır. En sık çıkan farklar şunlar:

Kod farkı

Müşteri veya ürün, iki sistemde farklı kodla durur. Eşleştirme için sabit bir anahtar seçilir; ada göre eşleştirme er ya da geç yanlış kaydı bulur.

Birim farkı

Bir tarafta kilogram, diğerinde adet; bir tarafta metre, diğerinde milimetre. Çevrim kuralı yazılı olmalı ve tek yerde uygulanmalı.

Vergi ve para birimi

Tutarın vergi dâhil mi hariç mi olduğu, hangi para biriminde ve hangi günün kuruyla saklandığı açıkça belirlenir.

Format farkı

Tarih biçimi ve ondalık ayırıcı (virgül mü nokta mı) klasik sessiz hata kaynağıdır: veri gider, yanlış okunur, hata vermez.

Zorunluluk farkı

Bir tarafta boş bırakılabilen alan diğer tarafta zorunlu olabilir. Bu durumda kaydın reddedilmesi mi, varsayılanla geçmesi mi gerektiği önceden kararlaştırılır.

Bu sözlüğü teklif aşamasında yazılı hâle getirmek, entegrasyon projelerinde yapılabilecek en yüksek getirili iştir. Sözlük yoksa iş, karşılıklı varsayımlar üzerine kurulur ve ilk ay içinde yeniden yazılır.

Güvenlik: anahtar, yetki ve iz kaydı

Entegrasyon, sisteminize dışarıdan bir kapı açmak demektir. O kapının nasıl açıldığı en az ne aktardığı kadar önemlidir.

• Anahtar yönetimi: Erişim anahtarları kodun içine yazılmaz; ortam değişkenlerinde tutulur ve sürüm deposuna girmez. Değiştirilebilir olmaları gerekir — değiştirilemeyen bir anahtar, sızdığında sizi çaresiz bırakır.
• En az yetki: Entegrasyon kullanıcısına tam yetki verilmez. Yalnız ihtiyaç duyduğu alanları okuyup yazabilmeli; silme yetkisi neredeyse hiçbir zaman gerekmez.
• Alan sınırı: Yalnız o entegrasyonun gerektirdiği alanlar, yalnız o servise gider. Hangi alanın nereye gittiği veri sözlüğünde yazılıdır.
• Test ortamı: Mümkünse karşı tarafın test ortamında çalışılır; canlı veriyle deneme yapılmaz.
• İz kaydı: Hangi işlemin ne zaman, hangi kaynaktan geldiği kayıt altında tutulur. Bir tutarsızlık çıktığında cevabı verecek olan tek şey budur.

Sahadan örnek: dosyadan toplu iş girişi

Fason imalat atölyeleri için geliştirdiğimiz LazerCRM'de tipik bir "API'si olmayan karşı taraf" durumu var. Atölyede kullanılan üretim yazılımı, parça listesini Word veya Excel raporu olarak veriyor. Bu raporu elle sisteme geçirmek, bir teklifin en uzun adımıydı.

Çözüm bir API değil, dosya tabanlı bir entegrasyon oldu: rapor yüklendiğinde sistem satırları kendisi okuyup iş kalemlerini dolduruyor. Kritik olan, dosyanın nasıl okunduğu:

• Okuma sabit sütun sırasına bağlı değil; başlıklar eşanlamlı adlarıyla eşleştiriliyor, başlık bulunamazsa konumsal yedeğe düşülüyor.
• İş kuralları dosyadan gelen veriye de uygulanıyor. Kural yalnız ekranda değil sunucu tarafında da çalıştığı için toplu giriş onu atlayamıyor.
• Dosyadan gelen değer ile sonradan elle düzeltilen değer ayrı gösteriliyor; tek tıkla orijinaline dönülebiliyor.

Buradaki ayrım şudur: dosya okumak "üçüncü sütunu al" demek değildir. Karşı taraf çıktısını değiştirdiğinde sistemin sessizce yanlış veri girmemesi için eşleme esnek, doğrulama katı olmalıdır. Bu yaklaşımı API ve sistem entegrasyonları hizmetimizin temeline koyduk.

Canlıya almadan önce kontrol listesi

Aşağıdaki soruların hepsine "evet" diyemeden bir entegrasyon canlıya alınmamalıdır. Listeyi teklif aşamasında da kullanabilirsiniz; cevaplayamayan bir tedarikçi, o maddeyi düşünmemiş demektir.

Sık yapılan 4 hata

1. Karşı tarafın hep ayakta olduğunu varsaymak. Her dış servis bir gün cevap vermez; entegrasyon o güne göre tasarlanır.
2. Ekran kazımayı entegrasyon sanmak. Arayüzden veri toplayan bir bağlantı, karşı taraf bir düğmenin yerini değiştirdiğinde bozulur ve bozulduğunu söylemez.
3. Dış servisin çıktısını sorgusuz kabul etmek. Gelen veri doğrulanmadan içeri alınıyorsa, karşı sistemin hatası sizin verinize dönüşür.
4. İzlemeyi sonraya bırakmak. "Önce çalıştıralım, izlemeyi sonra ekleriz" denen projelerde izleme hiç eklenmez ve ilk arıza aylar sonra fark edilir.

Sıkça sorulan sorular

Bağlanacağımız programın API'si yok, ne yapabiliriz?

Dosya tabanlı aktarım kurulur: karşı sistem rapor veya dışa aktarım üretiyorsa o okunur. Ekran kazımayı önermiyoruz, çünkü karşı taraf arayüzünü değiştirdiği gün sessizce bozulur ve bozulduğu fark edilmez.

Aktarım anlık mı olmalı?

İhtiyaca bakılır. Stok ve fiyat gibi cevabı beklenen alanlarda anlık aktarım mantıklıdır; sipariş ve rapor aktarımında zamanlanmış bir akış hem yeterli hem daha az kırılgandır. Anlık aktarım kurulum ve bakım maliyetini artırır.

Entegrasyon bozulursa haberimiz olur mu?

Doğru kurulduysa evet. Her aktarım durumuyla kaydedilir ve kalıcı hatalarda bildirim gider. Bu bir ek özellik değil, entegrasyonun asgari şartıdır.

Verilerimiz üçüncü tarafa gider mi?

Yalnız o entegrasyonun gerektirdiği alanlar, yalnız o servise gider. Hangi alanın nereye gittiği veri sözlüğünde yazılıdır ve iş başlamadan paylaşılır.

Ne kadar sürer?

Süreyi büyük ölçüde karşı taraf belirler. Belgelenmiş ve test ortamı olan bir servise bağlanmak öngörülebilir bir iştir; belgesi olmayan bir sisteme bağlanmak deneme-yanılmadır. Bu iki durumu teklifte ayrı ayrı yazıyoruz.

Mevcut sistemimizi değiştirmemiz gerekir mi?

Genellikle hayır. Entegrasyonun amacı çalışan sistemleri değiştirmek değil, aralarında elle taşınan veriyi ortadan kaldırmaktır. Değişiklik gerekiyorsa bunu ayrı bir özel yazılım kalemi olarak konuşuruz.

Bir sonraki adım

Entegrasyon konuşmasına yazılım seçerek değil, tek bir soruyla başlayın: hangi bilgiyi bugün elle bir sistemden diğerine taşıyorsunuz ve bunu haftada kaç kez yapıyorsunuz? Bu tek cümle, hangi yöntemin (anlık, zamanlanmış ya da dosya tabanlı) doğru olduğunu genellikle kendiliğinden söyler. Süreçlerinizi topluca gözden geçirmek istiyorsanız Excel'den yazılıma geçiş yazısı iyi bir başlangıç noktası.

Mevcut sistemlerinizin birbirine bağlanıp bağlanamayacağını öğrenmek için ücretsiz ön analiz talebi oluşturabilirsiniz: hangi yöntemin uygun olduğunu, karşı tarafın getirdiği riskleri ve tahmini kapsamı içeren bir dönüşü 1 iş günü içinde yapıyoruz. Yaklaşımımızın ayrıntısı API ve sistem entegrasyonları sayfasında.