Çoğu satıcı açık API'yi teknik bir süs, ileride belki lazım olacak bir kutu olarak görür. Gerçek ise şu: dijital ürün pazarında ölçek, sitene gelen ziyaretçi sayısıyla değil, senin stoğunu kendi vitrininde satan iş ortaklarının sayısıyla büyür. Bir bayi sana günde beş kez elle sipariş veriyorsa o bir müşteridir; API üzerinden otomatik sipariş açıyorsa o bir dağıtım kanalıdır. Arasındaki fark, bir yazlık kiracı ile kalıcı bir boru hattı arasındaki farktır.
Ama burada ikinci bir gerçek var: kötü tasarlanmış bir API, hiç olmamasından daha zararlıdır. Aynı siparişin iki kez düşmesi, stok sorgusunun tedarikçi fiyatını sızdırması, hız limiti olmadığı için tek bir bayinin döngüye girip sunucuyu yatırması. Bunların hepsi sahada görülmüş senaryolardır. İyi bir e-pin satış scripti açık API'yi "kapıyı açmak" olarak değil, "kapıya ölçülü ve kilitli bir geçit takmak" olarak kurar. Bu yazıda o geçidin nasıl tasarlandığını kaynak modelinden hata sözleşmesine kadar anlatıyorum.
Açık API'yi kapı açmak mı, geçit kurmak mı diye düşünmelisin?
Bu soruyu en başta cevaplamak, sonraki bütün kararları kolaylaştırır. Açık API'nin amacı, dışarıdan gelen bir programın senin iş kurallarını atlamadan iş yapabilmesidir. Yani API katmanı panelin bir kopyası değil, panelin arkasındaki aynı kuralların farklı bir kapısıdır. Fiyat hesabı, bayi indirimi, stok ayırma ve limit kontrolü tek bir servis katmanında yaşamalı; panel de API de o katmanı çağırmalı. Bu ilkeyi çiğneyip API için ayrı bir mantık yazdığın gün iki gerçek oluşur: panelden verilen siparişle API'den verilen sipariş farklı davranır, ve bu fark ilk önce muhasebede sonra müşteri ilişkilerinde patlar. Dijital ürün satış yazılımı tarafında tek kaynak kuralı pazarlıksızdır.
Kaynak tasarımı: sipariş mi, teslimat mı, stok mu?
Uç nokta listesini işin kavramlarına göre kurmalısın, veritabanı tablolarına göre değil. Pratikte bir e-pin işini besleyen beş kaynak yeter: katalog (ürün ve varyant listesi), fiyat/stok (bayiye özel fiyat ve anlık uygunluk), sipariş (oluştur, sorgula), teslimat (sipariş altındaki kodlar), hesap (bakiye ve hareketler). Dikkat edilecek nokta teslimatı siparişten ayırmaktır: bir sipariş anında teslim edilemeyebilir, kısmi teslim edilebilir veya iade edilebilir. Teslimatı ayrı kaynak yaparsan bu durumların hepsini temiz modellersin. Ayrıca kod değerini yalnızca teslimat kaynağından, yalnızca tek seferlik ve yetki doğrulanmış bir istekle dön; katalog veya sipariş yanıtının içine asla gömme.
| Kaynak | Tipik metot | Hız limiti önerisi | Önbellek | Kritik kural |
|---|---|---|---|---|
| Katalog | GET liste / detay | 120 istek / dk | 5-15 dakika | Değişiklikte sürüm damgası dön |
| Fiyat ve stok | GET, toplu sorgu destekli | 300 istek / dk | 10-30 saniye | Tedarikçi maliyeti asla görünmez |
| Sipariş | POST oluştur / GET sorgula | 60 istek / dk | Yok | Idempotency anahtarı zorunlu |
| Teslimat | GET (yetkiye bağlı) | 60 istek / dk | Yok | Kod gösterimi kayda geçer |
| Hesap / bakiye | GET özet, GET hareket | 30 istek / dk | Yok | Sayfalama imleç tabanlı olur |
| Webhook | Giden POST | Kuyruk + geri çekilme | Yok | İmzalı gövde, tekrar gönderim |
Aynı siparişi iki kez göndermek: idempotency neden pazarlıksız?
Şu senaryoyu yaşamayan entegratör yoktur: bayinin sistemi sipariş isteğini gönderir, senin sunucun siparişi oluşturur ama yanıt ağda kaybolur. Bayi tarafı zaman aşımı görür ve isteği tekrarlar. Sonuç: iki sipariş, iki kod, tek ödeme. Bunun tek doğru çözümü, sipariş oluşturan her isteğin bayi tarafından üretilmiş bir Idempotency-Key başlığı taşıması ve senin bu anahtarı en az 24 saat saklamandır. Aynı anahtar ikinci kez geldiğinde yeni sipariş açmaz, ilk siparişin yanıtını aynen tekrar dönersin. Anahtar aynı ama gövde farklıysa net bir çakışma hatası verirsin. Bu üç satırlık kural, sahada gördüğüm mutabakat kavgalarının büyük bölümünü baştan siler ve e-pin scripti tarafında en yüksek getirili tek tasarım kararıdır.
Aktif bayi entegrasyonlarında API çağrılarının dağılımı
- Stok ve fiyat sorgusu 45%
- Sipariş oluşturma 25%
- Teslimat ve durum sorgusu 20%
- Bakiye, webhook ve diğer 10%
Kimlik doğrulama ve anahtar yönetimi nasıl kurulur?
Basit tutarken sağlam tutmak mümkün. Her bayiye bir anahtar çifti ver: açık bir istemci kimliği ve gizli bir sır. İstekler Authorization başlığıyla gelir, sır hiçbir zaman adres satırında taşınmaz. Sırları veritabanında düz metin saklama; hash'le ve yalnızca oluşturma anında bir kez göster. Her anahtara üç özellik bağla: izin kapsamı (sadece okuma, sipariş açma, teslimat görme), IP kısıtı ve son kullanma tarihi. Anahtar döndürme (rotation) akışını baştan yaz: bayi yeni anahtar üretir, iki anahtar bir hafta birlikte çalışır, sonra eskisi otomatik ölür. Kesinti olmadan anahtar değiştirilemeyen bir sistem, bir sızıntı anında ya kesinti ya risk seçmeye zorlar. Ek olarak yüksek riskli işlemlerde gövde imzası isteyerek araya girmeyi zorlaştırabilirsin.
Hız limiti, sayfalama ve webhook: sistemi kim yatırır?
Genelde saldırgan değil, iyi niyetli ama kötü yazılmış bir bayi entegrasyonu yatırır. Bu yüzden hız limiti bir cezalandırma değil, ortak koruma aracıdır. Limiti anahtar bazında uygula, kalan kotayı yanıt başlıklarında bildir ve limit aşımında net bir bekleme süresi dön; böylece karşı taraf doğru davranmayı öğrenir. Sayfalamada sayfa numarası yerine imleç (cursor) kullan, çünkü sürekli değişen sipariş listesinde sayfa numarası veri atlamaya yol açar. En önemlisi: bayiyi durum sorgusu yapmaya mahkûm etmek yerine webhook gönder. Siparişin teslim edildiği, iptal edildiği veya stoğun bittiği anda imzalı bir bildirim yollarsan hem gereksiz trafiği yüzde altmış azaltırsın hem de karşı tarafın sistemi gerçek zamanlı çalışır. Webhook'larda üç şey şart: imza, tekrar gönderim politikası ve tekrarlanan bildirimleri tanımak için olay kimliği.
| Kontrol maddesi | Neden gerekli | Doğrulama | Öncelik |
|---|---|---|---|
| Sipariş ucunda Idempotency-Key zorunlu | Mükerrer siparişi keser | Aynı anahtarla iki kez gönder | Kritik |
| Anahtar kapsamı ve IP kısıtı tanımlı | Sızan anahtarın etkisini daraltır | Yetkisiz uca istek dene | Kritik |
| Tedarikçi maliyeti yanıtta yok | Ticari sır korunur | Ham JSON yanıtını denetle | Kritik |
| Hız limiti ve kalan kota başlıkları | Sunucuyu korur, entegratörü yönlendirir | Limit aşana kadar döngü kur | Yüksek |
| İmleç tabanlı sayfalama | Veri atlamasını önler | Liste değişirken sayfa gez | Yüksek |
| Webhook imzası ve olay kimliği | Sahte bildirimi ve tekrarı engeller | İmzayı bozup gönder | Kritik |
| Adreste sürüm (/v1/) var | Kırıcı değişikliği yönetir | Sürümsüz adres 404 dönmeli | Yüksek |
| Hata gövdesi standart ve makine-okunur | Entegrasyon süresini kısaltır | Her hata kodu için örnek üret | Orta |
| Test ortamı ve sahte stok mevcut | Bayi canlıda deneme yapmaz | Test anahtarıyla akışı tamamla | Yüksek |
Her hata yanıtında sabit bir makine kodu (stok_yetersiz, bakiye_yetersiz, limit_asildi), okunabilir bir açıklama ve istek kimliği bulunsun. Entegratör metni değil kodu kontrol eder; mesajı sonradan düzeltmek istediğinde kimsenin entegrasyonu kırılmaz.
Sürümleme ve dokümantasyon: entegrasyonu bir güne indiren şey
API'nin kalitesi, onu ilk kez gören bir geliştiricinin ne kadar hızlı ilk başarılı siparişi açtığıyla ölçülür. Bu süreyi kısaltan üç şey var. Birincisi adreste açık sürüm: /api/v1/. Alan eklemek kırıcı değişiklik sayılmaz, ama alan silmek veya anlamını değiştirmek sayılır; böyle bir ihtiyaçta v2 açıp v1'i en az altı ay yaşatırsın. İkincisi makine okunabilir şema: OpenAPI dosyası verdiğinde karşı taraf istemci kodunu kendisi üretir. Üçüncüsü kopyala-çalıştır örnekler: cURL, PHP ve Node için üç satırlık örnekler, sayfalar dolusu anlatımdan daha etkilidir. Bir de test ortamı ver; sahte stok ve sahte bakiyeyle çalışan bir sanal alan olmadan hiçbir ciddi bayi entegrasyona başlamaz. Bu yatırımı yapan bir dijital ürün satış scripti, bayisini kendi ekibine yük olmadan kazanır.
Bayilerin senin stoğunu kendi sitesinde satsın
Pinova, sürümlü uç noktalar, anahtar yönetimi ve webhook altyapısıyla bayi entegrasyonlarını ilk günden taşıyacak şekilde tasarlandı. Entegrasyon katmanına bak, paketleri karşılaştır.
Açık API vermek rakibime stok listemi mi açar?
Doğru tasarımda hayır. Katalog yanıtında yalnızca satılabilir ürün ve bayiye özel satış fiyatı yer alır; tedarikçi maliyeti, kaynak bilgisi ve toplam stok adedi dışarı çıkmaz. Stoğu "var / az / yok" gibi kademeli göstermek de yaygın ve güvenli bir yaklaşımdır.
REST mi kullanmalıyım, başka bir yaklaşım daha mı iyi?
Bayi entegrasyonları için REST açık ara en pratik seçimdir; her dilde hazır istemci var, önbellekleme ve hız limiti doğal çalışır. Daha modern alternatifler esneklik verir ama karşı tarafın öğrenme maliyetini yükseltir; dağıtım kanalı kurarken bu maliyet doğrudan entegrasyon sayına yansır.
Webhook göndermek yerine bayi sorgulasa olmaz mı?
Olur ama pahalıya gelir. Sürekli durum sorgusu sunucunu gereksiz yükler ve teslimat bildirimini dakikalarca geciktirir. Webhook ile bildirim anında gider; yine de her webhook'un yanına bir durum sorgu ucu koy, çünkü bildirim kaybolabilir ve karşı tarafın telafi yolu olmalı.
Hız limitini ne kadar sıkı tutmalıyım?
Uca göre farklı tut. Stok sorgusu bol, sipariş açma orta, bakiye hareketi kısıtlı olsun. Kalan kotayı yanıt başlığında bildir ve aşımda bekleme süresi dön; iyi bilgilendirilmiş bir entegratör limiti zorlamak yerine kendi tarafında önbellek kurar.
Açık API, dijital ürün işinde ekip büyütmeden ciro büyütmenin en sessiz yoludur; bir kez doğru kurulduğunda her yeni bayi sana ek iş yükü değil ek hacim getirir. Uç noktaların, anahtar yönetiminin ve webhook akışının gerçek bir kurulumda nasıl çalıştığını görmek için canlı demo üzerinden bir test anahtarı oluştur, örnek siparişi baştan sona kendi elinle geçir; boru hattını kurmaya karar verdiğinde lisans adımı tek kalan iş olacak.