API entegrasyonu nedir? İşletmeler için sade anlatım

API entegrasyonu, iki yazılımın bir insan aracı olmadan birbirine veri gönderip alacak biçimde bağlanmasıdır. API (Application Programming Interface, uygulama programlama arayüzü), bir yazılımın dışarıya açtığı ve “bu biçimde istersen bu biçimde cevap veririm” dediği kapıdır. Entegrasyon ise bu kapıyı kullanarak, örneğin e-ticaret siparişinin muhasebeye kendiliğinden düşmesini sağlayan bağlantıdır.

Bu yazıda API’nin ne olduğunu teknik bilgi gerektirmeden anlatıyor, işletmelerde sık karşılaşılan entegrasyon senaryolarını, entegrasyonun nasıl kurulduğunu ve dikkat edilmezse nerede sorun çıkardığını ele alıyoruz.

API nedir? Bir benzetmeyle

API, bir yazılımın başka yazılımlarla konuşmak için kullandığı resmî kanaldır. Bir kurumun dilekçe penceresini düşünün. Pencereye belirli bir formda, belirli bilgilerle başvurursunuz; kurum da size belirli bir formda cevap verir. Binanın içinde neler döndüğünü bilmeniz gerekmez. Kimin hangi pencereye başvurabileceği de bellidir.

API de böyle çalışır:

İstek: “Bugün gelen siparişleri ver” ya da “Bu müşteri için fatura taslağı oluştur.”
Kimlik: İsteği yapanın yetkili olduğunu gösteren bir anahtar ya da oturum.
Cevap: Siparişlerin listesi ya da “fatura oluşturuldu, numarası şu” bilgisi.
Kurallar: Hangi isteklerin kabul edildiği, ne kadar sıklıkla istek yapılabileceği, hangi alanların zorunlu olduğu.

Bu kuralların hepsi sağlayıcının API belgesinde yazılıdır. İyi bir API belgesi, entegrasyonun ne kadar sorunsuz kurulacağının ilk işaretidir.

API ile webhook arasındaki fark nedir?

API’de siz sorarsınız; webhook’ta karşı taraf olay olduğunda size haber verir. API ile “yeni sipariş var mı?” diye belirli aralıklarla sorarsınız. Webhook kurulduğunda ise sipariş geldiği anda e-ticaret sistemi sizin belirlediğiniz adrese bir bildirim gönderir.

	API isteği	Webhook
Kim başlatır?	Sizin sisteminiz	Karşı taraftaki sistem
Ne zaman?	Siz sorduğunuzda	Olay olduğu anda
Tipik kullanım	Liste çekmek, kayıt oluşturmak, güncellemek	Yeni sipariş, ödeme, form gönderimi bildirimi
Dikkat edilecek nokta	Çok sık sormak, limitlere takılmak	Bildirimin gerçekten o sistemden geldiğini doğrulamak

Çoğu entegrasyon ikisini birlikte kullanır: webhook “bir şey oldu” der, API ile ayrıntısı alınır ve diğer sisteme yazılır.

API entegrasyonu ne işe yarar?

API entegrasyonu, aynı bilginin birden fazla sisteme elle yazılmasını ortadan kaldırır. İşletmelerde sık karşılaşılan senaryolar şunlar:

Sipariş ve muhasebe. E-ticaret sitesinden gelen sipariş, muhasebe ya da fatura sisteminde taslak olarak açılır.
Ödeme ve kayıt. Ödeme kuruluşundan gelen “ödeme alındı” bildirimi, siparişin durumunu kendiliğinden günceller.
Kargo. Gönderi oluşturulur, takip numarası siparişe ve müşteriye iletilir.
Form ve CRM. Web sitesindeki form doldurulduğunda CRM’de müşteri kaydı açılır, ilgili kişiye görev atanır.
Stok. Birden fazla satış kanalında stok sayısı tek kaynaktan güncellenir.
Mesajlaşma. WhatsApp gibi kanallardan gelen konuşmalar müşteri kaydına bağlanır. Bu senaryoyu WhatsApp Business API ile satış otomasyonu yazımızda ayrıntılı anlattık.

Hangi süreçlerin önce otomatikleşmesi gerektiğini küçük işletmeler için iş otomasyonu yazımızda ele aldık. Bu yazı, o bağlantıların nasıl kurulduğuna odaklanıyor.

