"Siparişler siteye düşüyor ama muhasebeye elle giriyoruz." "Stok depoda değişiyor, pazaryerinde bir gün sonra güncelleniyor." Bu cümleleri duyduğumuz her projede asıl ihtiyaç aynıdır: sistemlerin birbiriyle konuşması. API entegrasyonu, iki yazılımın önceden tanımlanmış kurallarla birbirine veri gönderip alması ve böylece bir sistemdeki işlemin diğerinde insan müdahalesi olmadan karşılık bulmasıdır. API (Application Programming Interface, uygulama programlama arayüzü) bu kuralları tanımlayan kapıdır: hangi adrese, hangi biçimde, hangi kimlikle istek atılacağını ve cevabın nasıl döneceğini belirler. Bu yazıda API entegrasyonunun temel kavramlarını bir sözlük gibi açıklıyor, ardından işletmelerde sık karşılaştığımız entegrasyon örneklerini anlatıyoruz.
API entegrasyonu nasıl çalışır?
En basit hâliyle bir API entegrasyonu, bir garsonla mutfak arasındaki ilişkiye benzer. Müşteri (sizin sisteminiz) siparişi belirli bir biçimde verir; garson (API) bunu mutfağa (karşı sistem) iletir ve hazırlanan yemeği geri getirir. Müşterinin mutfağın içini bilmesi gerekmez; menüdeki seçenekleri ve sipariş verme kurallarını bilmesi yeterlidir.
Teknik tarafta bu, şöyle bir akışa dönüşür. E-ticaret siteniz yeni bir sipariş aldığında muhasebe programının API'sine bir istek gönderir: "Şu müşteri için şu ürünlerden oluşan bir satış kaydı oluştur." İstek, internet üzerinden HTTPS ile gider ve gövdesinde JSON biçiminde veri taşır. Muhasebe programı isteğin kimden geldiğini doğrular, veriyi kontrol eder, kaydı oluşturur ve bir cevap döner: başarılıysa oluşturulan kaydın numarası, değilse hatanın sebebi.
Entegrasyon iki yönlü de olabilir. Sizin sisteminiz karşı tarafa düzenli olarak "yeni bir şey var mı?" diye sorabilir ya da karşı sistem bir olay olduğunda size haber verebilir. Hangi yöntemin seçileceği, verinin ne kadar güncel olması gerektiğine ve karşı sistemin neyi desteklediğine bağlıdır.
Temel kavramlar sözlüğü
Entegrasyon projelerinde sık geçen terimleri, bir yazılımcıyla konuşurken ne anlama geldiklerini bilecek kadar açıklayalım.
REST ve uç nokta (endpoint)
REST, web API'lerinin en yaygın tasarım biçimidir. Her kaynak (müşteri, sipariş, ürün) bir adresle temsil edilir; bu adreslere uç nokta denir. Örneğin https://api.ornekfirma.com/v1/siparisler sipariş listesine, /v1/siparisler/1042 ise tek bir siparişe karşılık gelir. Adresteki v1 sürüm bilgisidir; API sağlayıcısı yeni bir sürüm çıkardığında eski entegrasyonların bozulmaması için kullanılır.
HTTP metotları
Bir uç noktaya ne yapmak istediğinizi metot belirler. GET veri okur, POST yeni kayıt oluşturur, PUT ve PATCH mevcut kaydı günceller, DELETE siler. Aynı adrese farklı metotla gitmek farklı işlem demektir.
İstek, cevap ve JSON
Her API çağrısı bir istek ve bir cevaptan oluşur. İstekte adres, metot, başlık bilgileri (kimlik, içerik türü) ve gerekiyorsa gövde bulunur. Gövde genellikle JSON biçimindedir: {"musteri_id": 381, "tutar": 1250.00, "para_birimi": "TRY"}. Eski sistemlerde XML tabanlı SOAP servislerine de hâlâ rastlanır; özellikle bazı kamu ve finans entegrasyonlarında bu biçim kullanılır.
HTTP durum kodları
Cevabın başarılı olup olmadığını durum kodu söyler. 2xx başarı (200 tamam, 201 oluşturuldu), 4xx istemci hatası (400 hatalı istek, 401 kimlik doğrulanamadı, 403 yetki yok, 404 bulunamadı, 429 çok fazla istek), 5xx ise sunucu hatası anlamına gelir. Bu ayrım hata yönetiminin temelidir: 4xx hatalarında isteği düzeltmeden tekrar göndermenin anlamı yoktur, 5xx ve 429 hatalarında ise bir süre bekleyip yeniden denemek çoğu zaman doğru davranıştır.
Webhook
Webhook, karşı sistemin bir olay gerçekleştiğinde sizin belirlediğiniz bir adrese kendiliğinden istek göndermesidir. "Yeni sipariş var mı?" diye her beş dakikada bir sormak (polling) yerine, ödeme sağlayıcısı ödeme onaylandığı anda size haber verir. Webhook'lar hem daha hızlıdır hem de gereksiz istek trafiğini azaltır. Ancak sizin tarafınızda her zaman erişilebilir, HTTPS ile çalışan bir uç nokta gerektirir.
Kimlik doğrulama
API, isteğin kimden geldiğini bilmek zorundadır. En yaygın yöntemler şunlardır:
- API anahtarı: Sağlayıcının size verdiği gizli bir dizgi, her istekte başlıkta gönderilir. Basittir ama anahtar sızarsa herkes sizin adınıza işlem yapabilir.
- OAuth 2.0: Kullanıcının, şifresini paylaşmadan bir uygulamaya belirli izinler vermesini sağlayan yetkilendirme çerçevesidir. "Google hesabınla bağlan" ekranlarının arkasında bu mekanizma vardır. Sonuçta süreli bir erişim jetonu (access token) alınır ve istekler bu jetonla yapılır.
- İmza doğrulama: Özellikle webhook'larda kullanılır. Gönderen taraf, mesajı ortak bir gizli anahtarla imzalar; siz de aynı anahtarla imzayı doğrulayarak mesajın gerçekten o sistemden geldiğinden ve yolda değiştirilmediğinden emin olursunuz.
Hız sınırı (rate limit)
API sağlayıcıları, belirli bir sürede yapılabilecek istek sayısını sınırlar. Sınır aşıldığında genellikle 429 kodu döner ve çoğu zaman ne kadar beklemeniz gerektiğini Retry-After başlığıyla bildirir. Toplu veri aktarımlarında bu sınırı hesaba katmayan entegrasyonlar en yoğun anda tıkanır.
İdempotency (tekrar güvenliği)
Aynı isteğin birden fazla kez gönderilmesi durumunda sonucun değişmemesidir. Bağlantı koptuğunda isteği yeniden göndermek zorunda kalırsınız; ama ilk istek aslında karşı tarafa ulaşmışsa iki fatura ya da iki tahsilat oluşabilir. Bazı API'ler bunun için her isteğe benzersiz bir anahtar eklemenize izin verir; aynı anahtarla gelen ikinci istek yeni bir işlem başlatmaz. Webhook alırken de aynı olayın iki kez gelebileceğini varsayıp olay kimliğini kaydetmek bu sorunu önler.
API dokümantasyonu ve OpenAPI
İyi bir API, hangi uç noktaların olduğunu, hangi alanların zorunlu olduğunu, örnek istek ve cevapları ve hata kodlarını açıklayan bir dokümantasyonla gelir. OpenAPI, bu tanımı makinenin de okuyabileceği standart bir biçimde yazmayı sağlayan bir belirtimdir; test araçları ve kod üreticiler bu tanımı doğrudan kullanabilir. Bir entegrasyon teklifi değerlendirirken karşı sistemin dokümantasyonuna bakmak, işin zorluğunu en hızlı anlamanın yoludur.
Test ortamı (sandbox)
Gerçek veriyi etkilemeden deneme yapılabilen ayrı bir ortamdır. Ödeme, fatura ve kargo entegrasyonlarında test ortamı olmayan bir API ile çalışmak, her denemenin gerçek bir işlem yaratması anlamına gelir; bu yüzden test ortamının varlığı entegrasyon planını doğrudan etkiler.
Hata yönetimi: entegrasyonun asıl işi
Bir entegrasyonun her şey yolundayken çalışması işin kolay kısmıdır. Asıl değer, işler ters gittiğinde ne olduğunda ortaya çıkar. Karşı sistem bakımda olabilir, ağ kopabilir, veri beklenmedik biçimde gelebilir. Sağlam bir entegrasyonda şu önlemler bulunur:
- Hataları sınıflandırın. Kalıcı hatalar (hatalı veri, yetkisiz istek) ile geçici hatalar (zaman aşımı, sunucu hatası, hız sınırı) farklı ele alınmalıdır. Kalıcı hatayı tekrar denemek yerine kaydedip bir kişiye bildirin.
- Geçici hatalarda artan aralıklarla yeniden deneyin. İlk denemeden birkaç saniye sonra, sonra daha uzun aralıklarla tekrar edin. Sürekli ve hızlı tekrar, zaten zorlanan karşı sistemi daha da yorar.
- Zaman aşımı belirleyin. Cevap vermeyen bir API'yi sonsuza kadar beklemek, kendi sisteminizi de kilitler. Her çağrıya makul bir süre sınırı koyun.
- İşlemleri kuyruğa alın. Sipariş aktarımı gibi kritik işleri doğrudan kullanıcı isteğinin içinde değil, bir kuyruk üzerinden yapın. Karşı sistem çalışmıyorsa işler kuyrukta bekler ve sistem geri geldiğinde sırayla işlenir.
- Her şeyi kaydedin. Hangi isteğin ne zaman gönderildiğini, ne cevap alındığını ve kaç kez denendiğini loglayın. "Bu fatura neden muhasebeye geçmedi?" sorusunun cevabı bu kayıtlardadır. Loglara kişisel veri ve gizli anahtar yazmamaya dikkat edin.
- İzleyin ve uyarın. Başarısız işlem sayısı belirli bir eşiği geçtiğinde ilgili kişiye e-posta veya mesajla haber verin. Sessizce başarısız olan bir entegrasyon, hiç olmayan bir entegrasyondan daha tehlikelidir; çünkü herkes çalıştığını sanır.
- Uzlaştırma (mutabakat) yapın. Belirli aralıklarla iki sistemdeki kayıtları karşılaştıran bir kontrol çalıştırın: sitedeki siparişler ile muhasebedeki faturalar aynı mı? Gözden kaçan kayıtlar böylece yakalanır.
Güvenlik: anahtarlar ve yetkiler
API entegrasyonu, sisteminize yeni bir kapı açmak demektir; bu kapının da kilidi olmalıdır. OWASP'ın API güvenliği listesi, en yaygın riskler arasında nesne düzeyinde yetki kontrolünün eksik olmasını, zayıf kimlik doğrulamayı ve üçüncü taraf API'lerden gelen veriye gereğinden fazla güvenmeyi sayıyor. Pratikte uyguladığımız kurallar:
- API anahtarlarını kodun içine yazmayın; ortam değişkenlerinde veya bir gizli bilgi kasasında saklayın ve kod deposuna asla göndermeyin.
- Entegrasyon için ayrı bir kullanıcı veya anahtar açın ve yalnızca gereken yetkileri verin. Sipariş okuyacak bir entegrasyonun ürün silme yetkisi olmamalıdır.
- Webhook'larda imzayı doğrulayın ve mümkünse yalnızca sağlayıcının bilinen IP adreslerinden gelen isteklere izin verin.
- Karşı sistemden gelen veriyi de doğrulayın; beklenmeyen alanları ve değerleri olduğu gibi veri tabanına yazmayın.
- Bir anahtarın sızdığından şüphelendiğinizde hemen iptal edip yenisini oluşturun; bunun nasıl yapılacağını önceden bilin.
İşletmelerde sık görülen entegrasyon örnekleri
| Bağlanan sistemler | Ne sağlar? | Tipik yöntem |
|---|---|---|
| E-ticaret sitesi ve muhasebe programı | Siparişlerin fatura ve cari kaydına otomatik dönüşmesi | Sipariş olayıyla tetiklenen REST çağrısı |
| Site ve pazaryerleri | Ürün, stok ve sipariş senkronizasyonu | Pazaryeri API'si, zamanlanmış senkronizasyon |
| Yazılım ve e-Fatura entegratörü | Faturanın yasal formatta düzenlenip iletilmesi | Entegratörün sunduğu servis |
| Site ve ödeme kuruluşu | Tahsilat ve ödeme sonucunun anında öğrenilmesi | Ödeme API'si ve webhook |
| Sipariş sistemi ve kargo firması | Gönderi oluşturma, takip numarası, teslim durumu | Kargo API'si, durum sorgulama veya webhook |
| CRM ve web formları | Formdan gelen talebin müşteri adayı olarak kaydı | Form gönderiminde REST çağrısı |
| İş uygulaması ve mesajlaşma | Sipariş, randevu ve kargo bildirimleri | Mesajlaşma sağlayıcısının API'si |
Pazaryeri bağlantılarında ürün eşleştirme ve stok senkronizasyonu gibi kendine özgü sorunlar vardır; bunları pazaryeri entegrasyonu rehberimizde ele aldık. e-Fatura tarafındaki akışı e-Fatura ve e-Arşiv entegrasyonu yazımızda, müşterilere WhatsApp üzerinden otomatik bildirim göndermeyi ise WhatsApp Business API rehberimizde anlattık. Bayi ve toptan satış senaryolarında ERP bağlantısı öne çıkar; bu konu B2B bayi portalı yazımızda yer alıyor.
Hazır entegrasyon aracı mı, özel geliştirme mi?
Her entegrasyon için kod yazmak gerekmez. n8n, Zapier veya Make gibi iş akışı otomasyonu araçları, popüler uygulamalar için hazır bağlantılar sunar ve basit akışları birkaç saatte kurmanızı sağlar: formdan gelen veriyi tabloya yazmak, yeni siparişte ekibe mesaj atmak gibi. Kendi sunucunuzda çalıştırabileceğiniz bir seçenek arıyorsanız n8n rehberimiz iyi bir başlangıçtır.
Özel geliştirme ise şu durumlarda daha doğru olur: veri dönüşümü karmaşıksa (birden fazla sistemden gelen veriyi birleştirmek, özel fiyat kuralları uygulamak), işlem hacmi yüksekse, hata yönetimi ve uzlaştırma kritikse ya da karşı sistemin hazır bir bağlantısı yoksa. Pratikte ikisini birlikte kullanmak da mümkündür: basit bildirim akışları otomasyon aracında, para ve stokla ilgili kritik akışlar özel kodda.
Sık Sorulan Sorular
Her yazılımın API'si var mı?
Hayır. Modern bulut yazılımlarının çoğu API sunar, ancak bazı eski veya kurulu programlarda API yoktur ya da yalnızca üst paketlerde açılır. Bu durumda veri dosya aktarımıyla, veri tabanı bağlantısıyla veya üreticinin sunduğu ek bir modülle taşınabilir. Bir yazılım seçerken API'nin varlığını ve dokümantasyonunu sorgulamak sonradan yaşanacak sorunları önler.
API entegrasyonu ne kadar sürer?
İyi belgelenmiş bir API ile tek yönlü, basit bir veri aktarımı birkaç günde kurulabilir. İki yönlü senkronizasyon, karmaşık veri eşleştirme, hata yönetimi ve uzlaştırma içeren entegrasyonlar ise haftalar sürebilir. Süreyi en çok karşı sistemin dokümantasyon kalitesi ve test ortamının varlığı belirler.
Webhook ile periyodik sorgulama arasında nasıl seçim yapılır?
Karşı sistem webhook destekliyorsa ve anlık bilgi önemliyse webhook tercih edilir. Webhook yoksa ya da birkaç dakikalık gecikme sorun değilse periyodik sorgulama yeterlidir. Kritik akışlarda ikisi birlikte kullanılır: webhook anlık bildirim için, periyodik kontrol ise kaçırılan olayları yakalamak için.
Entegrasyon bozulursa nasıl anlarız?
İzleme ve uyarı mekanizması kurulmuşsa başarısız işlemler size bildirilir. Kurulmamışsa genellikle müşteri şikâyetiyle ya da muhasebedeki eksik kayıtla fark edilir. Bu yüzden izleme, entegrasyonun isteğe bağlı değil, zorunlu bir parçası olmalıdır.
API sağlayıcısı sürümü değiştirirse ne olur?
Sağlayıcılar genellikle yeni sürümü duyurur ve eski sürümü bir süre daha çalışır tutar. Bu duyuruları takip etmek ve entegrasyonu zamanında güncellemek gerekir. Bakım sözleşmesine API sürüm takibini dahil etmek, sürpriz kesintileri önler.
Sistemlerinizi birbirine bağlayalım
İyi bir API entegrasyonu, elle yapılan tekrar eden işleri ortadan kaldırır, hataları azaltır ve verinin tek bir doğru kaynaktan akmasını sağlar. Muhasebe, e-ticaret, pazaryeri, kargo veya kendi iş uygulamanız arasında hangi bağlantıya ihtiyacınız olduğunu birlikte belirleyip hata yönetimi ve izlemesiyle birlikte kurabiliriz. Özel yazılım hizmetimizi inceleyebilir veya mevcut sistemlerinizi anlatmak için bizimle iletişime geçebilirsiniz.
