API Entegrasyonu Nedir? İşletmeler İçin Sade Anlatım

İşletme sahipleriyle konuşurken en çok gözden kaçan kelime "API" oluyor. Teknik bir terim gibi durduğu için genelde yazılımcının işi sayılıyor; oysa API, bir işletmenin günlük hayatındaki en pahalı problemi çözer: aynı bilgiyi birden fazla yere elle girmek. Bu yazıda API'yi jargon kullanmadan, gerçek iş örnekleriyle anlatıyorum — ne olduğu, ne zaman gerektiği, neye mal olduğu ve nerede tuzakları olduğu dahil.

API aslında nedir? Sade bir tanım

API, iki yazılımın birbiriyle konuşması için açılmış resmi bir kapıdır. İnsan arayüzü değildir; ekran, buton, form yoktur. Bir program diğerine "bana bugünün siparişlerini ver" ya da "bu ürünün stoğunu 12 yap" der, karşı taraf da anlaşılmış bir formatta cevap verir.

Günlük hayattan benzetmesi şudur: restoranda mutfağa kendiniz girmezsiniz. Garsona ne istediğinizi söylersiniz, garson mutfağın anladığı dile çevirir, yemeği size getirir. API o garsondur — mutfağın (yani sistemin) iç işleyişini bilmenize gerek kalmadan, ondan belirli şeyleri isteyebilmenizi sağlar. Mutfak düzenini değiştirse bile garsonla konuşma şekliniz aynı kalır; iyi tasarlanmış bir API'nin değeri tam olarak buradadır.

Bir API'nin size vaat ettiği üç şey vardır: veriye erişmek, veriyi değiştirmek ve bir olaydan haberdar olmak. Entegrasyon dediğimiz iş de bu üçünün işletmenin ihtiyacına göre dizilmesinden ibarettir.

Entegrasyon ne zaman gerekir? Belirtiler

API entegrasyonu bir moda değil, bir ağrı kesicidir. Aşağıdaki cümlelerden ikisi sizde geçiyorsa entegrasyonun karşılığı vardır:

• "Aynı ürünü üç yere ayrı ayrı giriyoruz." Web sitesi, pazaryeri ve muhasebe programı için aynı bilgiyi tekrar yazmak, hem zaman hem hata demektir.
• "Stok tuttuğumuzu sanıyorduk, aslında tutmuyormuş." İki kanalda ayrı ayrı takip edilen stok, er ya da geç olmayan ürünü satmaya varır.
• "Gün sonunda siparişleri Excel'e döküyoruz." Elle rapor hazırlanan her süreç, aslında yazılmamış bir entegrasyonun faturasıdır.
• "Faturayı akşam toplu kesiyoruz." Satış ile fatura arasındaki her manuel adım, hem gecikme hem uyuşmazlık üretir.
• "Kargo takip numarasını müşteriye biz yazıyoruz." Kopyala-yapıştırla yürüyen her akış, kişi bağımlıdır; o kişi izne çıkınca durur.

Buna karşılık, günde beş sipariş alan ve tek kanaldan satan bir işletmede entegrasyon çoğu zaman erken bir yatırımdır. Karar ölçütü ciro değil, tekrar sayısıdır: bir işi haftada kaç kez, kaç kişi elle yapıyor?

İşletmelerde en sık kurulan entegrasyonlar

Aşağıdaki tablo, sahada en çok karşılaştığım entegrasyon tiplerini, çözdükleri problemi ve tipik zorluk seviyesini gösteriyor. Zorluk, kaynak sistemin API kalitesine göre değişir; tablo bir sıralama fikri vermek içindir.

Entegrasyon	Çözdüğü problem	Tipik zorluk	Kritik nokta
Pazaryeri ↔ mağaza stoğu	Olmayan ürünü satma riski	Orta	Tek doğru stok kaynağı belirlenmeli
Sipariş → muhasebe/fatura	Gün sonu elle fatura kesme	Orta	İade ve iptal senaryosu baştan düşünülmeli
Ödeme altyapısı	Ödeme durumunun elle kontrolü	Orta	Başarısız ödeme geri bildirimi
Kargo firması	Takip numarası girme, müşteri sorusu	Düşük-Orta	Barkod ve gönderi durumu eşleşmesi
WhatsApp / bildirim	"Siparişim ne oldu" mesajları	Düşük	Şablon onayı ve mesaj sıklığı
CRM / lead akışı	Formdan gelen talebin kaybolması	Düşük	Tekrarlayan kaydın engellenmesi
ERP ↔ e-ticaret	İki ayrı gerçeklik oluşması	Yüksek	Ürün kodu (SKU) disiplini

