API Nedir, API Entegrasyonu Nasıl Yapılır? Örneklerle Rehber

API nedir? Kısaca, bir yazılımın başka yazılımlara “bana bu biçimde sorarsan sana bu biçimde cevap veririm” dediği sözleşmedir. Açılımı Application Programming Interface, Türkçesiyle uygulama programlama arayüzüdür. Bir program “TR4815162342 numaralı kargo nerede?” diye sorar; kargo firmasının sistemi cevabı her seferinde aynı yapıda, makinenin okuyabileceği bir formatta döner. API ne demek sorusunun en kısa cevabı şu: insanlar için ekran, yazılımlar için API.

API ne işe yarar? Elle yapılan aktarımı ortadan kaldırır ve iki sistemin aynı veriyi aynı anda görmesini sağlar. Sitenizdeki kargo durumu kargo firmasının API'sinden gelir. Faturadaki döviz kuru Merkez Bankası'nın veri servisinden çekilebilir. Trendyol'a düşen sipariş kimse Excel'e yazmadan ERP'ye akar, stok düşer, e-Arşiv fatura kesilir. Bunların her birinin arkasında bir yazılımın belirli bir adrese, belirli bir biçimde istek göndermesi vardır.

Bu konuyu anlatan hemen her yazı garson benzetmesiyle açılır: siz menüden seçersiniz, garson siparişi mutfağa iletir, tabağı geri getirir. Benzetme fena değil ama yarım kalıyor. Gerçek bir API'de garson sizi tanımıyorsa sipariş almaz, menüde olmayan yemeği reddeder, aynı dakikada yüz sipariş verirseniz sizi bekletir ve mutfak kapandıysa bunu size bir kodla söyler. API'lerin karakteri bu kurallarda saklı; yazının geri kalanı büyük ölçüde onları anlatıyor.

Backend tarafında hem API yazan hem başkasının API'sine bağlanan biri olarak benim gözlemim şu: entegrasyonda zor kısım nadiren bağlantının kendisi. İlk başarılı istek çoğu zaman ilk gün atılır. Haftalar, iki sistemin aynı kelimeye farklı anlam yüklemesini çözerken geçer (sizin “sipariş” dediğiniz, onların “paket”i olabilir). Bir şey ters gittiğinde bunu kimin fark edeceği ve karşı taraf bir gün kuralı değiştirdiğinde ne olacağı da en baştan konuşulmalı.

Farkında olmadan her gün kullandığınız API'ler

• Kargo takibiMağaza → kargo firmasıSipariş sayfasındaki “Dağıtıma çıktı” bilgisi, mağazanın kargo firmasına takip numarasıyla sorduğu bir istekten gelir.
• Kartla ödemeMağaza → ödeme kuruluşu → bankaKart bilgisi mağazanın veritabanında saklanmaz; ödeme kuruluşunun ödeme formuna girilir ya da API'sine iletilir, 3D Secure sonucu mağazaya geri bildirilir.
• Pazaryeri siparişiPazaryeri ↔ ERPEntegrasyon yazılımı pazaryerinden yeni siparişleri çeker, stok ve fiyatı geri gönderir.
• e-Fatura / e-ArşivERP → özel entegratör → GİBFatura, ERP'den özel entegratörün servisine UBL-TR biçiminde gönderilir; durum bilgisi yine servisle sorgulanır.
• Döviz kuruERP → TCMB veri servisiKur bilgisi her sabah elle girilmek yerine Merkez Bankası'nın yayımladığı veriden okunur.
• SMS doğrulama koduUygulama → SMS sağlayıcısıGiriş ekranındaki tek kullanımlık kod, uygulamanın SMS firmasına gönderdiği bir API isteğiyle telefonunuza ulaşır.

Bir API çağrısı iki parçadan oluşur: istemcinin gönderdiği istek (request) ve sunucunun döndüğü yanıt (response). Web API'lerinin çok büyük kısmı bu alışverişi HTTP üzerinden yapar; tarayıcınızın bir sayfayı açarken kullandığı protokolün aynısıyla. Fark, dönen şeyin bir web sayfası değil, yapılandırılmış veri olmasıdır.

• 1MetotGETNe yapmak istediğinizi söyler: okumak, oluşturmak, güncellemek ya da silmek.
• 2Endpoint (URL)/v1/shipments/TR4815162342İşin yapıldığı adres. Sondaki parça hangi kaydı istediğinizi, v1 ise API sürümünü gösterir.
• 3Header'larAuthorization, Acceptİsteğin üst bilgileri: kim olduğunuz, hangi formatı beklediğiniz, gövdenin türü.
• 4Gövde (body){ "quantity": 42 }Yalnız veri gönderen isteklerde bulunur; okuma isteğinde genellikle boştur.