API entegrasyonu nasıl kurulur?

Bir entegrasyon, iki sistemin belgeleri okunarak, verinin bir taraftan ötekine nasıl eşleneceği yazılarak ve hata durumları baştan tasarlanarak kurulur. Adımlar genellikle şöyledir:

Akışın tarifi. Hangi olayda, hangi veri, hangi sistemden hangisine gidecek? Ters yönde bir şey dönecek mi?
Belgelerin incelenmesi. İki sistemin API’si bu akışı destekliyor mu? Gerekli alanlara erişim var mı?
Alan eşleme. Bir tarafta “Ad Soyad” tek alan, öbür tarafta iki alan olabilir. Vergi numarası, adres, ürün kodu gibi alanların nasıl eşleneceği yazılır.
Test ortamında deneme. Sağlayıcının test ortamı (sandbox) varsa gerçek veriye dokunmadan denenir.
Hata ve tekrar kurgusu. Karşı sistem cevap vermezse ne olacak? Aynı istek iki kez giderse çift kayıt oluşur mu?
Kayıt ve izleme. Her aktarım kayda geçer; bir şey ters giderse sorumluya haber gider.
Canlıya alma ve bakım. İlk haftalar yakından izlenir. Sağlayıcılar API’lerini zaman zaman değiştirir; bağlantının çalışmaya devam etmesi bakım ister.

Beşinci adım en çok atlanan adımdır. Örneğin ağ kesintisi yüzünden cevabı alınamayan bir “fatura oluştur” isteği tekrar gönderildiğinde, iyi kurulmamış bir entegrasyon aynı siparişe iki fatura keser. Bunu önlemek için her isteğe benzersiz bir kimlik verilir ve karşı taraf aynı kimliği ikinci kez gördüğünde yeni kayıt açmaz.

Entegrasyon için hangi yol seçilmeli?

Üç yol vardır: kullandığınız ürünün hazır bağlantısı, bağlantı kurma araçları ve özel entegrasyon. Hangisinin doğru olduğu akışın karmaşıklığına, hacme ve hata durumunda ne kadar görünürlük istediğinize bağlıdır.

Yol	Ne zaman uygun?	Sınırı
Hazır bağlantı (eklenti, uygulama mağazası)	Yaygın iki ürün, standart bir akış	Akış ürünün izin verdiği kadardır
Bağlantı kurma araçları	Basit, az koşullu akışlar, düşük hacim	Hacim arttıkça işlem başı maliyet ve limitler zorlar
Özel entegrasyon	Koşullu adımlar, yüksek hacim, hassas veri, ayrıntılı hata takibi	Geliştirme ve bakım gerektirir

Bizim önerimiz önce hazır bağlantıya bakmanız. Yetmediği yerde özel entegrasyon düşünülebilir. Kullandığınız programı değiştirmek, ancak hiçbir dış bağlantıya izin vermiyorsa gündeme gelir. Bu kararın daha geniş hâlini hazır yazılım mı, özel yazılım mı yazımızda bulabilirsiniz.

API entegrasyonunun riskleri nelerdir?

En önemli riskler yetkisiz erişim, sessizce bozulan akışlar ve kişisel verinin kontrolsüz dolaşmasıdır. Güvenlik tarafında iyi bir başlangıç noktası, OWASP’ın API Güvenliği İlk 10 listesidir. 2023 sürümünde ilk sıralarda nesne düzeyinde yetkilendirme hataları ve kimlik doğrulama hataları yer alıyor. Kendi API’nizi açıyorsanız bu listeyi bir kontrol listesi gibi kullanın.

İşletme tarafında dikkat etmenizi önerdiğimiz noktalar:

