Rehber

API entegrasyonu nedir, projede nelere dikkat edilir?

Entegrasyonun zor kısmı kod değil, kararlardır. Hangi sistem hangi veride söz sahibi, hata anında ne olur, erişim kime açılır ve sağlık nasıl izlenir?

Fratres Editör · 11 Kasım 2026

API entegrasyonu, iki yazılımın birbirinin verisine ve işlevine, kuralları önceden yazılmış bir arayüz (API, application programming interface) üzerinden ulaşmasıdır. Onaylanan siparişin muhasebeye, web formundaki talebin satış ekibine kendiliğinden gitmesi bu bağlantıyla olur. Projenin zor kısmı kod değildir. Hangi sistemin hangi veride söz sahibi olduğu, hata anında ne olacağı ve erişimin kime açılacağı baştan karara bağlanmalıdır.

API entegrasyonu neyi çözer, neden zorlaşıyor?

Satış, pazarlama, finans ve operasyon yazılımları ayrı ayrı alındığında aynı müşteri birkaç yerde farklı biçimde yaşar. Entegrasyon bu kopyaları tek bir akışa bağlar. Üç temel biçimi vardır:

İstek ve yanıt: Bir sistem diğerine HTTP üzerinden soru sorar, yanıtı hemen alır. Stok sorgusu buna örnektir.
Olay bildirimi (webhook): Kaynak sistem bir şey olduğunda karşı tarafa haber verir. Ödeme onayı tipik örnektir.
Toplu aktarım: Veri belirli aralıklarla dosya ya da toplu çağrıyla taşınır. Gece çalışan muhasebe aktarımları böyledir.

Zorluk, sistem sayısıyla büyüyor. MuleSoft'un Vanson Bourne ile Ekim ve Kasım 2025'te yaptığı ankete 1.050 BT yöneticisi katıldı. Kurumlardaki uygulama sayısı bir yılda 897'den 957'ye çıktı ve bu uygulamaların yalnız %27'si birbirine bağlı. Örneklem en az 1.000 çalışanlı şirketlerden oluşuyor ve Türkiye'yi kapsamıyor. MuleSoft'un entegrasyon yazılımı sattığını da hesaba katın.

Ekip içi düzen ayrı bir sorun. Postman'in 5.700'den fazla geliştirici ve yöneticiyle yaptığı 2025 API raporunda ekiplerin %93'ü API iş birliğinde engelle karşılaştığını söylüyor. Katılımcıların %55'i tutarsız dokümantasyondan, %34'ü var olan API'yi bulamamaktan yakınıyor. Bu da bir araç sağlayıcının anketi. Yön gösterir, sizin şirketinizi anlatmaz.

Başlamadan hangi kararlar verilmeli?

Teknik ekip ilk toplantıda uç nokta (endpoint) listesi ister. Ondan önce dört karar gerekir.

Asıl kaynak (source of truth): Müşteri adresi CRM'de mi, ERP'de mi doğru kabul edilir? Her alan için tek bir sahip yazın. İki sistem aynı alanı güncelliyorsa çakışma kuralı belirleyin.
Yön ve sıklık: Veri tek yönlü mü akacak, çift yönlü mü? Anlık mı gerekiyor, saatlik yeterli mi? Anlık aktarım her zaman daha iyi değildir, daha çok hata noktası demektir.
Hacim ve limit: Günlük kayıt sayısını ve karşı sistemin çağrı sınırını öğrenin. Kampanya günleri ortalamanın birkaç katı yük getirebilir.
Sözleşme: Alanlar, biçimler ve hata kodları yazılı bir tanımda toplanmalı. Bunun için yaygın standart OpenAPI'dir. Son sürüm 3.2.0, 19 Eylül 2025'te yayımlandı. Tanım dosyası, iki ekibin aynı şeyi konuştuğunu gösteren belge olur.

Veri sahipliği sorusu CRM projelerinde de karşınıza çıkar. CRM veri kalitesi yazısındaki alan sahipliği yaklaşımı entegrasyon için de geçerlidir.

Türkiye'de durum: Veri yurt dışına çıkıyorsa

