API Entegrasyonu Rehberi: İş Süreçlerini Güvenle Otomatikleştirin
API entegrasyonu ile e-ticaret, muhasebe, kargo, ödeme ve CRM sistemlerini birbirine bağlamadan önce bilmeniz gerekenler: REST, webhook, kimlik doğrulama, veri eşleştirme, hata yönetimi, idempotency, güvenlik, izleme ve kontrol listesi.
Bu içeriği farklı bir yapay zekâ aracında özetleyin
Seçtiğiniz araç, yazının adresiyle hazırlanmış bir özet isteğiyle yeni sekmede açılır.
API entegrasyonu, iki veya daha fazla yazılımın tanımlı bir arayüz üzerinden otomatik olarak veri alıp vermesini sağlayan bağlantıdır. E-ticaret sitesi, muhasebe programı, kargo, ödeme ve CRM gibi sistemler bu sayede elle aktarım olmadan konuşur. Sağlıklı bir entegrasyon; veri eşleştirme, hata yönetimi, güvenlik ve izleme planlamasıyla kurulur.
Birçok işletmede gün, sistemler arasında veri taşımakla geçer. Web sitesine düşen sipariş muhasebe programına elle girilir, kargo takip numarası kargo panelinden kopyalanıp müşteriye e-postayla gönderilir, depodaki stok sayısı akşamları bir hesap tablosundan siteye işlenir. Her elle aktarım hem zaman alır hem de yazım hatası, gecikme ve unutulan kayıt riski taşır. İşletme büyüdükçe bu yük de artar.
Bu rehber, entegrasyon kararını vermeden ve bir yazılım ekibiyle konuşmadan önce bilmeniz gereken temel kavramları ve planlama adımlarını anlatıyor. API'nin ne olduğu, REST ve webhook farkı, kimlik doğrulama yöntemleri, tipik entegrasyon senaryoları, veri eşleştirme ve tek doğru kaynak ilkesi, senkron ve asenkron çalışma, hata yönetimi, yeniden deneme, idempotency, oran sınırları, kayıt ve izleme, güvenlik, test ortamı, sürüm değişiklikleri, dokümantasyon ve bakım konularını sırayla ele alıyoruz. Yazının sonunda hazır eklenti ile özel entegrasyonu karşılaştıran bir tablo ve entegrasyon öncesi kontrol listesi bulunuyor.
API Nedir ve Entegrasyonda Ne İşe Yarar?
API (Application Programming Interface, uygulama programlama arayüzü), bir yazılımın başka yazılımlara hangi işlemleri, hangi kurallarla sunduğunu tanımlayan sözleşmedir. Bir restoranın menüsüne benzetilebilir: mutfağın nasıl çalıştığını bilmenize gerek yoktur, menüde yazanı doğru biçimde sipariş ettiğinizde tanımlı bir sonuç alırsınız. Muhasebe programının API'si "fatura oluştur", "cari hesap sorgula" gibi işlemleri; kargo firmasının API'si "gönderi oluştur", "gönderi durumunu sorgula" gibi işlemleri dışarıya açar.
Entegrasyon ise bu arayüzleri kullanarak iki sistemi bir iş sürecine göre bağlamaktır. API tek başına bir yetenektir; entegrasyon, bu yeteneğin sizin süreçlerinize uygun kurallarla kullanılmasıdır. Aynı API ile çok farklı entegrasyonlar kurulabilir. Bu nedenle "karşı sistemin API'si var" bilgisi, işin yalnızca başlangıcıdır.
REST API nasıl çalışır?
İşletme yazılımlarında en sık karşılaşılan yaklaşım REST'tir. REST yaklaşımında her kaynak (sipariş, ürün, müşteri) bir adresle temsil edilir ve bu kaynak üzerinde HTTP yöntemleriyle işlem yapılır:
- GET: Veri okuma, örneğin bir siparişin ayrıntılarını almak
- POST: Yeni kayıt oluşturma, örneğin yeni bir gönderi açmak
- PUT veya PATCH: Mevcut kaydı güncelleme, örneğin stok miktarını değiştirmek
- DELETE: Kaydı silme veya iptal etme
Veri genellikle JSON biçiminde taşınır. Sunucu her isteğe bir HTTP durum koduyla cevap verir. Bu kodlar, işlemin başarılı olup olmadığını ve başarısızsa nedenini anlamanın ilk ipucudur. Durum kodlarının anlamlarına MDN HTTP durum kodları sayfasından ulaşabilirsiniz.
Bazı sistemler REST yerine SOAP gibi XML tabanlı eski protokolleri veya GraphQL gibi farklı sorgu yaklaşımlarını kullanır. Kavramlar büyük ölçüde aynıdır: bir istek gönderilir, bir cevap alınır ve bu alışverişin kuralları dokümante edilmiştir.
Webhook nedir, API'den farkı ne?
Klasik API kullanımında sizin sisteminiz karşı tarafa sorar: "Yeni sipariş var mı?" Bu soruyu belirli aralıklarla tekrar etmeye yoklama (polling) denir. Webhook ise yönü tersine çevirir. Karşı sistem, bir olay gerçekleştiğinde (sipariş oluştu, ödeme onaylandı, kargo teslim edildi) sizin belirlediğiniz bir adrese kendiliğinden bildirim gönderir.
Webhook, gereksiz sorgu trafiğini azaltır ve olaylara daha hızlı tepki vermeyi sağlar. Ancak kendi sorumlulukları vardır: bildirimi alacak adresin her zaman erişilebilir olması, gelen isteğin gerçekten beklenen sistemden geldiğinin doğrulanması ve aynı bildirimin birden fazla gelmesi durumunda işlemin tekrarlanmaması gerekir. Pek çok sağlam entegrasyon iki yöntemi birlikte kullanır: olaylar webhook ile anında alınır, belirli aralıklarla yapılan bir mutabakat sorgusu ise kaçan bildirimleri yakalar.
Kimlik doğrulama: API anahtarı ve OAuth
Bir API, isteği kimin gönderdiğini bilmek ister. En sık kullanılan iki yöntem şunlardır:
- API anahtarı: Karşı sistemin size verdiği uzun ve gizli bir değerdir. Her isteğe genellikle bir HTTP başlığı içinde eklenir. Kurulumu basittir, ancak anahtar ele geçirilirse sahibinin tüm yetkileriyle kullanılabilir. Bu nedenle anahtarın saklanması ve gerektiğinde yenilenmesi önemlidir.
- OAuth 2.0: Kullanıcının ya da uygulamanın, parolasını paylaşmadan sınırlı bir erişim izni vermesini sağlayan yetkilendirme çerçevesidir. Sonuçta kısa ömürlü bir erişim belirteci (access token) üretilir; süresi dolduğunda, kullanılan akışa bağlı olarak yenileme belirteciyle (refresh token) ya da yeniden yetkilendirmeyle yenisi alınır. Sistemden sisteme kullanılan client credentials akışında genellikle yenileme belirteci verilmez. İzinler kapsamlarla (scope) sınırlandırılabilir; örneğin yalnızca siparişleri okuma izni verilip ürün düzenleme izni verilmeyebilir.
Bazı sistemler kullanıcı adı ve parola ile oturum açılıp kısa süreli belirteç alınmasını, bazıları ise istemci sertifikası veya imzalı istekleri kullanır. Hangi yöntemin kullanılacağını karşı sistemin dokümantasyonu belirler. Entegrasyon planında belirteç yenileme mantığının da ele alınması gerekir; aksi halde entegrasyon, belirtecin süresi dolduğu gün sessizce durabilir.
İşletmelerde Tipik API Entegrasyonu Senaryoları
Entegrasyon ihtiyacı çoğu zaman bir süreçteki tekrar eden elle aktarımdan doğar. Aşağıdaki senaryolar birçok işletmede karşılaşılan örneklerdir; her işletmenin ihtiyacı farklı kurgulanabilir.
E-ticaret ile muhasebe veya ERP
Web sitesinden gelen siparişlerin muhasebe ya da ERP programına aktarılması, en yaygın entegrasyon ihtiyacıdır. Bu senaryoda sipariş, müşteri (cari hesap), ürün satırları, vergi oranları, indirimler ve kargo bedeli gibi bilgiler aktarılır. Ters yönde ise stok miktarları, ürün kartları ve bazen satış tutarları muhasebe tarafından siteye gönderilir. Belge oluşturma (fatura veya irsaliye) gibi resmî süreçlerin hangi sistemde ve hangi aşamada tetikleneceği, muhasebe sorumlunuzla birlikte netleştirilmelidir.
Kargo entegrasyonu
Sipariş hazırlandığında kargo firmasının sisteminde gönderi kaydı açılması, barkod veya etiket bilgisinin alınması, takip numarasının siparişe ve müşteriye iletilmesi, teslim durumunun geri okunması bu senaryonun tipik adımlarıdır. Birden fazla kargo firmasıyla çalışılıyorsa, firmaların veri yapıları farklı olacağı için her biri için ayrı eşleştirme yapılması gerekir.
Ödeme altyapısı
Ödeme sağlayıcısıyla entegrasyon genellikle hazır modüllerle yapılır; ancak ödeme sonucunun siparişe doğru işlenmesi, iade ve iptallerin muhasebeye yansıması, taksit veya komisyon bilgilerinin raporlanması gibi konular ek çalışma gerektirebilir. Ödeme sonucunu bildiren webhook'lar, bu senaryoda en dikkatli doğrulanması gereken isteklerdir.
CRM ve müşteri iletişimi
Web sitesindeki formlar, teklif talepleri veya sipariş geçmişi CRM aracına aktarılarak satış ekibinin tek ekrandan müşteri görmesi sağlanabilir. Bu senaryoda kişisel veri yoğun biçimde aktarıldığı için KVKK kapsamında hangi verinin hangi amaçla aktarıldığı değerlendirilmelidir.
Stok ve çok kanallı satış
Aynı ürün hem web sitesinde hem pazaryerlerinde hem de mağazada satılıyorsa, stok miktarının tüm kanallarda tutarlı tutulması gerekir. Burada gecikme doğrudan satış kaybına veya karşılanamayan siparişe dönüşebilir. Bu nedenle stok entegrasyonunda aktarım sıklığı ve çakışma kuralları özellikle önemlidir.
E-posta ve bildirim servisleri
Sipariş onayı, kargo bildirimi, şifre sıfırlama veya kampanya e-postaları için harici bir e-posta servisinin API'sini kullanmak, gönderimin izlenmesini ve teslim edilebilirliğin yönetilmesini kolaylaştırır. Pazarlama amaçlı iletiler için izin yönetiminin de entegrasyon kapsamında düşünülmesi gerekir.
Veri Eşleştirme ve Tek Doğru Kaynak
Bir entegrasyonun en çok emek isteyen kısmı çoğu zaman bağlantının kendisi değil, verinin bir sistemden diğerine anlamını kaybetmeden taşınmasıdır. İki sistem aynı kavramı farklı biçimde tutabilir.
Veri eşleştirmede karşılaşılan tipik farklar şunlardır:
- Kimlikler: Web sitesindeki ürün kimliği ile muhasebedeki stok kodu farklıdır. Hangi alanın eşleştirme anahtarı olacağı belirlenmelidir.
- Birimler: Bir sistem adet, diğeri koli veya kilogram tutuyor olabilir.
- Vergi: Vergi oranlarının, vergi dâhil veya hariç tutarların iki sistemde nasıl gösterildiği eşleşmelidir.
- Ondalık ve yuvarlama: Satır bazında ve toplamda yapılan yuvarlamalar farklıysa, kuruş farkları oluşur.
- Tarih ve saat dilimi: Bir sistem yerel saat, diğeri UTC kullanıyorsa, gün sonu raporlarında kayıtlar yanlış güne düşebilir.
- Durum değerleri: "Hazırlanıyor", "kargoda", "tamamlandı" gibi durumların karşı sistemdeki karşılıkları tek tek eşleştirilmelidir.
- Karakterler ve uzunluk: Türkçe karakterler, alan uzunluk sınırları ve zorunlu alanlar farklı olabilir.
Bu eşleştirmeleri bir tablo hâlinde belgelemek, hem geliştirme hem de ileride yapılacak değişiklikler için temel kaynak olur.
Tek doğru kaynak ilkesi
Her veri türü için hangi sistemin "asıl" kabul edileceğine karar verin. Örneğin ürün adı ve açıklaması web sitesinde, stok miktarı ve vergi bilgisi muhasebe programında, müşteri iletişim tercihleri CRM aracında asıl olabilir. Bu karar verilmezse iki sistem aynı alanı karşılıklı olarak güncellemeye çalışır ve en son kim yazdıysa onun değeri geçerli olur. Sonuç, kimsenin güvenmediği bir veri kümesidir.
Tek doğru kaynak ilkesi, aynı zamanda elle düzenlemenin nerede yapılacağını da belirler. Stok muhasebede asılsa, sitede stok elle düzeltilmemeli; düzeltme muhasebede yapılıp entegrasyonla siteye yansımalıdır. Bu kuralın kullanıcılara açıkça anlatılması, teknik çözüm kadar önemlidir.
Örneğin yedek parça satan bir e-ticaret mağazası düşünelim. Ürün kartları ve stok muhasebe programında tutuluyor, siparişler web sitesinden geliyor, kargo ise tek bir firmayla gönderiliyor. Bu mağaza için makul bir kurgu şudur: stok ve ürün kartı muhasebeden siteye belirli aralıklarla aktarılır; sipariş, ödeme onaylandığında siteden muhasebeye gönderilir; sipariş hazırlandığında kargo kaydı açılır ve takip numarası siteye geri yazılır. Her ok tek yönlüdür ve her verinin sahibi bellidir.
Senkron ve Asenkron Entegrasyon
Senkron entegrasyonda bir sistem karşı tarafa istek gönderir ve cevabı bekler; işlem ancak cevap geldiğinde devam eder. Asenkron entegrasyonda ise istek bir kuyruğa bırakılır, arka planda işlenir ve sonuç daha sonra kaydedilir veya bildirilir.
| Özellik | Senkron | Asenkron |
|---|---|---|
| Çalışma biçimi | İstek gönderilir, cevap beklenir | İş kuyruğa alınır, arka planda işlenir |
| Uygun olduğu durumlar | Anlık cevap gereken işlemler, örneğin ödeme sonucu veya kargo ücreti sorgusu | Yoğun veya bekleyebilen işler, örneğin sipariş aktarımı, toplu stok güncellemesi |
| Karşı sistem yavaşsa | Kullanıcı veya süreç bekler | Kuyruk birikir, kullanıcı etkilenmez |
| Karşı sistem kapalıysa | İşlem hata verir | İş daha sonra yeniden denenir |
| Karmaşıklık | Daha basit kurulur | Kuyruk, işçi süreç ve izleme gerektirir |
Pratikte iki yöntem birlikte kullanılır. Müşteri ödeme yaparken ödeme sağlayıcısının cevabını beklemek zorunludur. Ancak siparişin muhasebeye aktarılması için müşterinin bekletilmesine gerek yoktur; bu iş kuyruğa alınabilir. Muhasebe programı o anda yanıt vermiyorsa sipariş kaybolmaz, birkaç dakika sonra yeniden denenir.
Hata Yönetimi: Entegrasyon Ne Zaman ve Nasıl Başarısız Olur?
Her entegrasyon bir gün hata verir. Karşı sistem bakımdadır, ağ bağlantısı kopmuştur, gönderilen veri eksiktir ya da yetki belirtecinin süresi dolmuştur. Sağlam bir entegrasyonu zayıf olandan ayıran şey hatasızlık değil, hatayla nasıl başa çıktığıdır.
Hataları iki ana gruba ayırmak, doğru tepkiyi belirlemenin ilk adımıdır:
- Geçici hatalar: Zaman aşımı, ağ kesintisi, karşı sistemin geçici olarak hizmet verememesi veya oran sınırına takılma. Bunlar genellikle bir süre sonra yeniden denenince düzelir.
- Kalıcı hatalar: Eksik zorunlu alan, geçersiz ürün kodu, yetkisiz erişim veya karşı sistemde var olmayan kayıt. Bunlar yeniden denemeyle düzelmez; verinin veya ayarın düzeltilmesi gerekir.
HTTP durum kodları bu ayrımı yapmaya yardımcı olur. Aşağıdaki tablo yaygın kodları ve entegrasyonda genel olarak önerilen tepkiyi özetler. Karşı sistemin dokümantasyonu bazı kodlara özel anlamlar yüklüyorsa, o dokümantasyon esas alınmalıdır.
| Durum kodu | Anlamı | Genel tepki |
|---|---|---|
| 200, 201 | İstek başarılı, kayıt oluştu | Sonucu kaydedin, süreci sürdürün |
| 400 | İstek hatalı veya eksik | Yeniden denemeyin; veriyi düzeltip hatayı raporlayın |
| 401 | Kimlik doğrulanamadı | Belirteci yenileyin; olmazsa yöneticiyi uyarın |
| 403 | Yetki yok | Yeniden denemeyin; izinleri kontrol edin |
| 404 | Kaynak bulunamadı | Eşleştirmeyi kontrol edin |
| 409 | Çakışma, örneğin kayıt zaten var | Mevcut kaydı sorgulayın, mükerrer kayıt oluşturmayın |
| 429 | Çok fazla istek | Bekleyin, varsa Retry-After başlığına uyun, sonra yeniden deneyin |
| 500, 502, 503, 504 | Sunucu tarafı veya geçit hatası | Artan aralıklarla ve deneme sınırıyla yeniden deneyin; kayıt oluşturan isteklerde önce idempotency anahtarını doğrulayın |
Yeniden deneme stratejisi
Geçici hatalarda isteği hemen ve sınırsızca tekrar göndermek, zaten zorlanan karşı sistemi daha da yorar. Yaygın yaklaşım, her denemede bekleme süresini artırmaktır (üstel geri çekilme). Örneğin ilk denemeden sonra kısa bir süre, ikinciden sonra bunun iki katı, üçüncüden sonra dört katı beklenir. Birçok istemcinin aynı anda yeniden denemesini önlemek için bekleme süresine küçük rastgele bir pay eklenir.
Yeniden denemenin bir üst sınırı olmalıdır. Belirlenen deneme sayısına ulaşan iş, ayrı bir "başarısız işler" listesine alınmalı ve bir kişiye bildirilmelidir. Bu listeden işin incelenip düzeltildikten sonra tek tıkla yeniden gönderilebilmesi, operasyon ekibinin işini büyük ölçüde kolaylaştırır.
Idempotency: Aynı işlemi iki kez yapmamak
Yeniden deneme beraberinde bir risk getirir. Siparişi muhasebeye gönderdiniz, karşı sistem kaydı oluşturdu ama cevap size ulaşmadan bağlantı koptu. Sizin tarafınızda işlem başarısız görünür ve yeniden denenir. Sonuç, muhasebede iki aynı fatura olabilir.
Idempotency, aynı işlemin birden fazla kez gönderilmesinin tek bir kez gönderilmesiyle aynı sonucu vermesi anlamına gelir. Bunu sağlamanın yolları şunlardır:
- Benzersiz işlem anahtarı: Birçok API, her isteğe eklenen benzersiz bir anahtarı (çoğu zaman Idempotency-Key gibi bir başlık) destekler. Aynı anahtarla gelen ikinci istek yeni kayıt oluşturmaz, ilk sonucu döndürür.
- Dış referans alanı: Siparişin kendi sisteminizdeki numarası karşı sistemde bir referans alanına yazılır. Göndermeden önce bu numarayla kayıt var mı diye sorgulanır.
- Kendi tarafınızda kayıt: Hangi kaydın hangi sonuçla gönderildiği entegrasyon tablosunda tutulur; başarıyla gönderilmiş bir kayıt yeniden gönderilmez.
Webhook alırken de aynı ilke geçerlidir. Karşı sistem aynı olayı birden fazla kez gönderebilir. Her olayın kimliği kaydedilmeli ve daha önce işlenmiş bir olay tekrar geldiğinde yalnızca başarılı cevap dönülüp işlem tekrarlanmamalıdır.
Oran Sınırları ve Performans
Çoğu API, belirli bir sürede kabul ettiği istek sayısını sınırlar. Bu sınır aşıldığında genellikle 429 durum koduyla cevap verilir. Oran sınırları karşı sistemi korumak için vardır ve entegrasyon tasarımında baştan dikkate alınmalıdır.
Oran sınırlarıyla uyumlu çalışmak için şu yöntemler kullanılır:
- Toplu işlem: API destekliyorsa, tek tek istek yerine birden fazla kaydı aynı istekte göndermek
- Yalnızca değişeni göndermek: Tüm ürün listesini her seferinde aktarmak yerine son aktarımdan bu yana değişen kayıtları göndermek
- Sayfalama: Büyük listeleri sayfa sayfa okumak ve her sayfa arasında sınırları gözetmek
- Önbellek: Sık değişmeyen verileri (kategori listesi, vergi tanımları) her istekte yeniden sorgulamamak
- Yoğunluk planlaması: Toplu güncellemeleri trafiğin düşük olduğu saatlere kaydırmak
Örnek mağazamızda binlerce ürünün stok bilgisi her birkaç dakikada bir tek tek güncellenmeye çalışılırsa, hem oran sınırına takılmak hem de sitenin yavaşlaması olasıdır. Yalnızca stok miktarı değişen ürünlerin aktarılması, aynı sonucu çok daha az istekle sağlar.
Kayıt (Log) ve İzleme
Entegrasyon görünmez çalışır. Her şey yolundayken kimse fark etmez; bir sorun olduğunda ise "sipariş neden muhasebeye geçmedi?" sorusuna hızlı cevap verebilmek gerekir. Bunun için iyi bir kayıt ve izleme altyapısı şarttır.
Her entegrasyon işlemi için şu bilgilerin kaydedilmesi faydalıdır:
- İşlemin zamanı ve türü
- İlgili kaydın kimliği (sipariş numarası, ürün kodu)
- Gönderilen isteğin özeti ve dönen durum kodu
- Hata mesajı ve kaçıncı deneme olduğu
- Süreci sistemler boyunca izlemeyi sağlayan bir ilişkilendirme kimliği
Kayıtlarda gizli anahtarlar, belirteçler, parolalar ve gereğinden fazla kişisel veri tutulmamalıdır. Kayıtların ne kadar süre saklanacağı ve kimlerin erişebileceği de belirlenmelidir.
İzleme, kayıtların pasif biçimde tutulmasının ötesine geçer. Belirli bir süre boyunca hiç sipariş aktarılmaması, başarısız işlerin belirli bir sayıyı geçmesi veya bir belirtecin süresinin dolmak üzere olması gibi durumlarda otomatik uyarı üretilmelidir. Uyarının kime, hangi kanaldan gideceği ve uyarıyı alan kişinin ne yapacağı yazılı olmalıdır. Operasyon ekibinin görebileceği basit bir entegrasyon durum ekranı (son başarılı aktarım zamanı, bekleyen ve başarısız işler) birçok sorunu müşteri fark etmeden yakalamayı sağlar.
Mutabakat kontrolleri
Hiç hata kaydı olmasa bile iki sistemin verisinin tutarlı olduğunu düzenli olarak doğrulamak iyi bir alışkanlıktır. Örneğin her gün, sitedeki tamamlanan sipariş sayısı ile muhasebeye aktarılan sipariş sayısı karşılaştırılabilir. Fark çıktığında hangi kayıtların eksik olduğu listelenir. Mutabakat, sessiz hataları yakalamanın en güvenilir yoludur.
API Güvenliği: Anahtarlar, Yetkiler ve Veri Koruma
Bir entegrasyon, iki sistem arasında açılmış bir kapıdır. Bu kapının güvenliği, her iki sistemin güvenliği kadar önemlidir. API'lere özgü güvenlik risklerini sınıflandıran OWASP API Security Project, hem API sunan hem de API kullanan taraf için faydalı bir referanstır. Listede nesne düzeyinde yetkilendirme hataları, kimlik doğrulama zafiyetleri ve kaynak tüketiminin sınırlandırılmaması gibi riskler yer alır.
Gizli anahtarların saklanması
API anahtarları, OAuth istemci sırları ve belirteçler parola kadar hassastır. Şu kurallar temel alınmalıdır:
- Gizli değerler kaynak kodun içine yazılmamalı, sürüm kontrol sistemine gönderilmemelidir.
- Ortam değişkenleri veya bir gizli değer yönetim servisi gibi kodun dışında, erişimi kısıtlı yerlerde saklanmalıdır.
- Veritabanında saklanması gerekiyorsa şifrelenmiş olarak tutulmalıdır.
- Tarayıcıda veya mobil uygulamada çalışan koda gizli anahtar konmamalıdır; bu kod kullanıcının cihazında çalıştığı için anahtar okunabilir.
- Anahtarlar düzenli aralıklarla ve bir çalışanın ayrılması gibi durumlarda yenilenmelidir.
- Test ve canlı ortam için farklı anahtarlar kullanılmalıdır.
En az yetki ilkesi
Entegrasyona yalnızca işini yapması için gereken yetkiler verilmelidir. Siparişleri okuyup muhasebeye aktaran bir entegrasyonun ürün silme, kullanıcı yönetme veya ödeme iadesi yapma yetkisine ihtiyacı yoktur. Karşı sistem kapsamlı izin seçenekleri sunuyorsa, yalnızca gereken kapsamlar seçilmelidir. Entegrasyon için ayrı bir kullanıcı veya uygulama hesabı açmak, bir kişinin kendi hesabını kullanmaktan daha güvenlidir; kişi işten ayrıldığında entegrasyon durmaz ve yapılan işlemler ayırt edilebilir.
Gelen isteklerin doğrulanması
Webhook adresi internete açıktır. Bu adrese gelen her istek gerçekten beklenen sistemden gelmeyebilir. Karşı sistem bir imza mekanizması sunuyorsa (genellikle paylaşılan bir sırla üretilen imza), her istekte bu imza doğrulanmalıdır. Gelen veri, güvenilmeyen girdi olarak ele alınmalı; beklenen biçimde olup olmadığı kontrol edilmelidir. Ödeme sonucu gibi kritik bildirimlerde, bildirime ek olarak karşı sistemin API'sinden işlemin durumu ayrıca sorgulanabilir.
Şifreli iletişim ve kişisel veriler
Tüm API trafiği HTTPS üzerinden yapılmalıdır. Aktarılan veri kişisel veri içeriyorsa (ad, adres, telefon, e-posta), 6698 sayılı Kişisel Verilerin Korunması Kanunu kapsamında hangi verinin hangi amaçla, hangi sisteme aktarıldığı değerlendirilmelidir. Entegrasyonda yalnızca gerekli alanların aktarılması, hem güvenlik hem de veri minimizasyonu açısından doğru yaklaşımdır. Hukuki değerlendirme için işletmenizin hukuk danışmanıyla çalışmanız önerilir.
Test Ortamı (Sandbox) ve Sürüm Değişiklikleri
Entegrasyonu doğrudan canlı sistemlerde geliştirmek, gerçek faturalar, gerçek kargo kayıtları veya gerçek ödemeler oluşturma riski taşır. Birçok servis bu nedenle test ortamı (sandbox) sunar. Test ortamında yapılan işlemler gerçek sonuç doğurmaz, ama API davranışı canlıya yakındır.
Test ortamıyla çalışırken dikkat edilmesi gerekenler:
- Test ortamının canlı ortamla aynı sürümde olup olmadığını kontrol edin.
- Başarılı senaryoların yanında hata senaryolarını da deneyin: eksik alan, geçersiz kod, zaman aşımı, mükerrer gönderim.
- Test ortamında oluşturulan verilerin canlıya taşınmadığından emin olun.
- Test ortamı sunmayan sistemlerde, canlıda kontrollü ve geri alınabilir test kayıtlarıyla çalışmayı karşı tarafla planlayın.
API sürümleri ve değişikliklere hazırlık
API'ler zamanla değişir. Yeni alanlar eklenir, eski alanlar kullanımdan kaldırılır, kimlik doğrulama yöntemi güncellenir. İyi yönetilen API'ler değişiklikleri sürüm numaralarıyla duyurur ve eski sürümü bir süre daha destekler. Yine de bu süre sonsuz değildir.
Sürüm değişikliklerine hazırlıklı olmak için:
- Kullanılan API sürümünü dokümantasyonda ve kodda açıkça belirtin.
- Karşı sistemin geliştirici duyurularını veya değişiklik notlarını takip edecek bir kişi belirleyin.
- Gelen cevaplarda tanımadığınız yeni alanlar olduğunda entegrasyonun bozulmayacağı biçimde kod yazılmasını isteyin.
- Kullanımdan kaldırma uyarılarını kayıtlarda yakalayın.
- Sürüm geçişlerini önce test ortamında deneyin.
Dokümantasyon ve Bakım
Entegrasyon kurulduktan sonra yıllarca çalışabilir. Bu süre içinde onu kuran kişi değişebilir, işletmenin süreçleri farklılaşabilir. Dokümantasyon, entegrasyonun kimseye bağımlı kalmadan anlaşılmasını sağlar.
Bir API entegrasyonu için hazırlanacak dokümantasyonda şunlar yer almalıdır:
- Bağlanan sistemler, kullanılan API sürümleri ve kimlik doğrulama yöntemi
- Veri akış şeması: hangi veri, hangi yönde, hangi tetikleyiciyle akıyor
- Alan eşleştirme tablosu ve dönüşüm kuralları
- Tek doğru kaynak kararları
- Zamanlanmış işlerin sıklığı
- Hata türleri, yeniden deneme kuralları ve başarısız işlerin nasıl ele alınacağı
- Uyarıların kime gittiği ve olası sorunlarda izlenecek adımlar
- Gizli anahtarların nerede saklandığı (değerlerin kendisi değil) ve nasıl yenileneceği
Bakım tarafında ise düzenli işler vardır: kütüphane ve çalışma ortamı güncellemeleri, belirteç ve sertifika yenilemeleri, kayıtların gözden geçirilmesi, mutabakat sonuçlarının incelenmesi ve karşı sistemlerdeki değişikliklere uyum. Bu işlerin kim tarafından, hangi sıklıkla yapılacağı entegrasyon kurulurken kararlaştırılmalıdır. Bakımı planlanmamış bir entegrasyon, ilk API değişikliğinde ya da ilk belirteç süresinin dolmasında durabilir.
Hazır Eklenti mi, Özel Entegrasyon mu?
Popüler platformlar arasında birçok bağlantı için hazır eklenti, modül veya bağlayıcı servis bulunur. Örneğin bir WooCommerce mağazası için muhasebe, kargo ve ödeme alanlarında eklentiler sunulur. Hazır çözüm ile özel geliştirme arasında seçim yaparken iki yaklaşımın güçlü ve sınırlı yanlarını tarafsız biçimde değerlendirmek gerekir.
| Ölçüt | Hazır eklenti veya bağlayıcı | Özel entegrasyon |
|---|---|---|
| Kurulum süresi | Genellikle kısa | Analiz ve geliştirme gerektirir |
| Süreç uyumu | Standart akışa göre tasarlanmıştır | Sizin iş kurallarınıza göre kurgulanır |
| Veri eşleştirme esnekliği | Eklentinin sunduğu ayarlarla sınırlı | İhtiyaca göre tanımlanabilir |
| Bakım ve güncelleme | Eklenti geliştiricisinin takvimine bağlı | Sizin veya ekibinizin sorumluluğunda |
| Karşı sistem değişikliği | Eklenti güncellenene kadar beklenir | Uyarlama doğrudan planlanabilir |
| Hata görünürlüğü | Eklentinin sunduğu kayıtlar kadar | Kayıt ve izleme ihtiyaca göre kurulur |
| Bağımlılık | Eklenti geliştiricisine ve lisansına | Kaynak koda ve dokümantasyona |
| Uygun olduğu durum | Standart süreçler, hızlı başlangıç | Özgün süreçler, çok sistemli akışlar |
Pek çok işletme için ilk adım hazır bir çözümü denemektir. Eklenti ihtiyacın büyük bölümünü karşılıyorsa, eksik kalan küçük bir kısım için ek geliştirme yapmak da bir seçenektir. Hazır çözümün sınırları süreçlerinizi eklentiye göre değiştirmenizi gerektirmeye başladığında veya birden fazla sistemin aynı akışa dâhil olduğu durumlarda özel entegrasyon daha uygun hâle gelebilir. Hangi yol seçilirse seçilsin, eklentinin güncel tutulup tutulmadığı, karşı sistemin hangi API sürümünü kullandığı ve hata durumunda nasıl bilgi verdiği değerlendirilmelidir.
Otomasyonun Avantajları ve Sınırları
Doğru kurgulanmış bir entegrasyonun faydaları belirgindir: elle aktarım ortadan kalkar, yazım hataları azalır, veriler sistemler arasında daha hızlı akar ve çalışanlar tekrar eden işler yerine karar gerektiren işlere zaman ayırır. Müşteriye giden bilgilerin (sipariş onayı, kargo takip numarası) gecikmeden ulaşması deneyimi de iyileştirir.
Sınırları da göz ardı edilmemelidir. Entegrasyon, hatalı bir süreci hızlandırır ama düzeltmez; elle yapılan işte fark edilen tutarsızlıklar otomatik akışta sessizce çoğalabilir. Her entegrasyon yeni bir bağımlılık ve bakım yükü getirir. Karşı sistemdeki bir değişiklik ya da kesinti, sizin süreçlerinizi de etkiler. Bu nedenle otomasyonu planlarken, entegrasyon durduğunda işin elle nasıl sürdürüleceğini anlatan kısa bir yedek prosedür hazırlamak iyi bir önlemdir.
Her süreci otomatikleştirmek de gerekmez. Ayda birkaç kez yapılan, istisnası bol ve insan kararı gerektiren bir işlem için entegrasyon yatırımı, sağlayacağı kazançla orantılı olmayabilir. Önceliği, sık tekrar eden, kuralları net ve hatası maliyetli işlere vermek daha verimli bir yaklaşımdır.
Entegrasyon Öncesi Kontrol Listesi
Bir API entegrasyonu çalışmasına başlamadan önce aşağıdaki maddeleri gözden geçirin:
- Otomatikleştirilecek süreç ve elle yapılan bugünkü adımlar yazıldı.
- Her iki sistemin API'si, dokümantasyonu ve gerekiyorsa lisans veya kullanım koşulları kontrol edildi.
- Kimlik doğrulama yöntemi ve erişim için gereken hesaplar belirlendi.
- Test ortamına erişim sağlandı ya da canlıda güvenli test yöntemi kararlaştırıldı.
- Aktarılacak veriler ve alan eşleştirme tablosu hazırlandı.
- Her veri türü için tek doğru kaynak kararı verildi.
- Aktarım yönü, tetikleyicisi ve sıklığı belirlendi.
- Senkron ve asenkron çalışacak adımlar ayrıldı.
- Geçici ve kalıcı hatalar için tepkiler, yeniden deneme sınırı ve başarısız iş listesi tanımlandı.
- Mükerrer kayıt oluşmasını önleyecek idempotency yöntemi seçildi.
- Karşı sistemin oran sınırları öğrenildi ve toplu işlem ihtiyacı değerlendirildi.
- Kayıt, izleme, uyarı ve mutabakat kontrolleri planlandı.
- Gizli anahtarların saklanma yeri ve yenileme süreci belirlendi.
- Entegrasyon hesabına yalnızca gereken yetkiler verildi.
- Kişisel veri aktarımı KVKK açısından değerlendirildi.
- Dokümantasyon ve bakım sorumluluğu kararlaştırıldı.
- Entegrasyon durduğunda uygulanacak elle çalışma prosedürü yazıldı.
Kaynaklar
- MDN: HTTP yanıt durum kodları
- OWASP API Security Project
- İçerik Ekim 2026'da hazırlandı.
Karınca Bilişim Kimdir?
API ve sistem entegrasyonu hizmeti veren Karınca Bilişim, Gaziantep Şahinbey'de 2019'dan beri bilişim ve yazılım alanında çalışıyor. Entegrasyonun iki ucundaki sistemler de çoğu zaman hizmet kapsamına girer: özel yazılım ve web yazılımı, WooCommerce kurulum ve danışmanlığı, özel WordPress eklentisi geliştirme ve Android uygulama geliştirme bunların başında gelir.
Bu yazıdaki kontrol listesi, bir entegrasyon görüşmesine hazırlanırken kullanılabilir. Listedeki sorular bağlantının nasıl kurulacağından çok verinin nasıl eşleşeceğine, hataların nerede görüneceğine ve gizli anahtarların nerede saklanacağına odaklanır; bu üç nokta, yayından sonraki bakım yükünü doğrudan belirler. Hazır bir eklentinin ihtiyacı karşılayıp karşılamadığı da aynı hazırlıkta yanıtlanması gereken bir sorudur, çünkü özel geliştirme yalnız hazır çözümün yetmediği yerde anlamlıdır.
Entegrasyonun çalıştığı altyapı için bakım ve güvenlik, hız optimizasyonu ve hosting yönetimi hizmetleri de sunulur. Bir entegrasyon yayına alındıktan sonra da izlenmesi ve bağlı sistemlerdeki sürüm değişikliklerine göre güncellenmesi gereken bir parça olarak düşünülmelidir.
Sıkça Sorulan Sorular
API entegrasyonu için iki sistemin de API'si olması gerekir mi?
Çoğu durumda en az bir tarafın veri alıp verebileceği bir arayüz sunması gerekir; diğer taraf genellikle sizin geliştirdiğiniz ya da kontrol ettiğiniz sistemdir. Bir sistem API sunmuyorsa dosya aktarımı, veritabanı bağlantısı veya dışa aktarılan raporların otomatik işlenmesi gibi alternatifler değerlendirilebilir. Bu alternatiflerin güvenilirliği ve bakım yükü API'ye göre farklı olabileceği için ayrıca planlanmalıdır.
Webhook mu kullanmalıyım, düzenli sorgu mu?
Karşı sistem webhook sunuyorsa olaylara hızlı tepki vermek için genellikle webhook tercih edilir. Ancak bildirimler kaçabileceği için belirli aralıklarla çalışan bir mutabakat sorgusuyla desteklemek daha güvenlidir. Webhook sunmayan sistemlerde ise oran sınırlarına uygun aralıklarla yapılan düzenli sorgu kullanılır.
Entegrasyon hata verirse siparişlerim kaybolur mu?
İyi tasarlanmış bir entegrasyonda kaybolmaması gerekir. Asenkron kuyruk, yeniden deneme, başarısız işler listesi ve günlük mutabakat kontrolleri, aktarılamayan kayıtların tespit edilip yeniden gönderilmesini sağlar. Planlama aşamasında bu mekanizmaların kapsamda olup olmadığını mutlaka sorun.
Hazır eklenti işimi görüyorsa özel entegrasyona gerek var mı?
Gerek olmayabilir. Hazır çözüm süreçlerinizi karşılıyor, güncel tutuluyor ve hata durumunda yeterli bilgi veriyorsa mantıklı bir tercihtir. Özel entegrasyon, eklentinin sınırları süreçlerinizi zorlamaya başladığında veya birden fazla sistemin aynı akışa dâhil olduğu durumlarda değerlendirilebilir.
API entegrasyonu maliyeti neye göre belirlenir?
Burada bir rakam vermiyoruz, çünkü maliyeti kapsam belirler. Bağlanacak sistem sayısı, veri eşleştirmenin karmaşıklığı, aktarım yönleri, hata yönetimi ve izleme beklentisi, test ortamının varlığı ve bakım ihtiyacı tahmini doğrudan etkiler. İhtiyacınızı yazılı hâle getirip iletişim bölümündeki kanallardan paylaşmanız, değerlendirmeyi somutlaştırır.
API anahtarımı yazılım ekibiyle nasıl paylaşmalıyım?
Anahtarları e-posta gövdesinde veya mesajlaşma uygulamalarında düz metin olarak paylaşmaktan kaçının. Mümkünse karşı sistemde entegrasyon için ayrı bir kullanıcı veya uygulama tanımlayıp yalnızca gerekli yetkileri verin ve anahtarı güvenli bir parola yöneticisi üzerinden iletin. Proje bittiğinde veya iş birliği sona erdiğinde anahtarları yenilemek iyi bir uygulamadır.
Karşı sistem API'sini değiştirirse ne olur?
Değişikliğin türüne göre entegrasyonun güncellenmesi gerekebilir. İyi yönetilen API'ler değişiklikleri önceden duyurur ve eski sürümü bir süre destekler; bu sürede uyarlamanın test ortamında yapılıp canlıya alınması gerekir. Bu tür uyarlamaların bakım kapsamında mı ayrı bir iş olarak mı ele alınacağını baştan kararlaştırmak sürprizleri önler.
Sonuç
İşletme sistemlerini birbirine bağlamak, elle aktarımı azaltır ve verinin daha hızlı, daha tutarlı akmasını sağlar. Bunun için API'nin ne sunduğunu anlamak, REST ve webhook gibi yöntemleri doğru yerde kullanmak ve kimlik doğrulamayı güvenli biçimde kurgulamak temel adımlardır.
Uzun vadede belirleyici olan şunlardır: verinin doğru eşleştirilmesi, her veri için tek doğru kaynağın belirlenmesi, hataların sınıflandırılıp yeniden deneme ve idempotency ile yönetilmesi, oran sınırlarına uyulması, kayıt ve izlemeyle sorunların görünür tutulması, gizli anahtarların korunması ve en az yetki ilkesinin uygulanması. Test ortamı, sürüm takibi, dokümantasyon ve planlı bakımla desteklenen bir API entegrasyonu, iş süreçlerinize uzun süre güvenilir biçimde hizmet eder.
İletişim Bilgileri
Sistemleriniz arasındaki veri akışını planlamak veya mevcut entegrasyonunuzla ilgili sorularınızı iletmek için aşağıdaki kanalları kullanabilirsiniz.
- Telefon: +90 539 219 79 78
- WhatsApp: WhatsApp üzerinden yazın
- İletişim sayfası: karincabilisim.net/iletisim
İş süreçlerinize uygun entegrasyon seçeneklerini değerlendirmek için Karınca Bilişim ile telefon, WhatsApp veya iletişim formu üzerinden görüşebilirsiniz.