Pazaryeri tarafını daha ayrıntılı merak ediyorsan, stok ve sipariş akışını uçtan uca anlattığım Trendyol ve Hepsiburada entegrasyonu yazısına bakabilirsin.

Bir entegrasyon nasıl kurulur? Altı adım

İyi bir entegrasyon, kod yazmadan önce verilen kararlarla ayakta durur. İzlediğim sıra şu:

• 1. Gerçeğin kaynağını seçin. Stok, fiyat ve müşteri bilgisi için "hangi sistem haklı" sorusunu tek bir cevaba bağlayın. İki sistemin de haklı olduğu bir kurulum, kaçınılmaz olarak çelişki üretir.
• 2. Eşleştirme anahtarını netleştirin. Ürün için SKU, müşteri için telefon veya e-posta, sipariş için sipariş numarası. Anahtar disiplinsizse entegrasyon değil, karışıklık kurulur.
• 3. Yönü belirleyin. Veri tek yönde mi akacak, çift yönde mi? Çift yön daha güçlüdür ama çakışma kurallarını da yazmayı gerektirir.
• 4. Tetikleyiciyi seçin. Belirli aralıklarla sorgulama mı (periyodik kontrol), olay anında bildirim mi (webhook)? Webhook daha hızlıdır; periyodik kontrol daha affedicidir. Çoğu kurulumda ikisi birlikte kullanılır.
• 5. Hata davranışını tasarlayın. Karşı sistem cevap vermezse ne olacak? Tekrar denenecek mi, kaç kez, sonra kime haber verilecek? Bu adım atlandığında entegrasyon sessizce durur ve kimse fark etmez.
• 6. Test ortamında yürütün. Canlı veriyle ilk denemeyi yapmak, muhasebeye yanlış fatura düşürmenin en kestirme yoludur.

Teknik sözlük: duyacağınız beş terim

• Endpoint: API'nin belirli bir işi yapan adresi. "Siparişleri getir" ve "stok güncelle" ayrı endpoint'lerdir.
• Token / API anahtarı: Sistemin sizi tanımasını sağlayan gizli şifre. Sızarsa üçüncü kişi sizin adınıza işlem yapabilir; bu yüzden koda gömülmez, ayrı ve korumalı tutulur.
• Webhook: Siz sormadan karşı tarafın size haber vermesi. "Yeni sipariş geldi" bildirimi böyle çalışır.
• Rate limit: Birim zamanda kaç istek yapabileceğinizin sınırı. Aşarsanız sistem sizi geçici olarak durdurur; iyi yazılmış entegrasyon bunu bekler ve sırasını bekleyerek devam eder.
• Sandbox: Gerçek para ve gerçek stok olmadan denemenizi sağlayan test ortamı.

Sık yapılan hatalar

• Ürün kodu disiplini olmadan başlamak. Aynı ürünün iki sistemde farklı kodla durduğu bir yerde hiçbir entegrasyon düzgün çalışmaz. Entegrasyondan önceki iş, veriyi temizlemektir.
• Her şeyi tek seferde bağlamak. Yedi sistemi aynı anda devreye almak, bir sorun çıktığında kaynağı bulmayı imkânsızlaştırır. Tek akışla başlayıp genişletmek daha hızlı sonuç verir.
• İade ve iptali unutmak. Satış akışı kolaydır; işin zor tarafı geri dönen siparişte stok, fatura ve muhasebenin birlikte düzeltilmesidir.
• Log tutmamak. Kayıt tutmayan bir entegrasyonda "bu sipariş neden aktarılmamış" sorusunun cevabı yoktur.
• Anahtarları paylaşmak. API anahtarını e-posta ya da mesajla dolaştırmak, kapıyı açık bırakmakla aynı şeydir.
• Sahibini belirlememek. Entegrasyon bir kez kurulup unutulan bir şey değildir; karşı sistem sürümünü değiştirdiğinde güncellenmesi gerekir.

API yoksa ne yapılır?