Yanıtın da üç parçası vardır: üç haneli bir durum kodu (200, 404, 429…), yanıt header'ları ve gövde. Aşağıdaki örnek, hayali bir kargo firmasının API'sine yapılan takip isteğini ve dönen cevabı gösteriyor.

GET /v1/shipments/TR4815162342 HTTP/1.1
Host: api.kargo.example
Authorization: Bearer $TOKEN
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "trackingNo": "TR4815162342",
  "status": "OUT_FOR_DELIVERY",
  "statusText": "Dağıtıma çıktı",
  "lastLocation": "Maltepe Şube",
  "updatedAt": "2026-10-21T08:42:00+03:00",
  "estimatedDelivery": "2026-10-21"
}

JSON nedir? JavaScript Object Notation; süslü parantez, anahtar ve değer çiftlerinden oluşan, hem insanın hem makinenin rahat okuduğu bir veri biçimi. Yeni yazılan API'lerin neredeyse tamamı JSON konuşur. XML ise etiket temelli, daha uzun ama XSD şemasıyla sıkı biçimde doğrulanabilen bir biçimdir; bankaların, bazı kamu servislerinin ve eski ERP web servislerinin bir kısmında hâlâ karşınıza çıkar. e-Fatura'nın UBL-TR belgesi de XML'dir; bir e-Fatura entegrasyonunda ikisini birden görmeniz olağan.

HTTP API'lerinin bir başka özelliği durumsuz (stateless) çalışmasıdır: sunucu bir önceki isteğinizi hatırlamak zorunda değildir. Bu yüzden kimlik bilgisi her istekte yeniden gönderilir. “Az önce giriş yaptım ya” diye düşünen istemci, token'ı eklemeyi unuttuğu ilk istekte 401 alır.

HTTP metodu isteğin niyetini söyler. İki kavramı bilmek, tasarım kararlarının çoğunu anlamaya yeter: güvenli (safe) metot sunucuda hiçbir şeyi değiştirmez; idempotent metot ise aynı istek bir kez de gönderilse on kez de gönderilse aynı sonucu bırakır. Tanımlar HTTP semantiğini anlatan RFC 9110'dan gelir.

Bu ayrım neden önemli? Ağ koptuğunda istemci isteği tekrarlar. GET ve PUT tekrarlandığında sonuç değişmez; POST tekrarlanırsa iki ödeme ya da iki sipariş oluşabilir. Ödeme API'lerinin Idempotency-Key gibi bir başlık ya da benzersiz sipariş numarası üzerinden mükerrer kontrolü istemesinin sebebi budur.

• 2xxBaşarılıİstek anlaşıldı ve yapıldı.
• 3xxYönlendirmeKaynak taşındı ya da değişmedi (304); API'lerde seyrek.
• 4xxİstemci hatasıSorun isteği gönderen tarafta: kimlik, yetki, veri, hız.
• 5xxSunucu hatasıSorun karşı tarafta ya da aradaki ağ geçidinde.

Bu tablo başvuru içindir. Canlıdaki bir entegrasyonda sipariş düşmüyor, stok tutmuyor ya da webhook gelmiyorsa adım adım teşhis için entegrasyon hataları rehberimize bakın.

Durum kodlarını tablodan okumak bir şey, kendi isteğinizin neden reddedildiğini görmek başka. Aşağıdaki laboratuvarda dört gerçekçi senaryodan birini seçin; metodu, kimlik bilgisini, gönderdiğiniz veriyi ve hız durumunu değiştirin. Laboratuvar size ham HTTP isteğini, sunucunun döneceği durum kodunu, örnek JSON yanıtını, ne olduğunu düz Türkçeyle ve aynı isteği terminalde atmanızı sağlayan cURL komutunu üretir.

Sunucu bir isteği sırayla kontrol eder ve ilk takıldığı yerde durur. Laboratuvar yaygın bir API ağ geçidi sırasını izliyor: önce hız sınırı, sonra kimlik, yetki kapsamı, metot, kayıt ve en son gövde doğrulaması. Gerçek sunucularda bu sıra kullanılan çatıya göre değişebilir; bazıları metodu kimlikten önce kontrol eder. Sıranın kendisinden çok, her kapının neyi sorduğunu öğrenmek işinize yarayacak.

GET /v1/shipments/TR4815162342 HTTP/1.1
Host: api.kargo.example
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJzY29wZSI6…
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

{
  "trackingNo": "TR4815162342",
  "status": "OUT_FOR_DELIVERY",
  "statusText": "Dağıtıma çıktı",
  "lastLocation": "Maltepe Şube",
  "updatedAt": "2026-10-21T08:42:00+03:00"
}

curl -X GET "https://api.kargo.example/v1/shipments/TR4815162342" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