Anahtarların saklanması. API anahtarı bir paroladır. Kodun içine, e-postaya ya da ortak bir belgeye yazılmaz; güvenli bir yerde tutulur ve düzenli olarak yenilenir.
En az yetki. Entegrasyon yalnızca okuması gerekeni okuyabilmeli, yazması gerekeni yazabilmelidir. Sipariş okuyan bir bağlantıya iade yetkisi verilmez.
Kişisel veri. Hangi kişisel verinin hangi sisteme, hangi ülkeye gittiği bilinmeli ve aydınlatma metinleri buna göre güncellenmelidir. Hukuki ayrıntıyı danışmanınızla kontrol etmenizi öneririz.
Sessiz hatalar. Bir bağlantı koptuğunda akış durmalı ve birine haber vermelidir. Haftalar sonra kayıp siparişlerle fark edilen bir hata, entegrasyon olmamasından daha pahalıya patlar.
Sağlayıcı değişiklikleri. API’ler sürümlenir, eski sürümler kapatılır. Sağlayıcının duyurularını takip eden biri olmalıdır.
Limitler. Çoğu API belirli bir sürede yapılabilecek istek sayısını sınırlar. Kampanya günü gibi yoğun anlar için kurgu buna göre yapılır.

Sağlayıcıya sorulacak 8 soru

Bir yazılımı satın almadan ya da bir entegrasyona başlamadan önce sağlayıcıya şu soruları sormanızı öneriyoruz. Bu cevaplar, entegrasyonun mümkün olup olmadığını ve ne kadar emek isteyeceğini büyük ölçüde belirler.

Herkese açık ve güncel bir API belgeniz var mı?
Gerçek veriye dokunmadan deneyebileceğimiz bir test ortamı var mı?
Olaylar için webhook gönderebiliyor musunuz? Hangi olaylar için?
Kimlik doğrulama nasıl yapılıyor? Yetkileri daraltılmış anahtar oluşturabiliyor muyuz?
İstek limitleriniz nedir?
API sürümlerini nasıl değiştiriyorsunuz, eski sürüm ne kadar süre destekleniyor?
API kullanımı ayrıca ücretlendiriliyor mu ya da belirli bir pakete mi bağlı?
Bir sorun olduğunda teknik destek ekibinize nasıl ulaşırız?

İlk iki sorunun cevabı hayırsa, entegrasyon mümkün olsa bile zahmetli olacaktır. Bu durum, ürün seçiminde bir eksi puan olarak not edilmelidir.

Yapay zekâ ve API

Yapay zekâ araçlarının şirket sistemlerine bağlanması da API’ler üzerinden olur. Bir dil modelinin müşteri kaydını okuması ya da bir talep açması, aslında bir API çağrısıdır. Bu bağlantıları standart bir biçimde tanımlamak için geliştirilen yaklaşımı MCP nedir yazımızda, iş süreçlerine dil modeli eklemeyi de ChatGPT entegrasyonu yazımızda anlattık. Yukarıdaki güvenlik kuralları burada da aynen geçerlidir.

Sık sorulan sorular

API entegrasyonu için kullandığımız programları değiştirmemiz gerekir mi?

Çoğu zaman hayır. Muhasebe, e-ticaret, CRM ve ödeme sistemlerinin büyük kısmı bir API sunar. Önce mevcut sistemleri bağlamayı denemenizi öneririz; bir programı değiştirmek, ancak hiçbir dış bağlantıya izin vermiyorsa konuşulur.

Bir API değişirse entegrasyon bozulur mu?

Bozulabilir. Sağlayıcılar genellikle değişiklikleri önceden duyurur ve eski sürümü bir süre daha çalıştırır. Bu yüzden entegrasyonların bakımı vardır: duyurular takip edilir, bağlantı yeni sürüme zamanında taşınır.

API entegrasyonu güvenli mi?

Doğru kurulduğunda güvenlidir. Anahtarların güvenli saklanması, yalnızca gereken yetkinin verilmesi, her aktarımın kayda geçmesi ve gelen bildirimlerin doğrulanması gerekir. Bu yüzden güvenliğin kurulumun ilk adımında tasarlanmasını öneririz.

Entegrasyonun kaynak kodu kime ait olur?

Bu, sözleşmede belirlenir. Kaynak kodun teslimde size devredilmesini sözleşmeye yazdırmanızı öneririz. Böylece ileride başka bir ekiple çalışmak isterseniz elinizde eksiksiz ve belgelenmiş bir yapı olur.

Sistemlerinizi birbirine bağlamak için nereden başlanacağını konuşmak isterseniz otomasyon ve entegrasyon sayfamıza bakabilir ya da kullandığınız programları kısaca listeleyerek bize yazabilirsiniz. Talebinize en geç iki iş günü içinde dönüyoruz.