Çoğu işletme sahibi bayiye API vermenin teknik bir ayrıntı olduğunu sanır. "Bir anahtar üretirim, dokümanı atarım, gerisi yazılımcısının işi" diye düşünür. Oysa API açtığın an yaptığın şey entegrasyon değil; kasanın yedek anahtarını, çalışma saatlerini ve kaç kere açılabileceğini bir yabancıya devretmektir. Ve o yabancı kötü niyetli olmak zorunda bile değil: acele yazılmış bir döngü, yanlış kurulmuş bir cron, panik anında üç kere basılan bir buton yeter.
Bu yazıda bayi API'sinin gerçekte nasıl patladığını, hangi limitlerin hangi riski kapattığını ve bir e-pin scripti tarafında hangi katmanların önceden kurulu olması gerektiğini anlatacağım. Amacım seni korkutmak değil; API'yi kapatmak yerine sınırlarıyla açmayı öğretmek. Çünkü sınırsız API veren işletme, aslında bayisine değil kendi bilançosuna güveniyor.
API vermek "entegrasyon" değil, kasanın yedek anahtarını teslim etmektir
Panelden sipariş veren bayi ile API'den sipariş veren bayi aynı müşteri değildir. Panelde insan hızı vardır: tıklar, bakar, düşünür, yanlış yaparsa görür. API'de makine hızı vardır. Saniyede 40 istek atan bir script, sen telefonunu eline alana kadar günlük stoğunu tüketmiş olur. Bu yüzden API katmanını panelin bir kopyası gibi düşünmek en pahalı hatadır.
Doğru kurgu şöyle başlar: her bayi için ayrı kimlik, ayrı anahtar, ayrı limit profili. Ortak bir anahtar, ortak bir kaderdir; bir bayinin sızan anahtarı yüzünden tüm hattı kapatmak zorunda kalırsın. İyi bir e-pin satış scripti bayi kaydını açarken anahtarı da, limitleri de, izin verilen ürün grubunu da aynı ekranda sorar. Sormuyorsa o iş sonradan sana kalır ve sonradan kalan iş hiç yapılmaz.
Bir de şu var: API'yi açtığın an bayinin altındaki son kullanıcı da dolaylı olarak senin sistemine bağlanmış olur. Yani trafiğin kaynağı artık bayi değil, bayinin müşterisi. Kapasite planını buna göre yapmalısın.
Token'ı kim taşıyor? Bayinin geliştiricisi mi, sen mi?
Anahtarların çoğu hack'lenmez, paylaşılır. WhatsApp grubuna düşer, GitHub'a commit edilir, freelance yazılımcının eski laptopunda kalır. Bu yüzden token güvenliğini "gizli tutmak" üzerine kurmak yetmez; token'ın yetkisini daraltmak ve ömrünü kısaltmak gerekir.
Uygulaması kolay üç kural var. Birincisi: her anahtarın sadece kendi ihtiyacı olan yetkisi olsun. Sipariş açan anahtarın bakiye çekme veya fiyat güncelleme yetkisi olmasın. İkincisi: IP kısıtı. Bayi sabit IP'den çalışıyorsa anahtarı o IP'ye kilitle; sızsa bile başka yerden işe yaramaz. Üçüncüsü: rotasyon. Anahtar tek tuşla yenilenebiliyorsa şüphe anında tereddüt etmezsin, yenilersin. Yenilemek zor olduğu an, insanlar riski yönetmek yerine görmezden gelir.
Bir dijital ürün satış yazılımı seçerken şunu sor: anahtar iptal edildiğinde açık siparişler ne oluyor? Doğru cevap "işlemekte olanlar tamamlanır, yenileri reddedilir" olmalı. Aksi halde güvenlik hamlesi, teslim edilmemiş sipariş yığınına dönüşür.
| Risk | Belirti | Kapatan katman | Aciliyet |
|---|---|---|---|
| Limitsiz istek | Ani stok erimesi, sunucu yükü | Rate limit + günlük kota | Kritik |
| Sızmış anahtar | Tanımadığın IP'den çağrı | IP kısıtı + rotasyon | Kritik |
| Tekrarlı sipariş | Aynı ürün üst üste teslim | Idempotency anahtarı | Yüksek |
| Fazla yetki | Bayi fiyat/bakiye görüyor | Scope (yetki kapsamı) | Yüksek |
| İzsiz işlem | İtirazı ispatlayamamak | Değişmez işlem logu | Orta |
| Zaman aşımı sarkması | Bayi "teslim gelmedi" diyor | Webhook + durum sorgusu | Orta |
Kota koymayan herkes aynı gece yarısı uyanıyor: rate limit gerçekte neyi korur?
Rate limit'i sunucuyu korumak için koyduğunu sanırsın. Aslında stoğunu ve marjını korur. Çünkü e-pin dünyasında en pahalı olay sunucunun yavaşlaması değil; yanlış fiyatla veya tükenmiş havuzdan satış yapmandır. Saniyede 5 istekle sınırlı bir bayi, fiyat listenin güncellenmediği o 90 saniyelik boşlukta en fazla 450 istek atar. Limitsiz bayi aynı boşlukta on binlerce.
Pratikte üç katmanlı kota işe yarar: saniyelik (ani patlamayı keser), günlük adet (toplam maruziyeti sınırlar), tutar bazlı (pahalı ürünlerde zararı çerçeveler). Üçünü birlikte kurmadan "API güvenli" demek doğru olmaz. Bir de yumuşak eşik ekle: kotanın %80'ine gelince bayiye de sana da bildirim gitsin. Böylece limit bir ceza değil, birlikte yönetilen bir plan hâline gelir.
Kotanın bayi bazında farklı olması da normaldir. Üç yıllık, düzenli ödeme yapan bayiye tanıdığın alan ile dün kaydolan bayiye tanıdığın alan aynı olmamalı. Bunu manuel tabloda tutmak yerine, epin yazılım tarafında bayi seviyesine bağlı otomatik limit profilleri kurgulamak en sağlıklısı.
API kaynaklı zararın gerçek dağılımı
- Kota/limit eksikliği 40%
- Sızmış veya paylaşılmış anahtar 25%
- Tekrarlı istek (idempotency yok) 20%
- Diğer / insan hatası 15%
Bakiye mi, kredi limiti mi? API'de asıl riski nerede taşıyorsun
Panelde bakiyesi biten bayi durur. API'de bakiyesi biten bayi, eğer sistem "sonra tahsil ederim" mantığıyla kuruluysa, durmaz. Burada verdiğin karar teknik değil ticari bir karardır: ön ödemeli mi, kredi limitli mi çalışacaksın?
Ön ödemeli model API için en güvenlisidir çünkü risk sıfırdır: bakiye yoksa istek reddedilir. Kredi limitli model büyüme sağlar ama üç şeyi zorunlu kılar: net limit, otomatik durdurma eşiği ve gecikme halinde kademeli kısıtlama. "Bu bayi iyi çocuk, aşarsa aşar" cümlesi tahsilat sürecine giren her dosyanın başlangıcıdır.
Bir ara model de var ve çoğu işletme için en dengelisi: ön ödemeli bakiye + küçük bir tampon kredi. Bayi bakiyesi bittiğinde sistem tamamen kapanmaz, tampon kadar devam eder, tampon dolunca durur. Böylece gece yarısı satışını kaçırmaz, sen de kontrolsüz açığa düşmezsin. Tampon miktarını bayinin son 30 günlük ortalamasına oranlamak iyi bir kuraldır.
API cevaplarında hata kodlarını ayrıştır. "Yetersiz bakiye", "kota aşıldı" ve "ürün tükendi" aynı mesajı döndürüyorsa bayinin yazılımcısı her üç durumda da yeniden dener ve sorunu büyütür.
Idempotency: aynı siparişi üç kere işleyen bayi senin hatandır
Bu kelime kulağa teknik geliyor ama anlamı çok basit: aynı isteği iki kere gönderirsen ikinci kez işlem yapılmaz, ilk sonuç geri döner. Bayi tarafında zaman aşımı olduğunda script tekrar dener; ağ koptuğunda tekrar dener; kullanıcı butona bastığında tekrar dener. Sende koruma yoksa üç kere satmış, üç kere teslim etmiş ve bir kere para almış olursun.
Çözüm, her sipariş isteğinde bayinin ürettiği tekil bir referansı zorunlu kılmaktır. Aynı referans tekrar gelirse yeni kayıt açmaz, mevcut kaydın durumunu döndürürsün. Bunu e-pin satış yazılımı tarafında ürünün tesliminden önceki adıma koymak şart; sonrasına koyarsan kod zaten çıkmış olur ve geri alamazsın.
İkinci koruma: durum sorgusu (status) endpoint'i. Bayi "acaba oldu mu?" sorusunu tekrar sipariş vererek değil, durum sorarak çözebilsin. Bu tek endpoint'i dokümanın en üstüne koy; destek yükünün önemli bir kısmı oradan gelir.
| Kontrol | Ne zaman yapılır | Tamam mı? |
|---|---|---|
| Bayi başına ayrı anahtar ve limit profili | Bayilik açılışında | Zorunlu |
| Saniyelik + günlük + tutar kotası | API açılmadan önce | Zorunlu |
| Idempotency referansı zorunlu alan | İlk entegrasyon testinde | Zorunlu |
| IP kısıtı ve anahtar rotasyon tuşu | Kurulumda | Zorunlu |
| Durum sorgusu ve webhook | Dokümantasyonla birlikte | Yüksek öncelik |
| Kota %80 bildirimi | İlk aydan itibaren | Önerilir |
| Sandbox / test ortamı | Bayi yazılımcısına teslimde | Önerilir |
| Değişmez işlem logu ve dışa aktarım | Sürekli | Zorunlu |
Log tutmayan bayilikten çıkış yoktur: denetim izi neden pazarlık gücü?
Bir bayi bir gün "bu 40 sipariş bende yok, iade edin" diyecek. O gün elinde ne varsa haklısın; ne yoksa değilsin. Bu yüzden log tutmak muhasebe işi değil, ticari savunma işidir. Kaydın içinde isteğin zamanı, kaynağı, kullanılan anahtar, gönderilen referans, dönen cevap ve teslim edilen içeriğin kimliği olmalı.
Logun bir de gündelik faydası var: hangi bayinin hangi saatte hangi ürüne yığıldığını görürsün. Bu veri stok planından kampanya tasarımına kadar her şeyi besler. Ve en önemlisi, sorun çıktığında tartışma "sen dedin / ben dedim"den çıkıp kayıt üzerine oturur. İyi kurulmuş bir dijital ürün satış scripti bu izleri kendiliğinden tutar; sen sonradan eklemek zorunda kalmazsın.
Pinova'da bayi API katmanı tam olarak bu mantıkla çalışır: anahtar bazlı yetki, üç katmanlı kota, zorunlu tekil referans, ayrıntılı işlem izi ve bayi seviyesine bağlı otomatik limit profilleri. Yani API'yi açmak için cesaret değil, hazır kurulmuş sınırlar gerekiyor.
Bayi API'sini korkmadan aç
Kota, yetki kapsamı, tekil referans ve denetim izi kutudan çıkar hâlde gelsin; sen büyümeye odaklan.
Bayiye API vermek riskli mi, hiç vermesem olur mu?
API vermemek büyümeyi keser; kurumsal bayiler kendi sistemlerinden satmak ister. Risk API'nin kendisinde değil, limitsiz açılmasında. Kota, yetki kapsamı ve tekil referans kurulduğunda API panelden daha güvenli hâle gelir.
Rate limit değerlerini neye göre belirlemeliyim?
Bayinin son 30 günlük gerçek trafiğini al, tepe noktasının iki katını saniyelik limit yap. Günlük adet limitini ortalama cironun 1,5 katına oturt. Sonra %80 eşiğinde bildirim kur ve veriyle her ay revize et.
Idempotency yoksa ne kadar zarar görürüm?
Tekrarlı istekler genelde toplam siparişin küçük bir yüzdesidir ama e-pin gibi geri alınamaz üründe her tekrar doğrudan zarardır. Zaman aşımlarının yoğun olduğu kampanya günlerinde bu oran ciddi biçimde yükselir.
Bayinin anahtarı sızdıysa ilk ne yapmalıyım?
Anahtarı iptal edip yenisini üret, o anahtarla geçmiş 24 saatteki tüm işlemleri logdan çıkar, IP kısıtı ekle ve şüpheli teslimatları dondur. İşlemekte olan siparişleri tamamlayıp yeni istekleri reddeden bir kesim en az kayıplı yöntemdir.
API'yi açmak bir cesaret testi değil, bir mimari kararıdır. Limitleri, yetkileri ve izleri önceden kurduğunda bayine "hayır" demek zorunda kalmazsın; sistem senin yerine nazikçe sınırı çizer. Katmanların canlıda nasıl davrandığını kendi gözünle görmek istersen canlı demo üzerinden bayi API ekranlarını, kota profillerini ve işlem loglarını inceleyebilir, paket seçeneklerini buna göre değerlendirebilirsin.