Bağlandığınız hizmetin sunucusu yurt dışındaysa entegrasyon aynı zamanda bir kişisel veri aktarımıdır. 6698 sayılı Kanun'un 9. maddesine dayanan Kişisel Verilerin Yurt Dışına Aktarılmasına İlişkin Usul ve Esaslar Hakkında Yönetmelik, 10 Temmuz 2024 tarihli ve 32598 sayılı Resmî Gazete'de yayımlandı. Yeterlilik kararı yoksa aktarım, standart sözleşme gibi uygun güvencelerle yapılır. Standart sözleşme metni değiştirilmeden kullanılır ve imzaların tamamlanmasından itibaren beş iş günü içinde Kurum'a bildirilir. Kurum bu bildirim için bir Standart Sözleşme Bildirim Modülü açtı. Hangi alanların nereye gittiğini gösteren veri eşleme listesi, hukuk ekibinin bu değerlendirmeyi yapabilmesi için de gerekir. Bu bölüm hukuki danışmanlık yerine geçmez.

Proje adım adım nasıl yürütülür?

Envanteri çıkarın. Bağlanacak sistemleri, mevcut bağlantıları ve bunları kimin yönettiğini tek listede toplayın. Unutulmuş eski bağlantılar burada ortaya çıkar.
İş akışını yazın. "Sipariş onaylanınca fatura taslağı oluşsun" gibi tek cümlelik olaylarla başlayın. Her olay için tetikleyiciyi, taşınan alanları ve beklenen sonucu not edin.
Alan eşlemesi yapın. Kaynak ve hedef alanları yan yana koyun. Tarih, para birimi, telefon ve adres biçimlerinin dönüşüm kuralını yazın.
Sözleşmeyi kilitleyin. OpenAPI tanımını iki tarafa onaylatın. Sonraki her değişiklik sürüm numarasıyla gelsin.
Tekrar güvenliğini kurun. Ağ kesildiğinde aynı istek yeniden gönderilir. RFC 9110, aynı isteğin birkaç kez yapılmasının tek seferle aynı etkiyi bıraktığı yöntemlere idempotent der. PUT ve DELETE böyledir, POST değildir. Ödeme ve sipariş gibi POST çağrılarında benzersiz bir anahtar gönderin. Stripe bu anahtarları en az 24 saat saklıyor ve aynı anahtarla gelen tekrara ilk yanıtı döndürüyor.
Limitleri ve hataları planlayın. Sunucu çok fazla istek aldığında 429 kodu döner. RFC 6585, bu yanıtın ne kadar beklenmesi gerektiğini Retry-After başlığıyla bildirebileceğini söyler. İstemci bu süreye uymalı ve her denemede bekleme süresini artırmalıdır. Kendi API'nizde hata gövdesini RFC 9457 biçiminde vermek, karşı ekibin hatayı makineyle okumasını kolaylaştırır.
Test ortamında uçtan uca deneyin. Sorunsuz senaryonun yanında boş alan, yinelenen kayıt, zaman aşımı ve yetkisiz erişim senaryolarını da çalıştırın.
İzlemeyi canlıdan önce açın. Her çağrının sonucu, süresi ve hata kodu kayda geçmeli. Başarısız işler bir kuyrukta beklemeli, sessizce kaybolmamalı.

Güvenlikte önce hangi açıklar kapatılır?

OWASP'ın API Security Top 10 2023 listesinin ilk sırasında nesne düzeyinde yetki hatası (BOLA) var. Kullanıcı adres çubuğundaki kayıt numarasını değiştirip başkasının siparişini görebiliyorsa sorun budur. Kimlik doğrulama tek başına yetmez. Her istekte "bu kişi bu kayda erişebilir mi?" sorusu sorulmalıdır.

Entegrasyon projeleri için listede iki madde daha öne çıkar. Dokuzuncu madde, belgelenmemiş ya da eskimiş uç noktaların ve sürümlerin yarattığı riski anlatır. Onuncu madde, üçüncü taraf API'den gelen veriye fazla güvenmeyi anlatır. Saldırgan doğrudan sizi değil, bağlandığınız hizmeti hedefleyebilir. Dışarıdan gelen veriyi de kullanıcı girdisi gibi doğrulayın.