API'ler teknik yapılarına göre değil, önce kime açık olduklarına göre ayrılır. Bu ayrım, teklif aşamasında “bu sisteme bağlanabilir miyiz?” sorusunun cevabını da belirler: açık bir API'ye ertesi gün bağlanabilirsiniz, partner API'si için sözleşme ve onay beklersiniz, dahili bir API'ye ise dışarıdan hiç erişemezsiniz.

• Açık (public) APIKayıt olan herkesHesap açıp anahtar alan herkesin kullanabildiği API'ler. Merkez Bankası'nın EVDS veri servisi buna örnektir: kayıt olduktan sonra profilinizdeki API anahtarıyla seri verilerini çekersiniz. Harita ve hava durumu servisleri de çoğunlukla bu gruptadır.
• Partner APISözleşmeli iş ortaklarıSatıcı, bayi ya da müşteri olduğunuzda açılan API'ler. Pazaryeri satıcı API'leri (Trendyol'da anahtarlar satıcı panelinde Hesap Bilgilerim → Entegrasyon Bilgileri sayfasındadır), kargo firmalarının kurumsal müşteri servisleri ve bankaların sanal POS servisleri bu gruptadır.
• Dahili (internal) APIYalnız şirketin kendi yazılımlarıMobil uygulamanızın konuştuğu backend, şirket içi servislerin birbirini çağırdığı arayüzler. Dışarıya dokümante edilmez ama güvenlik ihtiyacı daha az değildir: mobil uygulamanın konuştuğu her adres internetten erişilebilir.
• Bileşik (composite) APITek çağrıda birden çok işBirkaç servisi arkada çağırıp tek yanıtta birleştiren katman. “Sipariş özeti” ekranı için siparişi, kargoyu ve faturayı ayrı ayrı istemek yerine tek istek atarsınız. Bu bir erişim modeli değil, bir tasarım kalıbıdır; listede durmasının sebebi teklif dokümanlarında sık geçmesi. Zayıf mobil bağlantıda üç istek yerine tek istek, ekranın açılış süresini hissedilir biçimde kısaltır.

“Özel API” ifadesi iki anlamda kullanılıyor ve toplantılarda karışıklık yaratıyor: bazen dahili (private) API kastediliyor, bazen de “bizim için sıfırdan yazılacak API”. İkincisi bir tür değil, bir projedir; konuşurken hangisini kastettiğinizi netleştirin.

Kendi sisteminizi bayilere ya da iş ortaklarına açmayı düşünüyorsanız partner API tasarımının ayrı kuralları var: anahtar ve kapsam yönetimi, kota, sürümleme ve okunabilir dokümantasyon. Bu senaryo için sistemini dışarıya açanlar için API geliştirme sayfamızda yaklaşımımızı anlattık; mobil uygulamanın arkasındaki dahili API içinse mobil backend için API geliştirme sayfasına bakabilirsiniz.

REST bir protokol değil, bir mimari tarzdır: her şey bir kaynaktır (sipariş, ürün, müşteri), her kaynağın bir adresi vardır ve üzerinde HTTP metotlarıyla işlem yapılır. Basit, önbelleğe uygun ve herkesin bildiği bir yapı olduğu için dışarıya açılan API'lerin çoğu REST'tir. Zayıf yanı, ekranın ihtiyacından fazla ya da eksik veri getirmesi: bir sipariş ekranı için siparişi, müşteriyi ve kargoyu üç ayrı istekle çekmeniz gerekebilir.

GraphQL bu soruna cevap olarak Facebook'ta geliştirildi ve 2015'te açık kaynak yapıldı; bugün Linux Foundation bünyesindeki GraphQL Foundation tarafından yönetiliyor. Tek bir adrese sorgu gönderirsiniz ve tam olarak hangi alanları istediğinizi yazarsınız. Ekranı sık değişen mobil ve web uygulamalarında işe yarar: ön yüze yeni bir alan eklemek için backend'de yeni endpoint açmak gerekmez. Bedeli: HTTP önbelleği doğrudan işlemez, bir sorgunun sunucuya ne kadar yük bindireceğini önceden kestirmek zorlaşır ve sorgu derinliğine sınır koymanız gerekir.

SOAP XML zarfları ve WSDL adı verilen katı bir sözleşme dosyasıyla çalışan eski kuşak web servis standardıdır. Yeni projede pek seçilmez ama bazı banka ve kamu servislerinde, eski ERP web servislerinde ve kargo tarafındaki köklü entegrasyonlarda hâlâ karşınıza çıkar. Orada seçim sizde değildir; karşı taraf ne sunuyorsa ona bağlanırsınız.

gRPC Google kaynaklı, HTTP/2 üzerinde Protocol Buffers adlı ikili (binary) formatla çalışan bir uzak çağrı çatısıdır. Sözleşme .proto dosyasında tanımlanır, istemci kodu bundan üretilir. Servisler arası, saniyede yüzlerce çağrının döndüğü ve gecikmenin milisaniyelerle ölçüldüğü iletişimde öne çıkar; tarayıcıdan doğrudan çağrılması ise ara katman (gRPC-Web) ister. Monoliti servislere bölen ekipler için mikro servis geçişi için API geliştirme sayfamızda bu iletişimi nasıl kurguladığımızı anlattık.

Aşağıdaki altı soruyu projenize göre yanıtlayın; seçici size birincil yaklaşımı, varsa tamamlayıcısını ve gerekçesini verir. Puanlama basit ve şeffaftır; bir mimari incelemenin yerini tutmaz ama doğru soruyu sormanıza yardım eder.

Klasik API kullanımında bilgiyi siz çekersiniz (pull): “yeni ödeme var mı?” diye sorarsınız. Webhook ise yönü tersine çevirir (push): olay olduğunda karşı sistem sizin belirlediğiniz adrese kendisi bir HTTP isteği gönderir. Kısaca webhook, “bir şey oldu” haberini taşıyan ters yönlü bir API çağrısıdır.

Farkı rakamla görmek kolay. Ödeme sonucunu her beş dakikada bir sormak günde 288 istek demektir; ödeme gelmeyen saatlerde bunların hepsi boşa gider, ödeme geldiğinde ise ortalama iki buçuk dakika geç öğrenirsiniz. Webhook'ta ödeme anında tek bir istek gelir. Sık sorgulamak (polling) hem karşı tarafın hız sınırını zorlar hem de sizin sunucunuzu meşgul eder.

Webhook API'nin rakibi değildir, tamamlayıcısıdır. İyi tasarlanmış sistemlerde bildirim kısa tutulur (olay türü ve kayıt ID'si), ayrıntı ve kesin durum API'den sorgulanır. Böylece sahte ya da eski bir bildirim, tek başına sipariş onaylatamaz.

