E-Pin Scriptine Toptan Tedarikçi Entegrasyonu Nasıl Yapılır?

Elle stok girmek, tedarikçi panelinden tek tek kod kopyalamak, fiyat değişince tüm ürünleri gezip güncellemek... E-pin ve dijital ürün satan hemen her girişimci bu döngüden bir yerde bunalıyor. Oysa Turkpin veya Pinabi gibi toptan tedarikçilerin API'lerini scriptinize doğru şekilde bağladığınızda aynı işi saniyeler içinde otomatik yaptırmak mümkün. Peki bu entegrasyon gerçekte nasıl işliyor, nereden başlanır ve hangi noktalarda tökezlenir?

Bu yazıda entegrasyonun kavramsal çerçevesinden teknik akışına, sık yapılan hatalardan fiyatlandırma otomasyonuna kadar tüm süreci adım adım ele alıyoruz.

Toptan Tedarikçi Entegrasyonu Aslında Ne İşe Yarar?

Toptan tedarikçi entegrasyonu, e-pin scriptinizin arka planda tedarikçinin sunucusuyla doğrudan konuşmasını sağlayan bir köprü kurmak demektir. Bu köprü kurulduğunda scriptiniz üç şeyi otomatik yapar: tedarikçideki güncel stok bilgisini çeker, fiyat listesini senkronize eder ve müşteri sipariş verdiği anda kodu tedarikçiden talep edip teslim eder.

Bunu bir örnekle somutlaştıralım: sitenizde 50 farklı oyun kartı ve dijital kod kategorisi var. Her birinin onlarca varyasyonu (100 TL, 250 TL, 500 TL gibi) olduğunu düşünürsek toplam ürün sayısı kolayca 300-400'ü buluyor. Bu kadar ürünü elle takip etmek, fiyat güncellemesi olduğunda hepsini tek tek değiştirmek pratikte imkansıza yakın. API entegrasyonu bu yükü tamamen ortadan kaldırır.

• Stok bilgisi tedarikçide değiştiği anda sitenizde de değişir, "tükendi" yazan ürün satılmaz
• Fiyat güncellemesi tek bir cron görevi ile tüm kataloğa yansır
• Sipariş anında kod otomatik çekilir, müşteri bekletilmez
• Personel ihtiyacı azalır, insan hatası riski düşer

Burada altını çizmek gereken bir nokta var: entegrasyon sadece "kod çekme" işi değil, aynı zamanda bir muhasebe ve raporlama katmanı da kurar. Her sipariş anında tedarikçiden çekilen kodun maliyeti, satış fiyatı ve elde edilen kâr otomatik olarak kayıt altına alınır. Yıl sonunda "hangi kategori ne kadar kâr getirdi" sorusuna dakikalar içinde cevap verebilmek, elle tutulan Excel tablolarıyla neredeyse imkansızdır.

Turkpin ve Pinabi API'leri Birbirinden Ne Kadar Farklı?

Türkiye pazarında e-pin toptan satışında en çok tercih edilen iki tedarikçi Turkpin ve Pinabi. İkisi de REST tabanlı API sunuyor ama detaylarda ayrışıyorlar. Turkpin genellikle API anahtarı + gizli anahtar (secret key) ikilisiyle kimlik doğrulama isterken, Pinabi bazı entegrasyonlarda kullanıcı adı/şifre + token yenileme mantığını kullanıyor. Bu fark, entegrasyon kodunun tedarikçiye özel yazılması gerektiği anlamına gelir; tek bir "evrensel" bağlayıcı yazmak genelde yetersiz kalır.

Her iki tedarikçi de şu uç noktaları (endpoint) sunar:

• Ürün/kategori listesi: hangi ürünlerin satışa açık olduğu
• Stok sorgulama: anlık kalan adet bilgisi
• Fiyat listesi: bayi/alım fiyatları, genelde TL veya USD üzerinden
• Sipariş oluşturma: kod talep etme, ödeme çekme
• Sipariş sorgulama: daha önce alınan kodun tekrar görüntülenmesi

Pinova bu iki tedarikçiye özel hazır bağlayıcılarla gelir; yani API anahtarınızı panelden girip kategori eşlemesini yaptığınızda geri kalan teknik kısımla uğraşmanız gerekmez. Ama sıfırdan bir script yazıyorsanız, her tedarikçinin dokümantasyonundaki istek/yanıt formatını (genelde JSON, bazı eski uçlarda XML) birebir takip etmeniz gerekir.

