SMM sektöründe bayilik, bir panelin API'sine bağlanıp o servisleri kendi siteniz, botunuz ya da uygulamanız üzerinden satmak demektir. Müşteri paneli hiç görmez; siparişi size verir, sizin sisteminiz arka planda siparişi iletir. Bu yazıda entegrasyonun nasıl kurulduğunu ve güvenilir çalışması için nelerin ele alınması gerektiğini anlatıyoruz.
API v2 standardı ne kapsıyor?
Panellerin büyük çoğunluğu sektörde "API v2" denen bir arayüz sunar. Bu resmî bir şartname değil, zaman içinde oturmuş bir gelenektir ve pratik faydası taşınabilirliktir: bir panele göre yazılmış kod, genellikle küçük değişikliklerle başka bir panelde de çalışır.
Uç nokta kümesi küçük ve tahmin edilebilirdir. Bir API anahtarı ve bir action parametresiyle istek gönderir, karşılığında JSON alırsınız. Beş eylem neredeyse her şeyi kapsar.
- services — kimlik, ad, fiyat, en az ve en çok miktar bilgileriyle tüm kataloğu döndürür.
- add — servis kimliği, hedef bağlantı ve miktarla sipariş oluşturur; sipariş kimliği döner.
- status — siparişin durumunu, ücretini, başlangıç sayısını ve kalan miktarı bildirir.
- balance — güncel bakiyenizi döndürür.
- refill — destekleyen servislerde telafi talebi açar.
Paneller çoğunlukla birden çok sipariş kimliğini tek çağrıda alan bir toplu durum sorgusu da sunar. Bunu kullanmak önemlidir: yüz siparişi tek tek sorgulamak hem yavaştır hem de hız sınırına takılır.
Servis eşleştirme: her şeyi belirleyen katman
Bir bayi sisteminin en önemli tasarım kararı, panel servislerini kendi ürünlerinize nasıl eşleştirdiğinizdir. Panel kataloğunu olduğu gibi göstermek ilk bakışta pratik görünür ama kısa sürede sorun çıkarır: panel servis kimlikleri değişebilir, servisler kapanabilir ve servis adları müşterinizin okumasına gerek olmayan teknik etiketler taşır.
Sağlam yaklaşım bir ara katman kurmaktır. Kendi ürünlerinizi kendi adlarınız ve açıklamalarınızla tanımlarsınız; her ürün bir ya da birden fazla panel servis kimliğine işaret eder. Bir panel servisi kapandığında ürününüzü başka bir kimliğe yönlendirirsiniz ve müşterileriniz hiçbir şey fark etmez.
Bu katman aynı zamanda yedek tanımlamanıza imkân verir. Bir ürün iki servis kimliğine bağlıysa ve ilki hata döndürürse sisteminiz ikincisini dener. İyi panellerin kendi içinde kurduğu yedeklilik mantığının aynısını kendi katmanınızda da kurmak, hizmetinizi belirgin şekilde güvenilir hale getirir.
Kâr marjı ve fiyat kurgusu
Marj genellikle iki biçimde uygulanır. Yüzdesel marj panel fiyatının üzerine sabit bir oran ekler; basittir ve panel fiyatları değiştiğinde kendiliğinden uyum sağlar. Sabit marj bin adet başına belirli bir tutar ekler; ucuz servislerde marjı korur ama pahalı servislerde sizi rekabet dışı bırakabilir.
Pratikte en iyi sonucu karma model verir: yüzdesel marj artı bir taban tutar, böylece çok ucuz servisler bile işlem maliyetini karşılar. Hangisini seçerseniz seçin asıl önemli olan, panel fiyatı değiştiğinde yeniden hesaplamaktır. Panel fiyatlarını önbelleğe alıp hiç yenilemeyen bir sistem er ya da geç maliyetin altına satmaya başlar.
Kataloğu düzenli aralıklarla yenilemek bunu çözer. Servis listesini günde bir–iki kez çekmek, fiyatları karşılaştırmak ve kendi fiyatlarınızı güncellemek çoğu işletme için yeterlidir. Fiyatı sert biçimde değişen servisleri elle incelemek üzere işaretlemek de faydalı bir güvenlik önlemidir.
Sipariş durumlarını doğru yönetmek
Sipariş, oluşturulduğunda bitmez. Bir durum döngüsünden geçer ve sisteminizin bunu müşteriye dürüstçe yansıtması gerekir. Yaygın durumlar beklemede, işleniyor, tamamlandı, kısmi, iptal edildi ve bazı panellerde ayrıca işleme alındı biçimindedir.
Kısmi en dikkat gerektiren durumdur. Miktarın bir kısmının teslim edildiğini, kalanının edilemediğini anlatır. Panel teslim edilmeyen kısmı bakiyenize iade eder — ve sizin sisteminizin bu iadeyi müşterinize de geçirmesi gerekir. Kısmi durumları doğru işlemeyen bir bayi sistemi ya para kaybeder ya da müşteriyi mağdur eder; ikisi de güveni zedeler.
İptal edildi durumu da benzer şekilde ele alınmalıdır: tutarın tamamı bakiyenize döner ve müşterinize de dönmelidir. Her iki durumu da otomatikleştirmek elle yönetmekten çok daha iyidir, çünkü hacim büyüdüğünde elle mutabakat yapılabilir olmaktan çıkar.
Göndermeden önce doğrulama
En ucuz hata, panele hiç ulaşmayan hatadır. Sipariş oluşturmadan önce kendi tarafınızda doğrulama yapmak hem para hem destek zamanı kazandırır.
Miktarı servisin en az ve en çok değerlerine karşı kontrol edin; bu bilgiler services çağrısında gelir. Bağlantı biçiminin servis türüyle eşleştiğini doğrulayın — gönderi servisi gönderi adresi ister, profil servisi kullanıcı adı. Bakiyenizin siparişi karşıladığını kontrol edin. Ve bağlantıyı normalleştirin: izleme parametrelerini temizleyin, kısaltılmış adresleri açın, panelin çıplak kullanıcı adı beklediği yerde baştaki @ işaretini kaldırın.
Bu kontroller az kod gerektirir ve başarısız siparişlerin büyük bölümünü ortadan kaldırır. Ayrıca müşteriye genel bir API hatası yerine anlaşılır bir mesaj göstermenizi sağlar.
Hız sınırları ve durum sorgulama
Paneller hız sınırı uygular ve bunu göz ardı eden bir bayi sistemi tam da en kötü anda kısıtlanır. İki alışkanlık sizi sınırların içinde tutar.
Birincisi, tamamlanmış siparişleri sorgulamayı bırakmaktır. Bir sipariş tamamlandı, iptal edildi ya da kısmi durumuna ulaştığında durumu kesinleşmiştir; yalnız hâlâ açık olanları kontrol edin. İkincisi, toplu durum çağrısı kullanmak ve açık siparişleri tek tek değil gruplar halinde sorgulamaktır.
Sorgulama sıklığı da gerçekle uyumlu olmalıdır. Çoğu sipariş saatler sürer, dolayısıyla otuz saniyede bir kontrol etmek kotanızı yakmaktan başka bir işe yaramaz. Başlangıçta birkaç dakikada bir kontrol edip sipariş yaşlandıkça aralığı açmak hem daha nazik hem fazlasıyla yeterlidir.
API anahtarını güvende tutmak
API anahtarı bakiyenize tam erişim verir. Anahtarı eline geçiren biri sipariş verip bakiyeyi tüketebilir. Üç önlem gerçekçi riskleri kapsar.
Anahtarı yalnız sunucu tarafında tutun — ön yüz koduna, mobil uygulama paketine asla koymayın. Koda gömmek yerine yapılandırmadan ya da ortam değişkeninden okuyun ki değiştirmek kod değişikliği gerektirmesin. Sızma şüphesi varsa yenileyin; paneller genellikle hesap ayarlarından anahtar üretmenize izin verir.
Bakiyeyi ölçülü tutmak ek bir korumadır. Bir yıllık harcama yerine bir–iki aylık tutmak, bir sorun olduğunda kaybın sınırlı kalmasını sağlar.
Bakiye yönetimi ve nakit akışı
Bayilikte gözden kaçan operasyonel konu nakit akışıdır. Müşteriniz size ödeme yapar, siz panele bakiye yüklersiniz ve sipariş o bakiyeden düşer. Bu üç adım aynı anda gerçekleşmez ve arada kalan boşluk yönetilmezse sistem tıkanır.
En sık yaşanan sorun, bakiyenin gece yarısı bitmesidir. Panel bakiyesi sıfırlandığında gelen siparişler işlenemez ve müşteri hata mesajı alır. Bunun önlemi bir eşik uyarısı kurmaktır: bakiye belirli bir tutarın altına düştüğünde kendinize bildirim gönderin. Çoğu panel bunu kendi arayüzünde de sunar.
İkinci önlem, otomatik siparişlerde bakiye kontrolünü sipariş öncesine almaktır. Bakiye yetmiyorsa siparişi panele hiç göndermeden müşteriye anlaşılır bir mesaj döndürmek, panelden dönen genel hatayı göstermekten çok daha iyidir ve destek yükünü azaltır.
Müşteriye ne göstermeli?
Bayi sisteminin arayüz tarafında bir denge kurmanız gerekir: yeterince bilgi verip müşteriyi rahatlatmak ama teknik ayrıntıya boğmamak.
Gösterilmesi gerekenler: siparişin durumu sade bir dille, başlangıç sayısı, teslim edilen miktar ve kısmi durumda iade edilen tutar. Bu dördü müşterinin aklına gelen soruların neredeyse tamamını yanıtlar ve destek talebi açma ihtiyacını belirgin şekilde azaltır.
Gösterilmemesi gerekenler: panel servis kimlikleri, panel adı, ham API yanıtları ve panelin kendi hata metinleri. Bunlar müşteriye bir şey anlatmaz, aradaki panel ilişkisini gereksizce açık eder ve panel değiştirdiğinizde tutarsızlık yaratır.
Sıkça sorulan sorular
API v2 standardı neleri kapsıyor?
Beş temel eylem neredeyse her şeyi karşılar: servis listesi çekme, sipariş oluşturma, sipariş durumu sorgulama, bakiye okuma ve telafi talebi açma. Paneller çoğunlukla toplu durum sorgusu da sunar.
Panel kataloğunu neden doğrudan göstermemeliyim?
Panel servis kimlikleri değişir ve servisler kapanır. Ara katman sayesinde kendi ürünlerinizi bir ya da birden fazla panel kimliğine bağlar, gerektiğinde müşteriniz fark etmeden yönlendirmeyi değiştirirsiniz.
Kısmi siparişi nasıl ele almalıyım?
Panel teslim edilmeyen kısmı bakiyenize iade eder; sisteminizin bu iadeyi müşterinize de geçirmesi gerekir. Hacim büyüdüğünde elle mutabakat yapılamaz hale geldiği için bunu otomatikleştirmek önemlidir.
Hız sınırına takılmamak için ne yapmalıyım?
Kesinleşmiş durumdaki siparişleri sorgulamayı bırakın, açık siparişleri toplu durum çağrılarında gruplayın ve sipariş yaşlandıkça sorgulama aralığını açın.