API entegrasyonu, iki yazılımın birbirine veriyi insan eli değmeden göndermesini sağlayan bağlantıdır. Web formundan gelen talebin CRM'e düşmesi, siparişin kargoya ve muhasebeye kendiliğinden geçmesi bu bağlantının işidir. Aşağıda API'nin ne olduğunu, REST ile webhook farkını ve işletmelerin en sık kurduğu bağlantıları anlatıyoruz. Maliyeti ve süreyi belirleyen etkenler, anahtar güvenliği ve hata yönetimi de burada. Kendi sitemizin panelindeki Search Console ve Meta bağlantılarından örnek veriyoruz.
API nedir, entegrasyon ne demektir?
API (Uygulama Programlama Arayüzü), bir yazılımın başka bir yazılıma hangi veriyi hangi kuralla açtığını tanımlayan arayüzdür. Entegrasyon ise bu arayüzü kullanarak iki sistemi sürekli konuşturan yazılım parçasıdır. API'yi sağlayıcı yazar; entegrasyon işletmenin tarafında kurulur.
Bir kargo firmasının API'sini düşünelim. "Gönderi oluştur" isteğine alıcı adresi ve paket bilgisi gider. Yanıt olarak takip numarası döner, çoğu zaman JSON adlı düz bir metin biçiminde. İsteğin geçerli olması için bir kimlik anahtarı da eklenir.
Ayrım önemlidir, çünkü teklif görüşmelerinde sık karışır. "Bu yazılımın API'si var" cümlesi, entegrasyonun hazır olduğunu söylemez. Yalnızca bağlantının kurulabileceğini, kapının var olduğunu söyler. Kapıdan geçecek yazılımı birinin yazması, test etmesi ve bakımını yapması gerekir.
REST ile webhook arasındaki fark nedir?
REST'te sizin sisteminiz sorar, webhook'ta karşı taraf haber verir. REST, isteği alan tarafın yanıt döndüğü yaygın API biçimidir. Webhook ise bir olay olunca sağlayıcının sizin adresinize kendiliğinden gönderdiği bildirimdir.
Yeni siparişleri REST ile 15 dakikada bir sormak, günde 96 istek eder. Bu isteklerin çoğu boş döner ve sipariş en fazla 15 dakika gecikmeyle görülür. Aralığı kısaltmak gecikmeyi azaltır ama istek sayısını artırır; hız sınırına da daha çabuk yaklaşılır.
Webhook'ta istek yalnızca olay olunca gelir. Meta'nın belgesine göre bildirim POST isteğiyle gelir ve alıcıdan 200 OK yanıtı beklenir. Teslim başarısız olursa Meta, 36 saat boyunca azalan sıklıkla yeniden dener. Aynı bildirim iki kez gelebileceği için alıcı tarafın tekrarı ayıklaması gerekir.
| Ölçüt | REST ile sorgulama | Webhook |
|---|---|---|
| Kim başlatır | İşletmenin sistemi | Sağlayıcı |
| Gecikme | Sorgu aralığı kadar | Olay anında |
| Boş istek | Çok | Yok |
| Gereken | Zamanlanmış görev | Herkese açık bir alıcı adresi |
| Güvenlik adımı | Anahtar ile istek | Gelen bildirimin imzasını doğrulamak |
Projelerimizde ikisini birlikte kullanmayı öneriyoruz. Webhook olayı haber verir, ayrıntı REST ile çekilir. Gece çalışan bir REST sorgusu da gün içinde kaçan bildirimi yakalar (sağlayıcının tekrar süresi bitse bile).
İşletmelerde en sık hangi API entegrasyonları kurulur?
En sık kurulan bağlantılar satışın arkasındaki elle yapılan işleri taşır. Form, sipariş, ödeme, fatura, kargo ve mesaj bunların başında gelir. Her biri bir olayla tetiklenir ve belli bir veriyi taşır.
| Bağlantı | Taşıdığı veri | Tetikleyen olay |
|---|---|---|
| Web formu → CRM | Ad, telefon, talep | Form gönderimi |
| Ödeme altyapısı (sanal POS) | Ödeme sonucu | Ödeme onayı ya da reddi |
| E-ticaret → muhasebe ve e-fatura | Sipariş ve fatura bilgisi | Ödemenin onaylanması |
| E-ticaret → kargo | Gönderi ve takip numarası | Siparişin hazırlanması |
| Pazaryeri | Stok, fiyat, sipariş | Stok değişimi ya da yeni sipariş |
| WhatsApp ya da SMS | Bildirim mesajı | Sipariş ya da randevu durumu |
| Reklam dönüşümü | Form ve kayıt olayı | Başvurunun tamamlanması |
Formun CRM'e bağlanması çoğu işletmenin ilk entegrasyonudur. CRM'in kendisini CRM yazılımı geliştirme rehberimizde adım adım anlattık. Sipariş, stok ve muhasebe aynı sistemde toplanacaksa soru ERP'ye döner. İki yazılımın farkını ERP ile CRM karşılaştırmamızda ele aldık. Mesaj tarafı için WhatsApp Business API ve CRM bağlantısı yazımız var.
Reklam dönüşümü neden sunucudan gönderilir?
Tarayıcıdaki etiket engellenebilir; sunucudan giden olay bu kaybı kapatır. Meta'nın Dönüşüm API'si, reklamverenin sunucusundan Meta'ya doğrudan bağlantı kurar. Kendi sitemizde Meta Pixel ile birlikte bunu kullanıyoruz.
İki kaynaktan giden aynı olay iki kez sayılmamalıdır. Meta, olayları olay kimliği ve olay adı eşleşirse tekilleştiriyor. Eşleşmenin 48 saat içinde gelmesi gerekiyor. Sitemizde form başvurusu tarayıcıdan ve sunucudan aynı olay kimliğiyle gider. İkisi de yalnızca çerez onayından sonra çalışır.
Sunucudaki gönderimi ziyaretçiye yanıt döndükten sonra yapıyoruz. Meta geç yanıt verse bile form gönderen kişi beklemez. Her gönderimin sonucu kişisel veri içermeyen bir kayda yazılır; 30 günden eski kayıtlar silinir. Kurulumun ayrıntısını Dönüşüm API'si kurulum yazımızda anlattık.
API entegrasyonu işletmeye ne kazandırır?
Kazancın büyük kısmı zamandan ve hatasız veriden gelir. Hesabı basittir: aylık kazanılan süre = aylık kayıt sayısı × kayıt başına elle geçen süre. Hız ve tek kaynaktan veri de buna eklenir.
Ayda 300 sipariş alan ve her siparişi muhasebeye 3 dakikada giren bir işletmeyi düşünelim. 300 × 3 = 900 dakika eder, yani ayda 15 saat. Kargo kaydı da elle giriliyorsa süre aynı hesapla ikiye katlanır.
Zamanın yanında üç kazanç daha var:
- Hata: Elle kopyalanan adreste bir harf hatası, paketin geri dönmesine yeter.
- Hız: Form CRM'e saniyeler içinde düşer, satış ekibi talebi bekletmez.
- Tek kaynak: Stok tek yerde değişir, pazaryerinde biten ürün satılmaz.
Her bağlantı kârlı değildir. Ayda 20 kayıt ve kayıt başına 2 dakika, aylık 40 dakika eder. Böyle bir işte entegrasyonun bakım yükü, kazandırdığı süreyi aşabilir. Bizim önerimiz önce hacmi ölçmek, sonra karar vermektir.
Entegrasyonun maliyetini ve süresini ne belirler?
Maliyeti kodun uzunluğundan çok karşı tarafın API'si belirler. Belgelerin kalitesi, test ortamı, veri eşleme ve bağlantının yönü en büyük etkenlerdir. Aşağıdaki tablo hangi durumun işi kolaylaştırdığını gösteriyor.
| Etken | İşi kolaylaştırır | İşi uzatır |
|---|---|---|
| Belgeler | Güncel ve örnekli | Eksik ya da eski sürüme ait |
| Test ortamı | Ayrı deneme hesabı var | Yalnızca canlı hesap |
| Kimlik doğrulama | Kendiliğinden yenilenen belirteç | Elle yenilenen anahtar |
| Veri eşleme | Az alan, aynı kavramlar | Farklı ürün kodu, birim ve vergi yapısı |
| Yön | Tek yönlü aktarım | Çift yönlü eşitleme |
| Hız sınırı | Geniş kota | Dakikada az istek |
| Kullanım ücreti | Pakete dahil | İstek başına ya da aylık ücret |
Çift yönlü eşitleme tablonun en pahalı satırıdır. Aynı müşteri kaydı iki sistemde aynı anda değişirse hangisinin kazanacağına karar vermek gerekir. Bu kural yazılmadan kurulan bağlantı, veriyi sessizce ezer.
Süre tahmini için taşınacak alanlar ve hata senaryoları tek tek sayılmalıdır. "Kargo bağlantısı" tek kalem değildir. Gönderi oluşturma, iptal, iade ve takip ayrı işlerdir. Özel bir entegrasyon gerekiyorsa özel yazılım geliştirme sayfamızda nasıl çalıştığımızı anlattık.
API'si olmayan yazılımla ne yapılır?
API yoksa veri dosya ya da ara katman üzerinden taşınır. Yazılımın dışa aktardığı dosya zamanlanmış bir görevle okunabilir. Bu yol çalışır ama gecikmelidir ve dosya biçimi değişince kırılır.
Seçenekler kabaca üç tanedir. Birincisi düzenli dışa aktarılan CSV ya da Excel dosyasıdır. İkincisi, yazılımın izin verdiği durumda veritabanına salt okunur bağlantıdır. Üçüncüsü ekran otomasyonudur; arayüz her değiştiğinde bozulur ve son çare olarak kalmalıdır. Sağlayıcıya API'nin yol haritasında olup olmadığını sormak da ayrı bir adımdır.
API anahtarı nasıl güvende tutulur?
API anahtarı bir paroladır ve yalnızca sunucuda durmalıdır. Tarayıcıya giden koda ya da kod deposuna girmemelidir. Google da anahtarı kısıtlamayı, kullanılmayanı silmeyi ve düzenli yenilemeyi öneriyor.
Google'ın önerisi bir adım daha ileri gidiyor: mümkünse kalıcı anahtar yerine kısa ömürlü kimlik. Hizmet hesabı, bir kişiye değil uygulamaya ait olan hesaptır. Sitemizin panelindeki Search Console bağlantısı böyle bir hesapla çalışır. Sunucu imzalı bir istek gönderir, Google karşılığında bir saatlik erişim jetonu verir. Jeton süresi bitene kadar saklanır, sonra yenisi alınır.
Anahtarın kimin hesabında oluşturulduğu da önemlidir. Bizim önerimiz anahtarların işletmenin kendi hesabında açılmasıdır. Anahtar sizin hesabınızda olursa ajans ya da çalışan değişince erişim işletmede kalır. Her entegrasyona ayrı anahtar vermek de iyi bir alışkanlıktır; biri sızarsa yalnızca o kapatılır.
Hız sınırları ve hatalar nasıl yönetilir?
Her API belirli bir sürede belirli sayıda istek kabul eder. Sınır aşılınca sunucu genellikle 429 kodu döndürür. İyi bir entegrasyon hatayı türüne göre ayırır; ya bekler ya da bir insana haber verir.
Search Console API'de URL denetiminin kotası site başına günde 2000, dakikada 600 istektir. Arama analizi verisinde site başına dakikada 1200 sorgu sınırı var. Panelimizde performans verisini önbellekte tutuyoruz; panel her açıldığında Google'a yeniden sorulmaz. Google, kısa süreli kota aşımında 15 dakika bekleyip yeniden denemeyi öneriyor.
429 yanıtıyla birlikte Retry-After başlığı gelebilir. Başlık, yeniden denemeden önce ne kadar beklenmesi gerektiğini söyler. Entegrasyon bu süreye uymalıdır; hemen tekrar denemek sınırı uzatır.
| Yanıt | Anlamı | Ne yapılır |
|---|---|---|
| 200 | İstek başarılı | Sonuç kayda yazılır |
| 400 ya da 422 | Gönderilen veri hatalı | Tekrar denenmez, kayıt düzeltilir |
| 401 ya da 403 | Anahtar geçersiz ya da yetki yok | Bir insana haber verilir |
| 429 | Hız sınırı aşıldı | Retry-After kadar beklenir |
| 500'lü kodlar ya da zaman aşımı | Karşı taraf geçici sorunda | Artan aralıkla yeniden denenir |
Geçici hatalarda bizim kullandığımız kural, 1, 5 ve 30 dakika sonra üç denemedir. Üçüncüsü de başarısızsa kayıt bir insanın önüne düşer. Sipariş ve fatura gibi işlerde her isteğe benzersiz bir kimlik verilir. Böylece yeniden deneme aynı faturayı iki kez kesmez.
Hata mesajı da okunur olmalıdır. Panelimizdeki Meta bağlantısı, Meta'nın hata kodlarını Türkçe bir cümleye çeviriyor. Örneğin 190 kodu, "erişim belirteci geçersiz ya da süresi dolmuş" uyarısı olarak görünür ve yapılacak işi söyler.
Sağlayıcı API'sini değiştirince ne olur?
Sağlayıcılar yeni sürüm çıkarır ve eski sürümü bir süre sonra kapatır. Entegrasyon güncellenmezse bir gün sessizce durur. Meta, yeni Marketing API sürümü çıkınca eskisini en az 90 gün daha desteklediğini yazıyor.
Süre bitince eski sürüme yapılan çağrılar başarısız olabilir ya da bir sonraki sürüme yükseltilebilir. İkincisi daha sinsidir, çünkü hata vermeden farklı davranabilir. Bizim Dönüşüm API'si bağlantımız bugün v25.0 sürümünü kullanıyor. Sürüm numarası kodda tek bir yerde duruyor; yükseltme tek satırla başlar, testle biter.
Sürüm değişikliği dışında üç tür kırılma sık görülür. Bir alanın adı değişir, yeni bir alan zorunlu olur ya da kimlik doğrulama yöntemi değişir. Erken uyarı için sağlayıcının değişiklik günlüğünü izlemek gerekir. Günde bir kez çalışan basit bir sağlık kontrolü de bağlantının yaşadığını gösterir.
Sağlayıcının kendisi değişebilir; kargo firması ya da ödeme kuruluşu başkasıyla değiştirilir. Entegrasyonu iki katmanda yazmak burada işe yarar. İşin kuralları bir katmanda, sağlayıcıya özel kod ayrı bir katmanda durur. Sağlayıcı değişince yalnızca ikinci katman yeniden yazılır.
Entegrasyondan önce sağlayıcıya hangi sorular sorulmalı?
Yedi soru, entegrasyonun süresini ve riskini baştan gösterir. Cevapların çoğu sağlayıcının belgelerinde yazar. Yazmıyorsa bu da bir cevaptır.
- API belgeleri herkese açık mı, hangi sürüme ait?
- Ayrı bir test ortamı ya da deneme hesabı var mı?
- Kimlik doğrulama nasıl yapılıyor, anahtar ne kadar geçerli?
- Dakikalık ve günlük istek sınırı ne kadar?
- Webhook desteği var mı, başarısız bildirim yeniden gönderiliyor mu?
- API kullanımı ücretli mi, hangi pakette açık?
- Sürüm değişikliği ne kadar önceden duyuruluyor?
Yedi cevap elde olunca süre tahmini çok daha sağlam yapılır. Cevabı "bilmiyoruz" olan her soru, takvime eklenecek bir risk payıdır.
Sıkça sorulan sorular
- API entegrasyonu nedir?
- İki yazılımın birbirine veriyi insan eli değmeden göndermesini sağlayan bağlantıdır. API sağlayıcının kapısıdır, entegrasyon o kapıdan geçen yazılımdır.
- REST ile webhook arasındaki fark nedir?
- REST'te işletmenin sistemi sorar, webhook'ta sağlayıcı olay olunca haber verir. Webhook gecikmesizdir; REST ise kaçan bildirimi yakalamak için gece sorgusunda işe yarar.
- İşletmeler en sık hangi entegrasyonları kurar?
- Form ile CRM, ödeme altyapısı, muhasebe ve e-fatura en yaygın olanlardır. Kargo, pazaryeri, WhatsApp ya da SMS ve reklam dönüşümü bağlantıları da sık kurulur.
- API entegrasyonunun kazancı nasıl hesaplanır?
- Aylık kazanılan süre = aylık kayıt sayısı × kayıt başına elle geçen süre. Ayda 300 sipariş ve 3 dakika, ayda 15 saat eder.
- Entegrasyon maliyetini en çok ne etkiler?
- Karşı tarafın belgeleri, test ortamı, veri eşleme ve bağlantının yönü en büyük etkenlerdir. Çift yönlü eşitleme en pahalı türdür.
- API anahtarı nerede saklanmalı?
- Yalnızca sunucuda saklanmalıdır; tarayıcı koduna ve kod deposuna girmemelidir. Google ayrıca anahtarı kısıtlamayı ve düzenli yenilemeyi öneriyor.
- API 429 hatası ne demek?
- Hız sınırının aşıldığını gösterir. Retry-After başlığı varsa entegrasyon o süre kadar bekleyip yeniden dener.
- Sağlayıcı API sürümünü değiştirirse ne olur?
- Eski sürüm bir süre sonra kapanır ve entegrasyon güncellenmezse durur. Meta eski Marketing API sürümünü en az 90 gün daha destekliyor.
Kaynakça
- Getting Started - Webhooks - Meta for Developers — Webhook bildiriminin POST ile gelmesini, 200 OK beklenmesini, imza başlığını ve 36 saatlik yeniden denemeyi destekler.
- Handling Duplicate Pixel and Conversions API Events - Meta for Developers — Olay kimliği ve olay adıyla tekilleştirmeyi ve 48 saatlik süreyi destekler.
- Marketing API Versioning - Meta for Developers — Eski sürümün en az 90 gün desteklenmesini ve sonrasında çağrıların başarısız olabilmesini destekler.
- Usage limits - Search Console API — URL denetiminde günde 2000 ve dakikada 600, arama analizinde dakikada 1200 sınırını ve 15 dakika beklemeyi destekler.
- Best practices for managing API keys - Google Cloud — Anahtarı istemci koduna ve depoya koymamayı, kısıtlamayı, silmeyi ve düzenli yenilemeyi destekler.
- 429 Too Many Requests - MDN Web Docs — 429 kodunun hız sınırını ve Retry-After başlığının bekleme süresini bildirdiğini destekler.