Erişim belirteçleri (token) için güncel referans, Ocak 2025 tarihli RFC 9700 OAuth 2.0 güvenlik önerileridir. Belge, örtük akış (implicit grant) yerine yetkilendirme kodu akışını ve PKCE kullanımını önerir. Belirteçlerin yalnız gereken yetkiyle ve belirli bir sunucuya sınırlı verilmesini ister. Pratikte her entegrasyona ayrı bir hesap ve ayrı anahtar açın. Anahtarları kod deposunda değil, gizli bilgi kasasında tutun.

Sık yapılan hatalar

Kalıcı çözüm yerine geçici betik: Bir çalışanın bilgisayarında çalışan betik, o kişi izne çıkınca durur. Her bağlantının bir sahibi ve izleme ekranı olmalı.
Çakışma kuralı olmadan çift yönlü akış: İki sistem aynı alanı yazınca kayıtlar birbirini ezer. Kural yazılmadan çift yönlü akışı açmayın.
Hata kodlarını yutmak: Başarısız yanıtı kaydetmeden geçmek, eksik siparişi haftalar sonra fark ettirir.
Etkisi anlatılmayan değişiklik: Postman verisinde katılımcıların %60'ı API'lerini sürümlüyor, ama yalnız %26'sı anlamsal sürümleme (semantic versioning) kullanıyor. Yani çoğu ekip değişikliği kaydediyor, etkisini karşı tarafa bildirmiyor. Alan adını sessizce değiştirmek karşı sistemi bozar.
Kişisel veriyi gereğinden fazla taşımak: Hedef sistem yalnız e-posta istiyorsa kimlik numarasını göndermeyin. Az veri, az risk ve daha kolay KVKK değerlendirmesi demektir.
Dokümantasyonu en sona bırakmak: Proje bitince yazılacak belge çoğu zaman hiç yazılmaz. Tanım dosyası işin başında açılmalı.

Entegrasyonun sağlığı nasıl ölçülür?

Canlıya geçtikten sonra şu göstergeleri haftalık izleyin:

Başarı oranı: Başarılı çağrıların toplam çağrıya oranı. Akış bazında ayrı tutun, çünkü ortalama tek bozuk akışı gizler.
Gecikme: Kaynakta olayın oluştuğu an ile hedefte görüldüğü an arasındaki süre. Kabul edilen süreyi yazın, aşımı alarma bağlayın.
Mutabakat farkı: Gün sonunda iki sistemdeki kayıt sayısını ve tutarları karşılaştırın. Fark sıfır değilse kaybolan işi bulun.
Yinelenen kayıt: Aynı siparişin ya da kişinin iki kez oluşması, tekrar güvenliğinin çalışmadığını gösterir.
Limit aşımı: 429 yanıtlarının sayısı. Artıyorsa çağrıları toplu hale getirmenin ya da önbellek kurmanın zamanı gelmiştir.
Düzeltme süresi: Hatanın fark edilmesinden çözülmesine geçen süre.

Bu göstergeleri satış ve operasyon ekiplerinin de gördüğü bir panoya koymak, sorunun iş tarafında erken fark edilmesini sağlar. Entegrasyonu bir otomasyon programının parçası olarak düşünüyorsanız sıradaki soru iş süreci otomasyonuna nereden başlanacağıdır. Bağlantı mimarisini ve izlemeyi birlikte kurmak için API entegrasyonları başlığı bu adımları bir arada ele alır.

Yarın envanterle başlayın

Yarın bir çalışma sayfası açın ve şirketteki her sistem bağlantısını satır satır yazın: hangi iki sistem, hangi veri, hangi sıklıkla, kim sorumlu, hata olursa kim haberdar oluyor. Sahibi ya da izlemesi olmayan satırları işaretleyin. Kişisel veri taşıyan ve yurt dışına giden bağlantıları ayrı bir renkle gösterin. Yeni entegrasyon projesinin kapsamı bu listeden çıkar. İlk iş, işaretli satırlara birer sahip atamaktır.