Her sistemin API'si olmaz; özellikle yerel ve eski yazılımlarda bu sık karşılaşılan bir durumdur. Böyle hallerde üç seçenek kalır: sağlayıcıdan dosya tabanlı bir aktarım istemek (düzenli aralıklarla üretilen bir liste dosyası), varsa hazır bir aracı servis kullanmak ya da süreci elle yürütmeye devam edip yalnızca kontrolü otomatikleştirmek. Üçü de API kadar zarif değildir; ama "API yok" cümlesi, işi otomatikleştirmenin imkânsız olduğu anlamına gelmez. Otomasyonun genel mantığını işletmeler için iş otomasyonu yazısında ele almıştım.

Sık Sorulan Sorular

API entegrasyonu ne kadar sürer?

Tek yönlü ve tek akışlı basit bir bağlantı ile iki yönlü, çok kanallı bir kurulum arasında ciddi fark vardır. Süreyi belirleyen asıl unsur kod değil, veri düzenidir: ürün kodları temizse ve "hangi sistem haklı" sorusu cevaplanmışsa iş hızlanır; değilse süre büyük ölçüde temizliğe gider. Bu yüzden sağlıklı bir tahmin, ancak mevcut veri görüldükten sonra verilebilir.

Entegrasyon kurulduktan sonra bakım gerekir mi?

Evet. Bağlandığınız sistemler kendi API'lerini zaman zaman günceller, alan ekler, eski sürümü kapatır. Bakımsız bırakılan entegrasyon genellikle gürültüsüzce bozulur — ve bunu ilk fark eden çoğu zaman müşteri olur. Basit bir sağlık kontrolü ve hata bildirimi, bu riski büyük ölçüde kapatır.

Hazır entegrasyon servisi mi, özel geliştirme mi?

İhtiyacınız standart bir akışsa (örneğin yaygın bir mağaza altyapısı ile yaygın bir muhasebe programı arasında), hazır bir bağlayıcı hem hızlı hem ucuzdur. İş kuralınız kendine özgüyse — özel fiyatlama, çok depolu stok, kendi üretim akışınız — hazır çözümler bir yere kadar gider ve sonra sizi kendi kalıbına zorlar. Ben bu kararı "kuralımı yazılıma mı uyduracağım, yazılımı kuralıma mı" sorusuyla veriyorum.

API anahtarımı geliştiriciyle paylaşmak güvenli mi?

Doğru yapılırsa evet. Kural şudur: mümkünse yalnızca gereken yetkileri içeren ayrı bir anahtar üretilir, iş bitince veya kişi değişince anahtar yenilenir. Tam yetkili tek bir anahtarı herkese vermek ise güvenli değildir. Yetki sınırlandırma ve anahtar yenileme imkânı olan sistemleri tercih edin.

Küçük işletmenin API entegrasyonuna ihtiyacı var mı?

Ölçek değil, tekrar belirler. Haftada birkaç kez yapılan basit bir kopyala-yapıştır işi entegrasyonu hak etmeyebilir; her gün onlarca kez tekrar eden ve hata payı satışa zarar veren bir iş ise küçük işletmede daha kritiktir, çünkü hatayı telafi edecek yedek personeliniz yoktur.

Bisifirdan yaklaşımı

Ben entegrasyona kodla değil, iki soruyla başlıyorum: bu veri kimin elinde doğru duruyor ve bu iş günde kaç kez tekrar ediyor? Cevaplar netleşmeden yazılan entegrasyon, karışıklığı otomatikleştirmekten öteye gitmez. Önce tek bir akışı sağlam kuruyor, hatasını görünür hâle getiriyor, sonra üzerine ekliyorum. Amaç, sistemin siz bakmadığınızda da doğru çalışması — ve bozulduğunda bunu müşteriden önce sizin öğrenmeniz.

Kurduğum sistemlerin örneklerini İşler bölümünde, hangi hizmetleri nasıl verdiğimi ise Neler Yapıyorum bölümünde görebilirsin. Sipariş bildirimi tarafını merak ediyorsan WhatsApp sipariş ve chatbot entegrasyonu yazısı iyi bir başlangıç.

Hangi işi elle tekrar ettiğini anlat, birlikte bakalım: projeni İletişim bölümünden yaz, sıfırdan canlıya kendi başına çalışan bir akış kuralım.