Çoğu işletme sahibi, bayi API'sini "ileride lazım olur" diye rafa kaldırılan bir teknik detay sanır. Panelini kurar, fiyat listesini hazırlar, bayilerini WhatsApp grubuna toplar ve günde yüzlerce siparişi elle işlemeye başlar. İlk üç ay sorun yok gibi görünür; çünkü hacim düşükken insan gücü hatayı gizler. Sonra bir gün, cirosunun yarısını getiren o büyük bayin sana tek bir cümle yazar: "Biz artık manuel çalışmıyoruz, sizin API'niz var mı?" İşte o an, kullandığın dijital ürün satış scriptinin gerçek sınırı ortaya çıkar.
Gerçek şu: bayi API'si bir "özellik" değil, bir satış kanalıdır. Bayin senin panelini açıp tek tek kod kopyalamak zorunda kaldığı sürece, senin stoğun onun sitesinde görünmez; görünmeyen stok satılmaz. Bu yazıda, bir e-pin satış scriptinde bayi API erişiminin nasıl kurulması gerektiğini, hangi çağrıların zorunlu olduğunu, hangi güvenlik katmanlarının atlanınca tek gecede kasa boşalttığını ve Pinova gibi hazır bir e-pin yazılımı tercih ederken neye bakman gerektiğini adım adım açacağım. Teknik olmayan bir işletme sahibi olsan bile sonuna kadar takip edebileceksin.
Bayi API'sini neden çoğu script sonradan ekliyor?
Piyasadaki hazır sistemlerin büyük kısmı "vitrin öncelikli" doğar. Yani önce güzel bir ana sayfa, sonra sepet, sonra ödeme yazılır. Bayi tarafı ise genellikle panelde ayrı bir fiyat listesi olarak eklenir. Sonuç: bayi, son kullanıcı akışının içine sıkıştırılmış bir kullanıcı tipine dönüşür. API'yi bu mimarinin üstüne sonradan eklemek, evi yaptıktan sonra temele kolon eklemeye benzer.
Doğru yaklaşım tersidir. Sipariş oluşturma, stok düşme, teslimat ve iade mantığı tek bir servis katmanında durur; web arayüzü de bayi API'si de aynı katmanı çağırır. Böylece panelden verilen siparişle API'den gelen sipariş aynı kuralları yaşar. Bu ayrım yapılmamışsa, API'den gelen istek stok kontrolünü atlar ve sen "satılmış ama teslim edilememiş" kod yığınıyla uğraşırsın. Bir dijital ürün satış yazılımını değerlendirirken sorman gereken ilk teknik soru bu: API ile panel aynı iş kurallarını mı kullanıyor?
API anahtarı mı token mı? Kimse bunu açıkça söylemiyor
Bayi entegrasyonlarında en sık görülen zafiyet, ömür boyu geçerli tek bir API anahtarının bayiye e-posta ile gönderilmesidir. O anahtar bayinin geliştiricisinin bilgisayarında, bir GitHub deposunda ve iki eski çalışanın telefonunda yaşar. Anahtarı iptal edemezsin, çünkü iptal edince bayinin tüm satışı durur ve seni arar.
Uygulanabilir çözüm üç katmanlıdır. Birincisi, her bayi için birden fazla anahtar üretilebilmesi ve her anahtarın ayrı ayrı pasife alınabilmesi. İkincisi, kısa ömürlü erişim token'ı: anahtar sadece token almak için kullanılır, asıl çağrılar token ile yapılır. Üçüncüsü, IP kısıtı ve imzalı istek. İmza, isteğin gövdesinin gizli bir sır ile hash'lenmesidir; araya giren biri tutarı değiştirirse imza bozulur. Bu üçlüyü destekleyen bir e-pin satış yazılımı, anahtar sızıntısını krize değil, on dakikalık bir bakım işine çevirir.
| Çağrı | Ne yapar | Zorunlu mu | Atlanırsa sonuç |
|---|---|---|---|
| /products | Bayiye özel fiyatlı ürün listesi döner | Zorunlu | Bayi fiyatı elle günceller, yanlış satış |
| /stock | Anlık stok adedini verir | Zorunlu | Stokta olmayan ürün satılır |
| /order/create | Sipariş açar, referans üretir | Zorunlu | Entegrasyon anlamsız kalır |
| /order/status | Siparişin son durumunu bildirir | Zorunlu | Bayi destek hattını kilitler |
| /balance | Cari ve kullanılabilir limiti verir | Önerilir | Bakiye yetmezliği satışta anlaşılır |
| /webhook | Teslimat tamamlandı bildirimi gönderir | Önerilir | Bayi sürekli sorgu atar, yük artar |
| /refund | İade veya iptal talebi açar | Opsiyonel | İade süreci manuel yürür |
Stok sorgusu olmayan bir API neden bayini kaçırır?
Bayinin kendi sitesi vardır ve orada senin ürünlerini listeler. Eğer stok bilgisini anlık alamıyorsa iki kötü seçenekten birini yapar: ya ürünü sürekli "stokta" gösterir ve satılamayan siparişlerle müşterisini kaybeder, ya da ihtiyatlı davranıp ürünü hiç listelemez. İkinci durumda sen hiçbir şey kaybetmediğini sanırsın; oysa görünmeyen bir ciro kaybı yaşarsın.
İyi bir epin yazılım mimarisinde stok iki biçimde sunulur: toplu liste ve tek ürün sorgusu. Toplu liste önbelleğe alınabilir, tek ürün sorgusu ise satış anında çağrılır. Ayrıca eşik bildirimi önemlidir: stok belirlediğin adedin altına düştüğünde bayiye webhook gider, bayi ürünü kendi sitesinde otomatik pasife alır. Bu küçük detay, iki taraflı iptal maliyetini neredeyse sıfırlar.
Bayi entegrasyonlarında yaşanan sorunların dağılımı
- Stok ve fiyat tutarsızlığı 40%
- Çift sipariş ve teslimat 28%
- Kimlik doğrulama hataları 20%
- Zaman aşımı ve yük 12%
Sipariş çağrısında idempotency yok mu? Çift teslimat kapıda
Bu, entegrasyonun en pahalı maddesidir. Bayi /order/create çağrısını yapar, senin sunucu siparişi açar, kodu ayırır ama cevap ağ üzerinde kaybolur. Bayinin sistemi cevap alamadığı için isteği tekrar gönderir. Sonuç: iki sipariş, iki kod, tek tahsilat. Bu senaryo teoride kalmaz; yoğun kampanya saatlerinde haftada birkaç kez yaşanır.
Çözümün adı idempotency key'dir. Bayi her sipariş için kendi tarafında benzersiz bir referans üretir ve isteğe ekler. Sunucu bu referansı daha önce gördüyse yeni sipariş açmaz, ilk siparişin sonucunu aynen döner. Böylece bayi isteği yüz kez tekrarlasa bile tek kod düşer. Bunun yanında sipariş durumları net tanımlanmalıdır: beklemede, ayrıldı, teslim edildi, iptal, iade. Belirsiz bir "işleniyor" durumu, bayinin destek yükünü üçe katlar.
Bayine test ortamı ver ve test anahtarında gerçek kod düşmeyen sahte stok tut. Entegrasyonu canlıda deneyen her bayi, ortalama 15-20 kodunu çöpe atar; bu maliyeti sen ödersin.
Rate limit, log ve webhook üçlüsü neden pazarlıkta konuşulmaz?
Bayinin sistemi bozulduğunda ilk belirti senin sunucunda görülür. Döngüye giren bir kod, saniyede yüzlerce stok sorgusu atar ve veritabanını yavaşlatır; son kullanıcıların sepeti açılmaz. Bu yüzden bayi başına oran sınırı şart: dakikada kaç sorgu, kaç sipariş. Sınır aşıldığında isteği reddetmek kaba görünür ama tüm sistemi ayakta tutar.
İkinci parça kayıt tutmadır. Her API isteğinin zaman damgası, kaynak IP'si, gönderilen gövdesi ve dönen yanıtı saklanmalı. Bayi "ben o siparişi vermedim" dediğinde tek savunman bu kayıttır. Üçüncü parça webhook: teslimat tamamlandığında bayiye bildirim gönder, imzala, başarısız olursa artan aralıklarla yeniden dene. Sorgulamayı bildirime çevirmek, sunucu yükünü tipik olarak üçte birine indirir ve bayinin müşterisine teslim süresini kısaltır. Pinova'nın entegrasyon yaklaşımını özellikler bölümünde daha ayrıntılı görebilirsin.
Kendi API'ni açmadan önce hangi kararları vermelisin?
API açmak teknik bir iş gibi görünse de aslında ticari bir karardır. Fiyat politikanı, iade kuralını ve limit mantığını netleştirmeden yazılan API, her yeni bayide istisna ister; istisnalar da bir süre sonra bakımı imkânsız bir yamaya dönüşür. Aşağıdaki kontrol listesini, geliştiriciyle konuşmadan önce kendi başına doldur.
| Kontrol | Ne sormalısın | Kabul ölçütü |
|---|---|---|
| Kimlik doğrulama | Anahtar iptal edilebiliyor mu | Bayi başına çoklu anahtar + IP kısıtı |
| Idempotency | Aynı referans iki kez gelirse ne olur | İlk sonuç döner, yeni kod düşmez |
| Stok | Anlık sorgu var mı | Tek ürün sorgusu + eşik webhook'u |
| Fiyat | Bayiye özel liste API'de görünüyor mu | Kademeli fiyat aynı yanıtta |
| Limit | Bakiye yetmezse ne döner | Net hata kodu, kısmi teslimat yok |
| Kayıt | İstek gövdeleri saklanıyor mu | En az 90 gün geriye dönük kayıt |
| Dokümantasyon | Bayi tek başına bağlanabilir mi | Örnek istek-yanıt + test ortamı |
| Sürüm | Alan eklenince eski bayi bozulur mu | Sürümlü yol veya geriye uyumluluk |
Bayi API'sini sıfırdan yazmak zorunda değilsin
Pinova, panel ve API'yi aynı iş kuralları üzerine kuran lisanslı bir dijital ürün satış yazılımı. Idempotency, stok webhook'u, oran sınırı ve kayıt altyapısı kurulumdan itibaren hazır gelir.
Bayi API'si için ayrı sunucu gerekir mi?
Başlangıçta gerekmez. Ancak API trafiği toplam isteklerin yarısını aştığında, sorgu yükünü ayrı bir okuma katmanına taşımak hem vitrini hem bayiyi rahatlatır.
Bayime hangi dokümanı vermeliyim?
Her endpoint için örnek istek, örnek yanıt, hata kodları tablosu ve bir test anahtarı yeterlidir. Bu paket olmadan entegrasyon süresi günlerden haftalara çıkar.
API'den gelen siparişte fiyat değişirse ne olur?
Fiyat, sipariş oluşturulduğu anda kilitlenmelidir. Bayinin gördüğü fiyatla düşen tutar farklı olursa mutabakat imkânsızlaşır ve güven kaybı yaşarsın.
Küçük bayilere de API vermeli miyim?
Vermelisin ama sınırlı oranla. Küçük bayi çoğunlukla paneli kullanır; API'yi açık tutmak ise o bayinin büyüdüğünde seni bırakmaması için en güçlü sebeptir.
Bayi API'si, dijital ürün işinde büyümenin görünmez motorudur: kimse ana sayfanda görmez ama cironun büyük kısmını o taşır. Fiyat seçeneklerini fiyat bölümünden karşılaştırabilir, entegrasyon akışının panelde nasıl göründüğünü merak ediyorsan canlı demo üzerinden kendi elinle deneyebilirsin. Bir bayinin "API'niz var mı?" sorusuna "evet, dokümanı gönderiyorum" diye cevap verdiğin gün, işin gerçekten ölçeklenmeye başlar.