API ve veri alışverişi: intranetin diğer sistemlerle konuşması

Bir intranet tek başına durduğunda, çalışan verisi elle giriliyor, izin bakiyeleri tutmuyor ve aynı bilgi üç yerde ayrı ayrı güncelleniyor.

Entegrasyon, bu tekrarın ortadan kalkması demek. Ama her entegrasyon da otomatik olarak iyi değil: yanlış kurgulanmış bir senkron, hatayı iki katı hızda yayıyor.

Üç temel yöntem

REST API. İstek geldiğinde cevap veren arayüz. "Bu çalışanın izin bakiyesi ne kadar?" sorusuna anlık cevap almak için uygun. Gerçek zamanlı ama her sorgu bir istek demek.

Webhook. Ters yön: bir olay olduğunda sistem karşı tarafa haber veriyor. "Yeni çalışan eklendi" bilgisinin İK sisteminden intranete anında gitmesi gibi. Sürekli sorgulamaya göre çok daha verimli. Kullanım örneklerini intranet entegrasyonları ve webhook yazısında ele aldık.

Toplu aktarım (batch). Günde bir kez dosya ya da veritabanı senkronu. Eski yöntem ama hâlâ yaygın ve bazı durumlarda en doğrusu: büyük hacimli, gecikmeye toleranslı veriler için.

Çoğu kurumsal senaryoda üçü birlikte kullanılıyor: kritik olaylar webhook ile anında, sorgular API ile, tam mutabakat gece toplu iş ile.

Tek yönlü mü çift yönlü mü?

En önemli tasarım kararı: hangi sistem hangi verinin sahibi?

Tek yönlü senkron basit ve güvenli: İK sistemi çalışan verisinin sahibi, intranet onu okur ve gösterir. İntranette değiştirilemez.

Çift yönlü senkron güçlü ama riskli: aynı kayıt iki yerde değiştirilebiliyorsa, çakışma kaçınılmaz. "Hangisi kazanır" kuralı baştan tanımlanmalı.

Pratik öneri: mümkün olduğunca tek yönlü tasarlayın ve her veri alanı için tek bir sahip belirleyin. Çift yönlülük gerçekten gerekliyse, çakışma çözümü yazılı olmalı.

Örnek: senkronun sessizce durması

Bir şirkette İK sisteminden intranete gecelik çalışan senkronu kurulmuş. Aylarca sorunsuz çalışıyor.

Bir gün İK sisteminde bir alan adı değişiyor. Senkron hata veriyor ama hata kimseye bildirilmiyor — log dosyasına yazılıyor ve orada kalıyor.

Üç hafta sonra fark ediliyor: bu sürede işe giren 12 kişi intranette görünmüyor, ayrılan 4 kişinin hesabı hâlâ aktif. İkincisi bir güvenlik bulgusu; erişim kapatma yükümlülüğünü ISO 27001 ve intranet yazısında ele aldık.

Eksik olan şey entegrasyon değil, izleme. Her entegrasyonun üç şeye ihtiyacı var: başarısızlıkta bildirim, düzenli sağlık kontrolü ve son başarılı çalışma zamanının görünür olması.

Hata yönetimi

Entegrasyon tasarımında en çok atlanan kısım, işlerin ters gittiği senaryolar:

• Geçici hata (karşı sistem kapalı): yeniden deneme mantığı, artan bekleme süresiyle.
• Kalıcı hata (veri geçersiz): hangi kayıt, neden reddedildi? Sessizce atlanmamalı.
• Kısmi başarı: 100 kayıttan 98'i geçti, 2'si başarısız. Bu bir başarı mı başarısızlık mı? Raporlama netliği gerekiyor.
• Tekrarlanabilirlik: aynı iş iki kez çalışırsa veri iki kez mi yazılıyor? Bu, üretim ortamında sık görülen bir hata kaynağı.

Kimlik doğrulama ve güvenlik

API erişiminde dikkat edilecekler: anahtar ya da token'ın nerede saklandığı (asla kod içinde değil), yetkinin en az düzeyde tutulması, erişim kayıtlarının tutulması ve anahtarın düzenli yenilenmesi.

Kişisel veri aktarımı söz konusuysa, bu aktarım envanterde yer almalı; yöntemini KVKK veri işleme envanteri yazısında ele aldık. Kimlik yönetiminin merkezîleştirilmesini kimlik ve dizin entegrasyonu yazısında anlattık.

Sahiplik: en sık atlanan madde

Entegrasyon kurulduktan sonra kimin sorumlu olduğu belirsiz kalıyor: BT mi, İK mı, yazılım sağlayıcısı mı?

Sonuç, arızada kimsenin sahiplenmemesi. Kurulum aşamasında yazılması gerekenler: hangi sistemler, hangi veriler, hangi sıklıkta, hata durumunda kime bildirim gidiyor, kim müdahale ediyor ve süreç dokümanı nerede? Dokümantasyon disiplinini süreç dokümantasyonu (SOP) yazısında ele aldık.

Entegrasyon öncesi veri temizliği

Entegrasyonların en sık aksadığı nokta teknik değil, veri kalitesi. İki sistem birbirine bağlandığında, her iki taraftaki dağınıklık da görünür hâle geliyor.

Tipik sorunlar: aynı kişinin iki sistemde farklı yazılmış adı, departman adlarının tutmaması ("Satış" ve "Satış ve Pazarlama"), boş bırakılmış zorunlu alanlar, geçersiz e-posta adresleri ve ayrılmış olmasına rağmen aktif görünen kayıtlar.

Bu yüzden entegrasyon projesi, aktarımdan önce bir mutabakat adımıyla başlamalı: iki sistemdeki kayıtlar karşılaştırılır, farklar listelenir ve hangi tarafın doğru olduğu kararlaştırılır.

Ayrıca eşleştirme anahtarı belirlenmeli: iki sistem aynı kişiyi neye göre eşleştirecek? Ad-soyad kırılgan; sicil numarası ya da kurumsal e-posta daha güvenilir. Anahtar kararı sonradan değiştirilmesi en zor tasarım kararlarından biri.

Veri kalitesi düzeldiğinde, entegrasyonun kendisi genellikle beklenenden kolay ilerliyor.

Sık sorulan sorular

Entegrasyon şart mı? Küçük ölçekte hayır; 50 kişilik bir şirkette elle güncelleme sürdürülebilir. Kadro büyüdükçe elle senkron hem hata üretiyor hem zaman yiyor.

Hangi entegrasyon önce yapılmalı? Neredeyse her zaman çalışan verisi: işe giriş, çıkış ve departman değişikliği. Bu üçü otomatikleşince diğer her şey kolaylaşıyor.

Sağlayıcının API'si yoksa? Ciddi bir kısıt ve seçim aşamasında sorulması gereken bir soru. Alternatif olarak dosya tabanlı aktarım kullanılabiliyor ama kırılgan oluyor.

Gerçek zamanlı mı olmalı? Çoğu İK verisi için gerek yok; gecelik senkron yeterli. Gerçek zamanlılık, erişim kapatma gibi güvenlik kritik olaylarda anlamlı.