Türkiye'deki ödeme bildirimlerinden iki örnek

Webhook alırken uyduğumuz beş kural

1. 1İmzayı doğrulayınWebhook adresiniz internete açıktır; herkes oraya istek atabilir. İmzası tutmayan bildirimi işlemeyin.
2. 2Hızlı 2xx dönün, işi kuyruğa atınFatura kesmek, e-posta göndermek gibi uzun işleri bildirimi aldıktan sonra arka planda yapın. Geç cevap, karşı tarafın tekrar göndermesine yol açar.
3. 3Aynı bildirim iki kez gelebilirAğ sorunlarında sağlayıcılar tekrar dener. Olay ya da ödeme ID'sini saklayın; daha önce işlenmişse yeniden işlemeyin (idempotency).
4. 4Sıraya güvenmeyin“İptal” bildirimi “onay”dan önce gelebilir. Kararı bildirimin geliş sırasına değil, API'den okunan güncel duruma göre verin.
5. 5Kaçanlar için mutabakat kurunWebhook bir gün gelmeyecek. Günde birkaç kez son kayıtları API'den çekip karşılaştıran küçük bir kontrol, kaçan bildirimi yakalar.

import crypto from "node:crypto";

// payload: sağlayıcının belirttiği alanlar, belirttiği sırayla birleştirilmiş hâli.
// encoding: dokümana bakın (iyzico "hex", PayTR "base64").
function isValidSignature(payload: string, received: string, secret: string, encoding: "hex" | "base64") {
  const expected = crypto.createHmac("sha256", secret).update(payload).digest(encoding);
  const a = Buffer.from(expected);
  const b = Buffer.from(received ?? "");
  // Zamanlama saldırısına karşı sabit süreli karşılaştırma
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Webhook hiç gelmiyorsa ya da geldiği hâlde sipariş güncellenmiyorsa izlenecek adımları entegrasyon hataları yazımızda topladık.

API key nedir? Sağlayıcının size verdiği, her istekte bir başlıkta gönderdiğiniz uzun ve tahmin edilemez bir metindir. Basittir ve sunucudan sunucuya entegrasyonlarda yaygındır. Bazı sağlayıcılar anahtarı bir gizli değerle (secret) birlikte verir ve ikisini HTTP Basic kimlik doğrulamasıyla göndermenizi ister. Trendyol satıcı API'si buna örnektir: satıcı ID'si, API key ve API secret panelden alınır, her istekte ayrıca User-Agent başlığı beklenir. Kendi yazılımınızla bağlanıyorsanız bu başlık SatıcıID - SelfIntegration biçimindedir; göndermeyen istek 403 ile reddedilir. Test ortamına erişmek için IP adresinizi Trendyol'a bildirmeniz de gerekiyor, canlı ortamda bu şart yok.

OAuth 2.0 bir yetkilendirme çerçevesidir: uygulamanız kullanıcının şifresini hiç görmeden, onun adına sınırlı bir işlem yapma izni alır. Sonunda elinize kısa ömürlü bir erişim token'ı geçer ve bu token belirli kapsamlarla (scope) sınırlıdır: orders:read alan bir uygulama sipariş iptal edemez. Sunucudan sunucuya entegrasyonlarda kullanıcı olmadığı için “client credentials” akışı, kullanıcı onayı gereken durumlarda “authorization code + PKCE” akışı kullanılır. OAuth 2.0 ve en iyi uygulamalarını tek metinde toplayan OAuth 2.1, Ekim 2026 itibarıyla hâlâ IETF taslağı aşamasında.

JWT (JSON Web Token) bir protokol değil, bir token biçimidir. Üç parçadan oluşur: başlık, içerik (kimin için, ne zamana kadar, hangi kapsamla) ve imza. Sunucu imzayı doğrulayarak token'ın değiştirilmediğinden emin olur. Sık yapılan yanlış: JWT'nin şifreli sanılması. Yaygın kullanılan imzalı JWT'nin içeriği yalnız Base64URL ile kodlanmıştır; token'ı jwt.io gibi bir çözücüye yapıştıran herkes okuyabilir. İçine kişisel veri ya da gizli bilgi koymayın.

Banka ve ödeme tarafında bir katman daha eklenir: mTLS (karşılıklı TLS). Burada yalnız sunucu değil istemci de sertifikayla kendini kanıtlar; anahtar çalınsa bile sertifikası olmayan makine bağlanamaz. Finansal entegrasyonlarda neleri ek olarak kurguladığımızı fintech ve ödeme için API geliştirme sayfasında anlattık.

Anahtarlar nerede durmalı?

• !Anahtarı kaynak koda yazmayın; ortam değişkeni (.env, sürüm kontrolüne eklenmeden) ya da bir gizli anahtar yöneticisi kullanın.
• !Mobil uygulamanın paketine ya da tarayıcıda çalışan JavaScript'e gizli anahtar koymayın; paket açılıp okunabilir. Bu çağrıları kendi sunucunuz üzerinden yapın.
• !Test (sandbox) ve canlı ortam anahtarları ayrı olsun; çoğu sağlayıcı zaten ayrı verir.
• !Her entegrasyona yalnız ihtiyacı kadar kapsam verin ve anahtarları belirli aralıklarla yenileyin.
• !Bir geliştirici ekipten ayrıldığında ya da anahtar bir e-postaya, ekran görüntüsüne, GitHub deposuna düştüğünde beklemeden değiştirin.

API entegrasyonu, iki ya da daha fazla sistemin veri ve işlemlerini bu arayüzler üzerinden otomatik olarak paylaşmasıdır. Kod yazma kısmı sürecin ortasında bir yerdedir; projeyi başarılı ya da başarısız yapan kararların çoğu ondan önce verilir. Aşağıdaki yedi adım, API geliştirme projelerimizde izlediğimiz sıranın sadeleştirilmiş hâli.

1. 1
   Veri akışını haritalayınHangi veri, hangi sistemden hangisine, hangi sıklıkla gidecek? Her veri nesnesinin tek bir sahibi (master) olsun: fiyat ERP'de mi değişir, sitede mi? Bu soru cevaplanmadan yazılan entegrasyon, iki sistemin birbirinin üstüne yazmasıyla biter.Kim karar verir: İş birimi + entegrasyon sorumlusuÇıktı: Akış şeması ve master tablosu
2. 2
   Dokümanı ve sandbox'ı inceleyinKarşı tarafın dokümanını okuyun, test ortamında ilk isteği atın. Hız sınırı, sayfalama, hata biçimi ve webhook desteği bu aşamada öğrenilir; sonradan öğrenilmesi pahalıdır.Kim karar verir: GeliştiriciÇıktı: Çalışan ilk istek, açık sorular listesi
3. 3
   Alanları eşleştirin (veri sözlüğü)Pazaryerindeki “kargo firması” sizin ERP'de hangi koda karşılık geliyor? KDV oranı nerede, birim “adet” mi “koli” mi? Alan alan eşleme tablosu çıkarın; eşleşmeyen kayıtlar için kural yazın.Kim karar verir: Operasyon / muhasebeÇıktı: Alan eşleme tablosu
4. 4
   Kimlik ve ortamları kurunTest ve canlı anahtarlarını ayırın, entegrasyon için ayrı bir kullanıcı ve en dar yetkiyi tanımlayın, anahtarları gizli anahtar yöneticisine koyun.Kim karar verir: BT / güvenlikÇıktı: Ortam ve yetki listesi
5. 5
   Hata ve yeniden deneme stratejisi belirleyinGeçici hatalarda (429, 503, zaman aşımı) artan aralıklarla tekrar deneyin; veri hatalarında (422) denemeyin, kaydı bekleyenler kuyruğuna alıp sorumluya bildirin. Hiçbir kayıt sessizce kaybolmasın.Kim karar verir: Yazılım mimarıÇıktı: Hata sınıfları ve kuyruk kuralları
6. 6
   Test edin: mutlu yol yetmezİndirimli sipariş, kısmi iade, iptal sonrası tekrar sipariş, aynı anda iki kanaldan son ürünün satılması, Türkçe karakterli adres, sıfır stok… Sandbox'ta ve Postman koleksiyonuyla uç durumları deneyin.Kim karar verir: Test + iş birimiÇıktı: Senaryo listesi ve onay
7. 7
   Canlıya alın ve izleyinÖnce sınırlı kapsamla (bir kategori, bir depo) açın. Her akışın en son ne zaman başarıyla çalıştığını gösteren bir pano ve eşik aşıldığında giden bir uyarı kurun. Entegrasyonun asıl ömrü canlıya alındıktan sonra başlar.Kim karar verir: OperasyonÇıktı: İzleme panosu ve alarm kuralları

Örnek alan eşleme tablosu (pazaryeri → ERP)

Birden fazla sistemi tek katmanda buluşturmak istiyorsanız sistem birleştirme için API geliştirme sayfamız bu adımların her birini nasıl ele aldığımızı anlatıyor. Bütçe tarafını merak ediyorsanız maliyet kalemlerini API entegrasyonu fiyatları yazısında ayrıca ele aldık.

Teklif görüşmelerinde konuştuğumuz entegrasyonlar genellikle aşağıdaki gruplardan birine giriyor. Hepsinin kendine özgü bir tuzağı var. Kartlara, sahada en çok vakit kaybettiren tuzağı yazdık.

• Ödemeiyzico, PayTR, banka sanal POS'larıÖdeme başlatma, 3D Secure, iade, ödeme sonucu bildirimiTuzak: Ödeme sonucunu yalnız kullanıcının döndüğü sayfaya göre onaylamak. Kesin sonuç sunucuya gelen bildirimde ve API sorgusundadır.
• KargoAras, Yurtiçi, MNG ve diğerleriGönderi oluşturma, etiket, takip, iade koduTuzak: Firmaya göre REST de SOAP/XML de çıkabilir; takip durum adları firmadan firmaya değişir, ortak bir durum sözlüğü gerekir.
• PazaryeriTrendyol, Hepsiburada, n11Ürün, stok ve fiyat gönderimi; sipariş çekme; iade ve soru-cevapTuzak: Toplu ürün işlemleri çoğunlukla asenkron çalışır: isteği gönderirsiniz, sonucu ayrı bir sorguyla takip edersiniz.
• e-Fatura / e-ArşivÖzel entegratör servisleriUBL-TR belge gönderimi, durum sorgusu, gelen faturalarTuzak: İşletmeler çoğunlukla GİB'e doğrudan değil, özel entegratörün API'sine bağlanır; entegratör değişirse bağlayıcı da değişir.
• ERPLogo, Netsis, Mikro, SAPCari, stok, fiyat, sipariş, irsaliye, faturaTuzak: Veritabanına doğrudan yazmak hızlı görünür, iş kurallarını atlar. Resmî servis katmanlarını tercih edin.
• Döviz kuruTCMB yayımladığı kurlar, EVDSGünlük kur, geçmiş seriTuzak: Hangi kurun (alış, satış, efektif) ve hangi günün kurunun kullanılacağı muhasebe kararıdır, yazılımcının değil.
• SMS ve e-postaToplu SMS ve e-posta sağlayıcılarıDoğrulama kodu, sipariş bilgilendirme, kampanyaTuzak: Sipariş bilgilendirmesi ile kampanya mesajı aynı şey değildir. Ticari elektronik iletilerde onay kaydı İleti Yönetim Sistemi (İYS) üzerinden yürür; hangi mesajın ticari sayılacağını hukuk ekibinizle netleştirin.
• Banka hareketleriKurumsal internet bankacılığı servisleriHesap hareketi okuma, tahsilat eşleştirmeTuzak: Açıklama alanı serbest metindir; cari eşleştirmesi için kural ve elle onay ekranı gerekir.

ERP tarafı ayrı bir yazıyı hak edecek kadar derin; Logo ile e-ticaret ve B2B kanallarını bağlarken hangi yöntemin seçildiğini Logo ERP entegrasyonu rehberimizde adım adım anlattık. Logo tarafında kurulum, lisans ve servis katmanı ihtiyacınız varsa Logo ERP çözüm ortaklığı hizmetimize göz atabilirsiniz.

Kendi ürünümüzden somut bir örnek: TYS, teklif yönetimi için geliştirdiğimiz sistem. Logo'dan cari, ürün, fiyat, stok, ödeme planı, sevk türü ve döviz kurunu periyodik olarak okur. Kurda öncelik sırası bellidir: önce Logo'daki kur, yoksa TCMB, o da yoksa elle giriş. Kabul edilen teklifi cari ve ürün eşleştirmesiyle Logo'ya sipariş olarak yazar ve aktarım sonrası mutabakat kontrolü yapar. Yukarıda anlattığımız master kararı, alan eşleme ve mutabakat adımlarının hepsi orada canlı çalışıyor.

e-Fatura ve e-Arşiv geçişinin mevzuat ve ERP tarafı için e-Fatura zorunluluğu yazımıza, e-ticaret kanallarının tamamını tek akışta toplamak için e-ticaret entegrasyonları için API geliştirme sayfamıza bakabilirsiniz.

Her yazılımın bir API'si yok. Özellikle yıllar önce yazılmış masaüstü programlar, bir dönemin yerel muhasebe yazılımları ve sektörel paketler dışarıya kapı açmayı hiç düşünmeden tasarlanmış olabilir. Bağlanmanın neredeyse her zaman bir yolu var. Sorun, her yolun bedelinin farklı olması ve bu bedelin teklif aşamasında değil, genellikle aylar sonra ilk sürüm güncellemesinde ya da ilk yoğun kampanya gününde görünmesi.

Aşağıdaki seçenekleri, bizim önerdiğimiz deneme sırasıyla listeledik. İlk sıradaki en temiz, sonuncu en kırılgan yoldur.

1. 01Üreticiden API ya da web servis talep etmekYazılımın güncel sürümünde ya da ek modülünde bir servis katmanı olabilir. Önce sorun; bazen modül vardır da lisansı açılmamıştır.Bedeli: Ek lisans ücreti ve bekleme süresi.
2. 02Önüne adapter (ara katman) API yazmakEski sistemin kendi içe/dışa aktarma yollarını kullanan, dışarıya JSON konuşan bir REST arayüzü sunan küçük bir servis yazılır. Diğer sistemler yalnız bu katmanla konuşur.Bedeli: Ek bir bileşenin bakımı; ama eski sistem değişince yalnız adapter güncellenir.
3. 03Veritabanı görünümü (view) ya da salt okunur kopyaOkuma için veritabanında hazırlanmış görünümler ya da bir rapor kopyası kullanılır.Bedeli: Okuma makul, yazma tehlikeli: doğrudan tabloya yazmak iş kurallarını atlar, sürüm güncellemesinde kırılır.
4. 04Dosya alışverişi (CSV/XML, SFTP) ve EDISistemler belirli saatlerde dosya bırakır ve alır. Büyük tedarikçilerle EDI standartları kullanılabilir.Bedeli: Anlık değildir; dosya biçimi değişince sessizce bozulur. Dosya geldi mi, işlendi mi takibi şart.
5. 05E-posta ayrıştırmaSistemin gönderdiği sipariş ya da rapor e-postaları okunup ayrıştırılır.Bedeli: Şablon değişince kırılır, gecikmelidir; düşük hacimli ve geçici çözümler için.
6. 06RPA ya da ekran kazımaBir yazılım robotu ekrandaki alanları insan gibi okur ve doldurur.Bedeli: En kırılgan yol: arayüzdeki küçük bir değişiklik akışı durdurur. Hizmet sözleşmesine ve kişisel veri işleme kurallarına uygunluğu ayrıca değerlendirilmelidir.

Hangi yol ne zaman mantıklı?

Eski bir masaüstü programın modernize mi edileceği, olduğu gibi kalıp önüne adapter mı yazılacağı ayrı bir karar. Bu karar için VB6 ve Delphi programlarının Windows 11'deki durumu yazısındaki “yamala, taşı, yeniden yaz” çerçevesi işinize yarayabilir. Adapter katmanını ve geri kalan bağlantıları API geliştirme hizmetimiz kapsamında tasarlıyoruz.

Bir tedarikçi “API'miz var” dediğinde ilk isteyeceğiniz şey dokümandır. İyi bir doküman, entegrasyon süresini ve teklif fiyatını doğrudan düşürür; kötü bir doküman ise geliştiricinin günlerini deneme yanılmaya harcatır. Teknik olmayan biri bile birkaç maddeye bakarak dokümanın kalitesini anlayabilir.

OpenAPI, REST API'lerini makinenin okuyabileceği bir dosyada (YAML ya da JSON) tarif etmenin standart yoludur. Eski adı Swagger Specification'dır; bugün Linux Foundation bünyesindeki OpenAPI Initiative tarafından geliştiriliyor ve Eylül 2025'te yayımlanan 3.2 en güncel sürüm. Araçların bir kısmı hâlâ 3.0 ve 3.1 ile çalışıyor; bu normal. Swagger UI bu dosyayı tarayıcıda gezilebilir, denenebilir bir sayfaya çevirir. Postman ise istekleri koleksiyonlar hâlinde saklayıp paylaşmanızı sağlayan bir istemcidir; iyi sağlayıcılar hazır bir Postman koleksiyonu da verir.

Bir uyarı: açık API ile OpenAPI aynı şey değildir. Açık API herkese açık olan API'dir; OpenAPI ise bir API'yi tarif etmenin dosya biçimidir. Tamamen dahili bir API de OpenAPI ile belgelenebilir, belgelenmelidir de.

openapi: 3.1.0
info:
  title: Mağaza Stok API
  version: 1.4.0
paths:
  /v1/products/{sku}/stock:
    patch:
      summary: Ürünün stok adedini günceller
      security:
        - bearerAuth: [stock:write]
      parameters:
        - name: sku
          in: path
          required: true
          schema: { type: string, example: SKU-1042 }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [quantity]
              properties:
                quantity: { type: integer, minimum: 0 }
                warehouse: { type: string, example: IST-01 }
      responses:
        "200": { description: Güncellendi }
        "404": { description: Ürün bulunamadı }
        "422": { description: Doğrulama hatası }

Sürümleme konusunu hafife almayın. v1 adresinde çalışan entegrasyonunuz, sağlayıcı alanların anlamını değiştirdiğinde bir gece kırılabilir. Ciddi sağlayıcılar kırıcı değişiklikleri yeni sürümde yapar ve eski sürümü kapatmadan önce aylar öncesinden duyurur. Dokümanda böyle bir politika yoksa sorun.

OpenAPI tanımı artık yalnız insanlar için değil: yapay zekâ ajanlarına bir API'yi “araç” olarak tanıtırken de bu şemalar kullanılıyor. Ajanların araç çağırma mantığını yapay zekâ ajanı nedir yazısında anlattık. İş uygulamalarında API'nin nasıl bir yere oturduğunu görmek isterseniz web uygulaması nedir yazısı iyi bir başlangıç.

OWASP'ın API Security Top 10 listesi, API'lerde en sık görülen güvenlik risklerini sıralar; en güncel sürümü 2023 yılında yayımlanan baskı. Listenin başında yer alan risk, bir işletme sahibinin de rahatça anlayabileceği kadar basit: BOLA (Broken Object Level Authorization), yani nesne düzeyinde yetki kontrolünün eksik olması.

Somut örnek: müşteri, mobil uygulamada kendi siparişini açtığında uygulama GET /v1/orders/10452 isteği atar. Meraklı biri bu sayıyı 10453 yapıp isteği tekrarlar. Sunucu yalnız “giriş yapmış mı?” diye bakıp “bu sipariş bu kullanıcının mı?” diye bakmıyorsa, başka bir müşterinin adı, adresi ve telefonu ekrana gelir. Ne şifre kırılmıştır ne sunucu hacklenmiştir; tek bir kontrol eksiktir ve sonuç bir kişisel veri ihlalidir.

• API1Nesne düzeyinde yetki (BOLA)Her istekte istenen kaydın o kullanıcıya ait olduğunu sunucuda kontrol edin. Tahmin edilemez ID'ler (UUID) işi zorlaştırır ama tek başına çözüm değildir.
• API2Kırık kimlik doğrulamaSüresiz token'lar, deneme sınırı olmayan giriş uçları, URL'de taşınan anahtarlar.
• API3Nesne özelliği düzeyinde yetkiYanıtta gerekenden fazla alan dönmek ya da istemcinin role gibi değiştirmemesi gereken alanları güncelleyebilmesi.
• API4Sınırsız kaynak tüketimiHız sınırı, sayfa boyutu üst sınırı ve zaman aşımı olmayan uçlar; hem maliyet hem kesinti riski.
• API5Fonksiyon düzeyinde yetkiSıradan kullanıcının yönetici uçlarını (ör. /admin/refunds) çağırabilmesi.
• API9Uygunsuz envanter yönetimiUnutulmuş eski sürümler, kapatılmamış test ortamları, dokümanda olmayan uçlar.
• API10API'lerin güvensiz tüketimiÜçüncü taraf API'den gelen veriye körü körüne güvenmek; dışarıdan gelen veri de doğrulanmalıdır.

API'nizin bu risklere karşı gerçekte nasıl davrandığını görmenin yolu, yetkili bir sızma testidir. Sürecin nasıl işlediğini ve rapordan ne beklemeniz gerektiğini sızma testi rehberimizde anlattık; test hizmeti için güvenlik ve sızma testi sayfamıza bakabilirsiniz. Kişisel veri işleyen API'ler için erişim kaydı, şifreleme ve yetki matrisi gibi tedbirlerin listesini ise KVKK teknik ve idari tedbirler yazısında bulabilirsiniz.