Tecof • 14 Eylül 2026
API Nedir? E-ticaret Entegrasyonlarında API Kullanımı
Kısaca
API (Application Programming Interface), iki yazılımın birbirine tanımlı bir sözleşmeyle veri alıp vermesini sağlayan arayüzdür. E-ticarette pazaryeri, kargo firması, sanal POS, muhasebe programı ve yapay zeka ajanı mağazanızla yalnızca API üzerinden konuşur. İyi kurulmuş bir API katmanı siparişin saniyeler içinde kargoya, stoğun anında pazaryerine, faturanın otomatik muhasebeye gitmesi demektir. Kötü kurulmuş olanı ise gece yarısı sessizce hata veren, kimsenin fark etmediği bir uç noktadır. 2026 itibarıyla soru "API'miz var mı" değil, "hangi işlemi kim, hangi yetkiyle, hangi sürümle çağırıyor" sorusudur.
Salı sabahı 09.10. Trendyol paneli bir üründen 14 adet satış gösteriyor, kendi sitenizde aynı üründen 9 adet stok görünüyor, depoda ise 3 adet var. Üç sistem üç farklı rakam söylüyor ve hiçbiri yalan söylemiyor; sadece birbirlerine haber vermemişler. Öğleye kadar iki müşteriye "ürün tedarik edilemiyor" mesajı gidecek, biri olumsuz yorum bırakacak.
Bu tablonun sebebi ne pazaryeri ne depo. Sebep, sistemlerin birbirine bağlanma biçimi. Stok bir yerde güncellendiğinde diğer ikisine kim, ne zaman, hangi yolla haber veriyor? Bu sorunun cevabı API'dir ve cevap eksikse ciro değil, güven kaybedersiniz.
API Nedir, E-ticarette Neye Karşılık Gelir?
API, bir yazılımın dışarıya açtığı tanımlı kapılar bütünüdür. Her kapının bir adresi, kabul ettiği bir istek biçimi ve döndürdüğü bir cevap biçimi vardır. Restoran benzetmesi işe yarar: mutfağa girmezsiniz, garsona menüden sipariş verirsiniz, garson mutfakla konuşur ve yemek gelir. Menü sözleşmedir, garson API'dir, mutfak ise karşı tarafın sistemidir.
E-ticaret için somutlaştıralım. Mağazanızın sipariş API'si "bana son 24 saatin siparişlerini ver" isteğine yapılandırılmış bir liste döner. Kargo firmasının API'si "bu adrese bu ağırlıkta gönderi oluştur" isteğine takip numarası döner. Sanal POS'un API'si "bu tutarı bu kartla tahsil et" isteğine onay ya da ret döner. Üçü de aynı mantıkla çalışır: istek gider, cevap gelir, ikisinin de biçimi önceden bellidir.
Mağaza sahibinin bilmesi gereken beş kavram
- Uç nokta (endpoint): tek bir işlemin adresi.
/orderssiparişleri,/products/123/stockbir ürünün stoğunu temsil eder. - Anahtar (API key / token): isteği kimin yaptığını kanıtlayan şifre. Yönetici parolanızla aynı şey değildir, ayrı üretilir ve ayrı iptal edilir.
- İstek limiti (rate limit): dakikada kaç istek atabileceğiniz. Kampanya günü aşıldığında entegrasyon sessizce durur.
- Webhook: siz sormadan karşı tarafın size haber vermesi. "Sipariş geldi" bilgisini her dakika sormak yerine, sipariş geldiğinde bildirim alırsınız.
- Sürüm (version): API'nin hangi baskısını kullandığınız. Sağlayıcı yeni sürüm çıkarıp eskisini kapattığında entegrasyonunuz durur.
Bu beş kavramı bilen bir mağaza sahibi, teknik ekibiyle ya da ajansıyla aynı dili konuşur ve "entegrasyon çalışmıyor" cümlesinin ardındaki gerçek sebebi sorabilir.
REST, webhook ve MCP: üç farklı konuşma biçimi
Bugün karşınıza üç tür arayüz çıkar. REST, siz sorduğunuzda cevap veren klasik yapıdır ve e-ticaret entegrasyonlarının büyük çoğunluğu bununla çalışır. Webhook, karşı tarafın olay olduğunda sizi aramasıdır ve sipariş, ödeme, kargo durumu gibi anlık işlerde REST'ten daha verimlidir. Model Context Protocol (MCP) ise yeni katman: bir yapay zeka ajanının mağazanızın fonksiyonlarını tanımlı parametrelerle çağırmasını sağlar. Ajan SQL yazmaz, veritabanına dokunmaz; sizin açtığınız araçları sizin koyduğunuz sınırda kullanır. Bu üçü rakip değil, üst üste binen katmanlardır.
| Biçim | Kim başlatır | Ne için uygun | Zayıf noktası |
|---|---|---|---|
| REST API | Siz sorarsınız | Katalog çekme, toplu stok güncelleme, rapor | Sık sormak limit yer, gecikme yaratır |
| Webhook | Karşı taraf haber verir | Yeni sipariş, ödeme onayı, kargo teslim | Bildirim kaçarsa yeniden deneme gerekir |
| MCP | Yapay zeka ajanı çağırır | Ürün açıklaması yazma, stok analizi, kampanya kurma | Yetki sınırı tanımlanmazsa risk büyür |
Bir Siparişin API Üzerinden Yolculuğu
Entegrasyonun ne işe yaradığını görmenin en kısa yolu, tek bir siparişin hangi kapılardan geçtiğini izlemektir. Aşağıdaki akış orta ölçekli, kendi sitesi ve iki pazaryeri olan bir mağaza için tipiktir.
Sipariş öncesi: katalog ve stok
Ürün bilgisi tek kaynakta tutulur ve pazaryerlerine API ile gönderilir. Fiyat değiştiğinde tek yerden güncellenir, üç panele ayrı ayrı girilmez. Stok her satışta düşer ve düşen stok diğer kanallara webhook ile anında iletilir. Ürün kodlaması tutarsızsa bu akış ilk adımda kırılır; düzgün bir SKU yapısı API entegrasyonunun ön koşuludur, sonradan eklenen bir iyileştirme değil.
Sipariş anı: ödeme ve doğrulama
Müşteri ödeme adımına geldiğinde sanal POS API'si devreye girer. Tutar, taksit ve kart bilgisi şifreli olarak gider, onay saniyeler içinde döner. 3D Secure adımı bu akışın parçasıdır ve doğru kurulmadığında sepet terki belirgin biçimde artar. Onay geldiği anda sipariş kaydı oluşur, stok rezerve edilir ve müşteriye sipariş e-postası tetiklenir.
Sipariş sonrası: kargo, fatura ve muhasebe
Sipariş oluştuğunda kargo API'sine gönderi isteği gider, takip numarası döner ve etiket basılır. E-fatura API'si faturayı keser. Muhasebe programı satışı kaydeder. Kargo durumu değiştikçe webhook'lar müşteri bildirimlerini tetikler. Bu zincirin tamamı insan eli değmeden dakikalar içinde tamamlanır; elle yapıldığında sipariş başına on ile on beş dakika arasıdır. Depo tarafındaki kurgunun ayrıntısı için lojistik ve depo yönetimi rehberi tamamlayıcı bir okuma.
| Adım | Kullanılan API | Elle süre | Entegre süre |
|---|---|---|---|
| Stok senkronu (3 kanal) | Pazaryeri ürün API'leri | Günde 1-2 saat | Anlık |
| Ödeme tahsilatı | Sanal POS API | Uygulanamaz | 3-5 saniye |
| Kargo etiketi | Kargo API | Sipariş başına 4 dk | Anlık |
| E-fatura | E-fatura entegratör API | Sipariş başına 3 dk | Anlık |
| Muhasebe kaydı | Muhasebe API | Haftalık toplu 2 saat | Anlık |
Günde 60 sipariş alan bir mağazada yalnızca kargo etiketi ve fatura kalemi, ayda kabaca 210 saatlik insan emeğine denk gelir. Bu emek, entegrasyon kurulduğunda müşteri hizmetine ve ürün geliştirmeye döner.
Türkiye'de En Sık Kurulan Entegrasyonlar ve Kırıldıkları Yerler
Entegrasyon konuşmaları genellikle "hangi platformlar destekleniyor" sorusuyla başlar ve orada biter. Asıl soru, entegrasyonun hangi koşulda kırıldığı ve kırıldığında bunu kimin fark ettiğidir. Aşağıdaki başlıklar sahada en sık karşılaşılan sorunları özetliyor.
Pazaryeri entegrasyonları
Trendyol ve Hepsiburada API'leri kategori özniteliklerini zorunlu tutar; eksik öznitelikle gönderilen ürün sessizce reddedilir ve siz reddi ancak paneli açınca görürsünüz. İstek limitleri kampanya günlerinde en çok bu tarafta aşılır. Fiyat ve stok gönderimini toplu (batch) yapan entegrasyon, tek tek gönderen entegrasyona göre hem limiti daha az yer hem daha hızlı tamamlanır. Pazaryerinin kampanya kuralları API'nin dışında, sözleşmenin içindedir; entegrasyon fiyatı düşürebilir ama düşürmesi gerekip gerekmediğini bilmez.
Kargo entegrasyonları
Yurtiçi, Aras, MNG ve Sürat gibi firmaların API'leri farklı adres formatı, farklı desi hesabı ve farklı hata kodu kullanır. En sık kırılma noktası, tek bir firmanın uç noktasının haftalarca hata döndürmesi ve kimsenin bakmamasıdır. Çözüm teknik değil, operasyoneldir: her kargo firması için günlük başarı oranını ölçen basit bir sayaç. Yüzde 100'den yüzde 92'ye düşen bir sayaç, gelecek haftanın şikayetlerini bugünden gösterir.
Ödeme ve e-fatura
Sanal POS tarafında en yaygın hata, test ortamı anahtarının canlıya taşınmasıdır: ödemeler başarılı görünür ama para hesaba geçmez. E-fatura tarafında ise GİB entegratörünün mükellef listesi günlük güncellenir; e-arşiv mi e-fatura mı kesileceği API'den sorgulanmalıdır, elle karar verilirse hatalı belge çıkar. Bu iki entegrasyon hata affetmez, o yüzden test siparişi her ay verilmesi gereken bir rutin olmalıdır.
Muhasebe ve ERP
Logo, Mikro, Netsis gibi sistemlerde alan eşlemesi (mapping) en çok zaman alan iştir. "Müşteri adı" sizde tek alan, ERP'de ad ve soyad olarak iki alan olabilir. Eşleme bir kez doğru yapılır ve dokümante edilir; dokümante edilmezse ekipten biri ayrıldığında kimse dokunamaz. Altyapı seçerken bu entegrasyonların hazır gelip gelmediğini sormak, sonradan ödenecek en büyük faturayı önler; altyapı seçiminde yapılan hatalar yazısında bu maliyeti ayrıntılı ele almıştık.
Hazır Entegrasyon mu, Özel Geliştirme mi?
Her mağaza bu ikilemle karşılaşır. Hazır entegrasyon hızlı kurulur ve bakımı sağlayıcıya aittir; özel geliştirme ise sizin iş akışınıza birebir uyar ama bakımı size kalır. Doğru cevap çoğu zaman ikisinin karışımıdır: yaygın entegrasyonlar hazır, size özgü iş kuralları API üzerinden özel.
| Ölçüt | Hazır entegrasyon | Özel geliştirme (API ile) |
|---|---|---|
| Kurulum süresi | Saatler, en fazla günler | Haftalar |
| Başlangıç maliyeti | Düşük, çoğu pakete dahil | Geliştirici gün maliyeti |
| Sürüm değişiminde | Sağlayıcı günceller | Siz güncellersiniz |
| Özel iş kuralı | Sınırlı | Tam esneklik |
| Uygun olduğu durum | Pazaryeri, kargo, POS, e-fatura | Özel fiyatlama, B2B akışı, ERP eşlemesi |
Karar verirken sorulacak tek soru şu: bu entegrasyon üç yıl sonra da çalışıyor olacak mı ve o gün kim bakacak? Cevap "bilmiyorum" ise özel geliştirmeye girmeyin. Tecof entegrasyonlar sayfasında hangi bağlantıların hazır geldiğini, hangilerinin API üzerinden genişletilebildiğini görebilirsiniz.
Yapay Zeka Ajanları ve API: Yeni Katman
API'nin son iki yıldaki en büyük değişimi, çağıranın artık yalnızca yazılım değil, yapay zeka ajanı olmasıdır. Ajan "stoğu beşin altına düşen ürünleri listele ve reklamlarını duraklat" gibi bir hedefi, mağazanızın API'sini ve reklam platformunun API'sini sırayla çağırarak yerine getirir. Bunun için API'nin ajana açık olması, yani fonksiyonların tanımlı parametrelerle sunulması gerekir. MCP tam olarak bu sözleşmeyi standartlaştırır.
Ajan çağrılarında yetki sınırı
Ajanın kullandığı anahtar yönetici anahtarı olmamalı. Ajana kendi kullanıcısı açılır, yalnızca ihtiyaç duyduğu uç noktalara yetki verilir, her çağrı loglanır. Fiyat güncelleme fonksiyonuna yüzde 15 sınırı koyduysanız, ajan ne kadar ısrarcı olursa olsun yüzde 40 indirim yazamaz. Bu kurgunun ayrıntısı ajanik ticareti anlattığımız rehberde yetki matrisiyle birlikte var. Tecof'ta CMS, katalog, sipariş ve analitik dahil yetmişin üzerinde araç tanımlı yetki sınırlarıyla ajanlara açılabiliyor.
KVKK ve veri asgariliği
API üzerinden yurt dışındaki bir modele veri gönderiyorsanız kişisel veri aktarımı yapıyorsunuz demektir. Kargo süresi tahmini için ilçe yeterlidir, ad soyad ve bina numarası değil. Aydınlatma metninizde otomatik karar mekanizmalarına yer verin, veri işleyen listesine model sağlayıcısını ekleyin, API loglarını saklama politikanıza dahil edin. Ticari ileti gönderen her entegrasyon İYS kontrolünü API'den yapmalıdır; onay yoksa mesaj gitmez.
Yeni Bir Entegrasyonu 30 Günde Ayağa Kaldırmak
Entegrasyon projeleri genellikle "geliştirici bağlar, biter" diye planlanır ve üçüncü ayda hâlâ test aşamasındadır. Aşağıdaki takvim, tek bir entegrasyon (örneğin yeni bir kargo firması) için gerçekçi bir sıradır.
1-7. gün: sözleşmeyi ve dokümanı okuyun
API dokümanını açın ve üç şeye bakın: istek limiti, sürüm politikası ve hata kodları listesi. Sağlayıcının test ortamı var mı, test anahtarı nasıl alınıyor? Bu haftada tek satır kod yazılmaz; yazılırsa ikinci haftada silinir.
8-14. gün: test ortamında uçtan uca akış
Tek bir test siparişini baştan sona geçirin: gönderi oluştur, takip numarası al, durum güncellemesini webhook ile yakala, iptal senaryosunu dene. Hata kodlarının her birine ne yapılacağını yazın. "Adres bulunamadı" hatası bir insana mı düşecek, otomatik mi düzeltilecek?
15-21. gün: gölge modda canlı
Entegrasyonu canlı veriyle çalıştırın ama eski yöntemi de sürdürün. İki yöntemin sonucunu her gün karşılaştırın. Fark sıfıra inmeden eski yöntemi kapatmayın. Bu hafta genellikle veri kalitesi sorunlarını ortaya çıkarır: eksik posta kodu, hatalı desi, yanlış il-ilçe eşlemesi.
22-30. gün: izleme ve devir
Günlük başarı oranı sayacını kurun, eşiğin altına düştüğünde kime bildirim gideceğini yazın. Anahtarların nerede saklandığını, kim tarafından üç ayda bir yenileneceğini not edin. Entegrasyonu kuran kişi ile işleten kişi farklıysa devir belgesi hazırlayın. Eski yöntemi ancak bu adımdan sonra kapatın.
Yarın sabah yapabileceğiniz iş şu: panelinizdeki aktif entegrasyonları tek bir tabloya yazın; her biri için hangi API sürümünü kullandığını, anahtarın en son ne zaman yenilendiğini ve son 7 gündeki hata sayısını yanına ekleyin. Sürümü ya da anahtar tarihini bilmediğiniz satır, önümüzdeki ay sizi arayacak entegrasyondur. Entegrasyonları hazır gelen bir e-ticaret altyapısında bu tablo panelden hazır çıkar.
Sıkça Sorulan Sorular
API ile entegrasyon aynı şey mi?
Hayır. API kapıdır, entegrasyon o kapıyı kullanarak kurulan bağlantıdır. Bir kargo firmasının API'si olması, mağazanızın o firmayla entegre olduğu anlamına gelmez; birinin o API'yi sizin sisteminize bağlaması gerekir. Hazır entegrasyon bu bağlamayı sizin yerinize yapılmış hali, özel geliştirme ise sizin yaptırdığınız halidir.
Kod bilmeden API kullanabilir miyim?
Doğrudan API çağırmak için kod ya da en azından teknik bir araç gerekir. Ancak hazır entegrasyonlar ve yapay zeka ajanları bu ihtiyacı büyük ölçüde ortadan kaldırdı. Doğal dille "Yurtiçi Kargo'yu bağla" diyebildiğiniz bir altyapıda API arka planda çağrılır, siz sonucu görürsünüz. Kod bilgisi, özel iş kuralı yazdırırken devreye girer.
API anahtarımı kiminle paylaşabilirim?
Yönetici anahtarını kimseyle paylaşmayın. Ajansa, geliştiriciye ya da yapay zeka ajanına ayrı anahtar üretin, yalnızca gereken yetkiyi verin ve iş bittiğinde iptal edin. Anahtar e-posta ya da mesajla gönderilmez; sağlayıcının panelinden doğrudan tanımlanır. Üç ayda bir yenileme rutini kurun.
Webhook ile sürekli sorgulama arasında hangisini seçmeliyim?
Olay bazlı işlerde (yeni sipariş, ödeme onayı, kargo teslim) webhook; toplu işlerde (gece katalog senkronu, haftalık rapor) sorgulama. Webhook kaçırılabilir, o yüzden sorgulamayı yedek olarak saatte bir çalıştırmak iyi bir alışkanlıktır. İkisini birlikte kullanan yapı en dayanıklısıdır.
Pazaryeri API limiti aşılınca ne olur?
Sağlayıcı istekleri reddeder ve entegrasyon durur; çoğu zaman sessizce. Kampanya günlerinde stok gönderiminin durması, stoksuz ürün satışı demektir. Çözüm, gönderimleri toplu yapmak, yalnızca değişen kayıtları göndermek ve limit hatasında otomatik yeniden deneme kurmaktır. Limitin ne olduğunu kampanyadan önce öğrenin.
API sürümü değişince entegrasyonum bozulur mu?
Sağlayıcı eski sürümü kapatırsa evet. Ciddi sağlayıcılar aylar önceden duyurur; duyuruyu takip eden biri yoksa duyuru bir işe yaramaz. Hazır entegrasyonlarda güncelleme sağlayıcıya aittir, özel geliştirmede size. Sözleşmede sürüm destek süresinin yazılı olmasını isteyin.
MCP nedir, REST API'nin yerini mi alıyor?
Hayır, üstüne geliyor. REST yazılımlar arası konuşmanın standardı olmaya devam ediyor. MCP, bir yapay zeka ajanının aynı fonksiyonları tanımlı parametrelerle çağırmasını standartlaştırıyor. Mağaza tarafındaki karşılığı şu: fonksiyonlarınızı bir kez doğru tanımlarsanız hem yazılımlar hem farklı ajanlar aynı araçları kullanabilir.
Entegrasyon hatasını kim fark eder?
Kurulum yapılırken bu soru cevaplanmadıysa cevap "müşteri" olur. Her entegrasyon için günlük başarı oranı sayacı, eşiğin altına düşünce bildirim ve bildirimin gideceği bir isim tanımlayın. Bu üç adım teknik değil, operasyoneldir ve çoğu mağazada eksiktir.
Küçük bir mağaza için API entegrasyonu gerekli mi?
Günde beş sipariş alan bir mağazada kargo etiketini elle basmak sorun değildir. Elli siparişte sorun olur. Eşik, tekrar eden işin haftada kaç saat yediğidir. Haftada beş saati geçen her tekrar iş, entegrasyon için yeterli gerekçedir. Hazır entegrasyonlar bu eşiği küçük mağazalar için de erişilebilir hale getirdi.