API entegrasyonu, bir işletmedeki farklı yazılımların birbiriyle otomatik veri alışverişi yapmasıdır: e-ticaret sitesine düşen sipariş ERP’ye kendiliğinden işlenir, kargo etiketi programdan basılır, banka hareketi cari hesapla otomatik eşleşir. Kulağa basit geliyor; sahada ise işletmelerin en çok zaman kaybettiği konulardan biri. Bu yazıda hangi sistemlerin nasıl bağlandığını, nerelerde sorun çıktığını ve entegrasyon yaptırırken neye dikkat edileceğini anlatıyoruz.
API nedir, entegrasyon ne demek?
API (uygulama programlama arayüzü), bir yazılımın dış dünyaya açtığı kapıdır. Kargo firmasının API’si "şu adrese şu ağırlıkta gönderi oluştur" isteğini kabul eder ve karşılığında takip numarası döner. Entegrasyon, sizin sisteminizin bu kapıları doğru sırayla, doğru veriyle ve hata durumunda ne yapacağını bilerek kullanmasıdır. Zor olan kapıyı çalmak değil; iki tarafın aynı şeyi aynı biçimde anlamasını sağlamaktır.
Bu kapıların bir de anahtarı vardır: API anahtarı veya erişim belirteci. Bu anahtar, sizin adınıza sipariş oluşturma, fatura kesme veya ödeme talimatı verme yetkisi taşır. Kodun içine gömülmüş, e-postayla paylaşılmış veya herkesin bildiği bir anahtar, entegrasyonun en zayıf halkasıdır. Anahtarların nerede saklandığı ve kimin erişebildiği, entegrasyon planının ilk sayfasında yazmalıdır.
En sık bağlanan dört sistem
ERP ve ticari yazılım
Entegrasyonun merkezi genelde burasıdır: stok, cari, fatura ve kasa gerçeği ERP’de yaşar. Diğer tüm sistemler ya buraya veri yazar ya da buradan okur. ERP’nin API’si yoksa (eski masaüstü programlarda sık görülür) entegrasyon doğrudan veritabanı üzerinden veya dosya alışverişiyle yapılır; bu çalışır ama kırılgandır ve her program güncellemesinde yeniden test ister.
E-ticaret ve pazaryerleri
Sitenizden ve pazaryerlerinden gelen siparişlerin tek yerde toplanması, stokun tüm kanallarda eşzamanlı düşmesi ve fiyat güncellemesinin tek noktadan yapılması. Pazaryeri API’leri sık değişir ve her birinin kendi kuralı (ürün eşleme, kategori, barkod zorunluluğu) vardır. Buradaki iş, kodu yazmaktan çok her kanalın istisnalarını yönetmektir.
Kargo
Sipariş onaylandığında gönderi oluşturma, etiket basma, takip numarasını müşteriye iletme ve teslimat durumunu geri alma. Kargo entegrasyonu görece standarttır; sorunlar genelde adres verisinin düzensizliğinden ve iade akışının baştan düşünülmemesinden çıkar. Birden fazla kargo firmasıyla çalışıyorsanız, hangi siparişin hangi firmaya gideceğini belirleyen kuralı (bölge, ağırlık, ödeme tipi) baştan yazdırın; aksi hâlde seçim elle yapılır ve entegrasyonun kazandırdığı zamanın bir kısmı geri gider.
Banka
Hesap hareketlerinin otomatik çekilip cari hesaplarla eşleştirilmesi (banka mutabakatı) ve toplu ödeme talimatları. Bankalar bu servisleri kurumsal müşterilere sözleşmeyle açar; başvuru ve yetkilendirme süreci teknik işten uzun sürebilir. Eşleştirme kuralları (açıklama metninden müşteriyi bulma) ilk aylarda elle düzeltme ister, sonra oturur.
Bu dördünün dışında e-belge entegratörü, SMS ve e-posta servisleri, sanal POS ve muhasebe müşavirinin programı da sık bağlanan uçlardır. Her yeni bağlantı bir bakım noktası daha demektir; "bağlanabilir mi" sorusundan önce "bağlanmazsa ne kaybediyoruz" sorusunu sorun. Elle yapıldığında haftada bir saat alan bir iş için entegrasyon yazdırmak, çoğu zaman o saatin maliyetini geçer.
Entegrasyon projelerinde sorun nerede çıkar?
- Veri standardının olmaması. Aynı ürün ERP’de "ADET", sitede "Adet", pazaryerinde "pcs". Entegrasyon başlamadan birim, barkod, vergi oranı ve cari kodları standartlaştırılmalıdır.
- Hata durumunun düşünülmemesi. Kargo API’si beş dakika yanıt vermezse ne olacak? Sipariş kaybolmamalı, kuyrukta beklemeli ve tekrar denenmelidir. Mutlu senaryo kolaydır; entegrasyonun kalitesi hata senaryosunda belli olur.
- Çift kayıt. Aynı siparişin iki kez işlenmesi en klasik entegrasyon hatasıdır. Her kaydın tekil bir kimlikle takip edilmesi gerekir.
- Karşı tarafın değişmesi. Pazaryeri API sürümünü yükseltir, banka adres değiştirir. Entegrasyon bir kez yazılıp bırakılacak bir şey değildir; izlenmesi ve bakılması gerekir.
- Dokümantasyonsuz devir. Entegrasyonu yazan kişi ayrıldığında kimse hangi servisin nereye bağlı olduğunu bilmiyorsa, ilk arızada sistem günlerce durur.
Gerçek zamanlı mı, toplu mu?
Her veri anında akmak zorunda değildir. Sipariş ve stok düşümü gerçek zamanlı olmalıdır; aynı ürünü iki müşteriye satmak istemezsiniz. Banka mutabakatı günde birkaç kez, fiyat listesi güncellemesi günde bir kez yeterlidir. Her şeyi anlık yapmaya çalışmak hem karşı tarafın istek sınırlarına takılır hem de gereksiz karmaşıklık üretir. Doğru soru "ne kadar hızlı olabilir" değil, "ne kadar gecikme kabul edilebilir" sorusudur.
Webhook mu, sorgulama mı?
Veri akışının iki yöntemi vardır. Sorgulama (polling) yönteminde sizin sisteminiz belirli aralıklarla karşı tarafa "yeni bir şey var mı" diye sorar. Basittir, her API’de çalışır, ama gereksiz istek üretir ve gecikme en az sorgulama aralığı kadardır. Webhook yönteminde karşı taraf bir olay olduğunda (sipariş oluştu, ödeme alındı, kargo teslim edildi) sizin sisteminize bildirim gönderir. Anlıktır ve verimlidir; ama sizin tarafınızda sürekli erişilebilir bir uç nokta gerekir ve bildirimin kaybolması ihtimaline karşı yedek bir sorgulama döngüsü yine de tutulur.
Pratikte ikisi birlikte kullanılır: webhook ana akışı taşır, sorgulama kaçanları toplar. Yalnızca webhook’a güvenen entegrasyonlarda, karşı tarafın bildirim gönderemediği beş dakikalık bir kesinti günlerce fark edilmeyen sipariş kayıplarına dönüşebilir.
Entegrasyon yaptırmadan önce kontrol listesi
- Bağlanacak her sistemin API dokümantasyonu ve test ortamı var mı?
- Hangi verinin hangi yönde akacağı (tek yönlü veya çift yönlü) yazılı mı?
- Veri standartları (birim, barkod, KDV, cari kodu) temizlendi mi?
- Hata, tekrar deneme ve bildirim kuralları tanımlı mı?
- Entegrasyonun çalışıp çalışmadığını gösteren bir izleme ekranı olacak mı?
- API anahtarları ve yetkiler kimde, nasıl saklanıyor?
- Karşı taraf değiştiğinde bakımı kim yapacak, bedeli ne?
Nereden başlamalı?
Hepsini aynı anda bağlamaya çalışmayın. En çok elle iş üreten ve en çok hata çıkaran akışla başlayın; çoğu işletmede bu, siparişin ERP’ye işlenmesidir. O akış oturup güvenilir hâle gelince kargoyu, sonra bankayı ekleyin. Her adımda bir öncekinin çalıştığını ölçmüş olursunuz. Süre ve maliyet açısından da bu yaklaşım daha öngörülebilirdir: tek bir akışın entegrasyonu çoğu zaman birkaç haftalık iştir, dört sistemi aynı anda bağlamaya çalışan proje ise aylarca "neredeyse bitti" durumunda kalır. Entegrasyonun kendisinden çok, karşı tarafın erişim açması, test ortamı vermesi ve veri temizliği beklenir; bu beklemeleri takvime baştan yazın.
Hazır paketinizin entegrasyon duvarına çarptığı noktada özel bir katman yazdırmak en pratik çözüm olabilir; bu seçeneği paket artı özel katman başlığında ele almıştık.
Entegrasyon ihtiyacınızı birlikte çıkarıp uygulamamızı isterseniz özel yazılım geliştirme hizmetimizi inceleyebilirsiniz; önce hangi akışın en çok zaman kaybettirdiğini ölçüyor, oradan başlıyoruz.