İki tedarikçi arasında seçim yaparken sadece API kalitesine değil, ürün çeşitliliğine ve alım fiyatlarına da bakmak gerekir. Bazı kategorilerde Turkpin daha rekabetçi fiyat sunarken, başka bir kategoride Pinabi'nin stoku daha derin olabilir. Bu yüzden çoğu orta-büyük ölçekli e-pin sitesi tek bir tedarikçiye bağlı kalmak yerine iki tedarikçiyi de entegre edip, ürün bazında hangi kaynaktan besleneceğini kendisi belirler. Böylece bir tedarikçide stok tükendiğinde otomatik olarak diğerine geçiş yapılabilir; bu da satış kaybını önemli ölçüde azaltır.

Entegrasyon Adım Adım Teknik Olarak Nasıl Kurulur?

Sıfırdan bir entegrasyon kurarken izlenen yol genelde şu sırayı takip eder. İlk adım tedarikçi panelinden API erişimi talep etmektir; bu genelde bir bayilik başvurusu ve onay süreci gerektirir. Onay geldikten sonra size özel API anahtarı ve genelde bir IP kısıtlaması (sunucunuzun sabit IP'sinin tedarikçi panelinde tanımlanması) verilir.

İkinci adım kategori ve ürün eşlemesidir. Tedarikçideki "PUBG Mobile UC 60" ürününü kendi sitenizdeki hangi ürün kaydına bağlayacağınızı belirlersiniz. Bu eşleme genelde bir eşleme tablosu (mapping table) üzerinden yapılır; tedarikçi ürün ID'si ile kendi ürün ID'niz eşleştirilir.

Üçüncü adım stok ve fiyat senkronizasyonudur. Burada iki yöntem var: belirli aralıklarla (örneğin 15 dakikada bir) çalışan bir cron görevi ile tedarikçiden veri çekmek, ya da tedarikçi destekliyorsa webhook ile anlık bildirim almak. Türkiye'deki toptan tedarikçilerin büyük kısmı henüz webhook sunmuyor, bu yüzden cron tabanlı senkronizasyon şu an için standart yöntem.

Son adım ise sipariş anındaki gerçek zamanlı akıştır: müşteri ödemeyi tamamladığı anda scriptiniz tedarikçiye "bu ürünü bana ver" isteği atar, tedarikçi kodu üretir veya stoktan çeker, script bu kodu alıp müşteriye e-posta/panel üzerinden iletir. Bu akışın tamamı normal şartlarda birkaç saniye sürer.

Bu dört adımın her biri kendi içinde ayrı bir test aşaması gerektirir. Örneğin stok senkronizasyonunu canlıya almadan önce, tedarikçi tarafında bilerek stoğu sıfırlanmış bir test ürünüyle deneme yapıp scriptinizin bu durumu doğru yansıtıp yansıtmadığı kontrol edilmeli. Aynı şekilde sipariş akışı için gerçek parayla değil, tedarikçinin sunduğu varsa test/bayilik ortamıyla ya da düşük tutarlı gerçek bir siparişle deneme yapmak, canlıya geçtikten sonra yaşanacak sürprizleri en aza indirir.

Manuel Sistemden Otomatiğe Geçince Neler Gerçekten Değişiyor?

Rakamlarla bakıldığında entegrasyonun getirdiği fark daha net görülüyor. Aşağıdaki tablo, günde ortalama 40-50 sipariş alan orta ölçekli bir e-pin sitesinde manuel süreç ile Pinova üzerinden kurulan otomatik entegrasyonu karşılaştırıyor.

Buradaki en kritik satır aslında stok tutarsızlığı. Manuel sistemde bir müşteri tükenmiş bir ürünü satın alabilir, ödemesi geçer ama kod verilemez; bu da iade süreci ve itibar kaybı demektir. Otomatik entegrasyon bu riski neredeyse sıfıra indirir çünkü stok kontrolü sipariş onaylanmadan hemen önce tekrar yapılır.

Entegrasyonda En Sık Hangi Hatalarla Karşılaşılır?

Toptan tedarikçi entegrasyonu kurarken tekrar eden birkaç sorun var. Bunları önceden bilmek, canlıya geçtikten sonra yaşanacak sürprizleri büyük ölçüde azaltır.

• Kur farkı senkronizasyonu: Tedarikçi fiyatı USD üzerinden veriyorsa ve siz TL satıyorsanız, kur güncellemesi gecikirse zararına satış riski doğar. Kur çekme sıklığının stok/fiyat senkron sıklığıyla uyumlu olması gerekir.
• Rate limit (istek sınırı): Tedarikçiler dakikada belirli sayıda isteğe izin verir. Çok sık sorgulama yapan bir script IP bazlı geçici olarak engellenebilir; bu yüzden senkron aralığı gereksiz sıklaştırılmamalı.
• Zaman aşımı (timeout) yönetimi: Tedarikçi sunucusu yavaş yanıt verdiğinde script'in sonsuza kadar beklememesi, belirli bir sürede hata dönüp tekrar denemesi gerekir.
• Bakım kesintileri: Tedarikçi sunucusu planlı ya da plansız bakıma girdiğinde sipariş isteği başarısız olur; bu durumda scriptin siparişi otomatik iptal etmek yerine bekletme kuyruğuna alıp birkaç dakika sonra tekrar denemesi, müşteri kaybını önler.
• Çift sipariş (duplicate order) riski: Ağ hatası nedeniyle aynı sipariş isteği iki kez tedarikçiye gidebilir. Her siparişe benzersiz bir referans numarası (idempotency key) atanmalı.
• Kategori eşleme hataları: Yanlış eşlenen bir ürün, müşteriye tamamen farklı bir kod gitmesine neden olabilir; canlıya almadan önce test siparişleri şart.

Bu hataların büyük kısmı, entegrasyonu sıfırdan yazmak yerine test edilmiş bir altyapı kullanıldığında zaten çözülmüş oluyor. Pinova'daki Turkpin ve Pinabi bağlayıcıları bu senaryoların çoğu için hata yönetimi ve tekrar deneme (retry) mantığını hazır barındırır.

Bir diğer gözden kaçan konu ise loglama. Entegrasyon sorunsuz çalıştığı sürece kimse loglara bakmaz, ama bir müşteri "param gitti kod gelmedi" dediğinde elinizde o siparişin tedarikçiye hangi istekle gittiği, ne yanıt döndüğü ve kaçıncı denemede başarılı/başarısız olduğu kaydı yoksa sorunu çözmek saatler alabilir. Her tedarikçi isteğinin zaman damgası, gönderilen parametreler ve dönen yanıtla birlikte ayrı bir log tablosunda tutulması, destek süreçlerini ciddi şekilde hızlandırır.

Fiyatlandırma ve Kâr Marjı Otomasyonu Nasıl Kurulur?

Entegrasyonun bir diğer önemli parçası, tedarikçiden gelen alım fiyatı üzerine otomatik kâr marjı eklemektir. Elle fiyatlandırmada her ürüne tek tek yüzde veya sabit tutar eklemek gerekirken, otomatik sistemde kategori bazlı kural tanımlanır: örneğin "oyun kartları kategorisinde alım fiyatının üzerine %8 ekle" gibi bir kural tüm o kategorideki ürünlere otomatik uygulanır.

Bu yaklaşımın avantajı sadece zaman kazancı değil; rekabetçi kalabilmektir. Tedarikçi fiyatı düştüğünde sizin satış fiyatınız da otomatik düşer ve piyasadaki en güncel fiyatı yakalarsınız. Fiyat yükseldiğinde ise zararına satış yapmadan önce sistem sizi korur.

• Kategori bazlı sabit yüzde marj (örn. %5-15 arası, ürün tipine göre değişir)
• Ürün bazlı özel marj (kampanyalı/öne çıkan ürünler için)
• Alt/üst fiyat sınırı (belirli bir bandın dışına çıkmayı engelleme)
• Rakip fiyat takibiyle dinamik marj (ileri seviye kurulum)

Pinova panelinde bu kurallar kategori bazında tanımlanır ve her senkron döngüsünde otomatik uygulanır; yani tedarikçi tarafında bir fiyat değişikliği olduğunda sizin elle müdahale etmenize gerek kalmadan doğru kâr marjıyla güncel fiyat sitenizde görünür.

Küçük bir uyarı: marj kuralını çok agresif ayarlamak kısa vadede kârı artırıyor gibi görünse de, sürekli fiyat karşılaştırması yapan e-pin alıcıları için caydırıcı olabilir. Kategori bazlı marjı belirlerken rakip fiyatlarını referans alıp makul bir bant içinde kalmak, hem satış hacmini korur hem de sürdürülebilir bir kâr yapısı sağlar.