Turkpin API entegrasyonunu çoğu işletme sahibi şöyle hayal eder: bayi panelinden bir anahtar alırsın, iki satır kod yazarsın, ürünler akmaya başlar. Gerçek hikâye ise ilk isteğin başarılı döndüğü yerde değil, ilk isteğin sessizce başarısız döndüğü yerde başlar. Çünkü bu tür servislerde en pahalı hata, ekrana kırmızı yazı basan hata değildir; müşteriye "işleminiz alındı" diyen ama arkada kod üretmeyen hatadır.
Sahadaki bayilerin çoğu bunu acı yoldan öğreniyor. Gece 02.00'de gelen bir sipariş, tedarikçi tarafında zaman aşımına düşüyor, sistem "hata" diyor, müşteri parayı ödemiş oluyor ve sabah masaya oturduğunda elinde hem eksik bir kasa hem de kızgın bir müşteri oluyor. İşin sırrı hata kodlarını ezberlemek değil; her hata kodunun para tarafında ne anlama geldiğini bilmek ve bunu kullandığın e-pin scripti içine kural olarak gömmektir. Aşağıda tam olarak bunu açıyoruz.
Hata kodu gerçekten "hata" mı, yoksa "bilmiyorum" mu?
Entegrasyon dünyasında üç farklı sonuç vardır ama çoğu kurulum bunu ikiye indirir: başarılı ve başarısız. Oysa aradaki üçüncü durum, yani belirsiz sonuç, kasadaki açığın neredeyse tamamının kaynağıdır. Bağlantı koptuğunda, soket zaman aşımına düştüğünde ya da yanıt yarı yolda kesildiğinde sipariş tedarikçi tarafında pekâlâ işlenmiş olabilir. Sen "hata" diye işaretlersin, müşteriye iade yaparsın, kod ise karşı tarafta düşmüş olur. İki kere kaybedersin.
Doğru kurulmuş bir dijital ürün satış scripti bu üç durumu ayrı ayrı tutar. Belirsiz sonuçları "kontrol edilecek" kuyruğuna alır, birkaç dakika sonra sipariş sorgulama ucuna giderek gerçek durumu öğrenir ve kararı ancak o zaman verir. Bu tek davranış, aylık kayıp kalemini genellikle tek başına sıfıra yaklaştırır.
Neden aynı isteği iki kez göndermek en tehlikeli alışkanlık?
Zaman aşımı aldığında ilk refleks isteği tekrar göndermektir. Ama aynı sipariş için ikinci kez talep atıyorsan ve gönderdiğin veride tekilliği garanti eden bir referans yoksa, tedarikçi bunu yeni bir sipariş sayar. Sonuç: bir müşteri, iki kod, yarı yarıya erimiş kâr. Çözüm, her siparişe kendi tarafında ürettiğin kalıcı ve benzersiz bir referans numarası vermek ve tekrar denemelerde aynı referansı kullanmaktır.
Bu, yazılım tarafında "idempotent istek" diye geçer ve ciddi bir e-pin satış yazılımı bunu varsayılan olarak yapar. Referans, sipariş oluşturulduğu anda veritabanına yazılır; tekrar denemeler bu satırı günceller, yenisini yaratmaz. Böylece kaç kez denediğin değil, kaçıncı denemede net cevap aldığın önemli hale gelir.
| Karşılaştığın durum | Gerçek anlamı | Yapılması gereken | Tekrar denenir mi? |
|---|---|---|---|
| Yetkisiz erişim / anahtar reddi | Anahtar, IP izni veya imza yanlış | Anahtarı ve sunucu IP kaydını doğrula | Hayır |
| Bakiye yetersiz | Bayi cüzdanı siparişi kaldıramıyor | Satışı durdur, yöneticiye uyarı gönder | Hayır |
| Ürün bulunamadı / pasif | Tedarikçi kodu değişmiş veya kapanmış | Eşleştirmeyi güncelle, ürünü gizle | Hayır |
| Stok yok | Anlık tükeniş | Ürünü otomatik pasife al, müşteriye seçenek sun | Sınırlı |
| Zaman aşımı / bağlantı koptu | Sonuç belirsiz | Sipariş durumunu sorgula, sonra karar ver | Evet, aynı referansla |
| İstek limiti aşıldı | Çok sık çağrı yapıyorsun | Artan bekleme süresiyle kuyruğa al | Evet, gecikmeli |
| Sunucu tarafı arıza | Tedarikçide geçici sorun | Kuyruğu beklet, otomatik yeniden dene | Evet |
| Geçersiz parametre | Gönderilen alan formatı bozuk | İsteği logdan incele, alanı düzelt | Hayır |
Anahtar doğru görünüyor ama yine reddediliyorsa ne oluyor?
Yetkilendirme hatalarının büyük kısmı aslında anahtarla ilgili değildir. En sık üç sebep şunlar: sunucunun çıkış IP adresi bayi panelinde tanımlı listede yok, paylaşımlı hostingde IP değişmiş ya da istek imzası oluşturulurken parametre sırası bozulmuş. Özellikle bulut arkasında çalışıyorsan, sitenin göründüğü IP ile sunucunun dışa çıktığı IP aynı olmak zorunda değil — ve API tarafı seni ikinciye göre tanır.
Pratik kontrol şu: sunucudan basit bir sorgu ile kendi dış IP'ni öğren, panele tanımlı değeri karşılaştır. Ardından test ortamı ile canlı ortam anahtarlarını karıştırıp karıştırmadığını doğrula. Bu iki adım, "saatlerce kod kurcaladım" hikâyelerinin çoğunu beş dakikaya indirir.
Entegrasyon arızalarının kaynak dağılımı
- Zaman aşımı ve belirsiz sonuç 40%
- Yetki, IP ve imza sorunları 30%
- Ürün eşleştirme ve stok 20%
- Limit aşımı ve diğer 10%
Log tutmuyorsan aslında entegrasyon yapmamışsın
Bir sipariş tartışmasında elinde ne olduğu her şeyi belirler. "Kod gelmedi" diyen müşteriye karşı tek savunman, o siparişe ait isteğin ve yanıtın tam kaydıdır: zaman damgası, referans numarası, gönderilen alanlar, dönen gövde ve karar. Bu kayıt olmadığında her tartışmayı kaybeder, her şüpheli işleme iade yaparsın.
Buradaki hassas nokta gizlilik: log içine anahtarını, imza gizini ve teslim edilen kodun tamamını düz metin yazmamalısın. Ciddi bir epin yazılım altyapısı hassas alanları maskeler, kodları şifreli saklar ve logu yalnızca yönetici rolüne açar. Böylece hem kanıt elinde kalır hem de bir gün panele izinsiz bir erişim olsa bile envanterin çıplak kalmaz.
Kuyruk mantığı olmayan sistem, yoğun saatte neden çöker?
Kampanya saatinde siparişler tek tek değil, dalga hâlinde gelir. Her siparişi müşteri beklerken senkron biçimde tedarikçiye yolluyorsan, ilk yavaşlamada web sunucun dolar, sayfalar açılmaz ve arıza satış sayfasına kadar yayılır. Doğru yaklaşım şu: ödeme onaylandığı anda siparişi kuyruğa yaz, kullanıcıya "hazırlanıyor" ekranı göster, arka plandaki işleyici teslimatı üstlensin.
Bu yapının ikinci faydası şudur: tedarikçi tarafında bir arıza başladığında satış durmaz, sadece teslimat gecikir. Arıza geçtiğinde kuyruk kendi kendini boşaltır, kimse tek bir siparişi bile kaybetmez. Modern bir e-pin satış scripti için kuyruk artık lüks değil, asgari şart.
Belirsiz sonuçta isteği körlemesine tekrarlama. Aynı referansla en fazla üç kez dene, aralarda bekleme süresini ikiye katla ve üçüncüden sonra siparişi manuel inceleme kuyruğuna al. Bu kural tek başına çift teslimatı da, kayıp kodu da bitirir.
Kurulum öncesi kendi kendine soracağın kontrol listesi
Entegrasyonu canlıya almadan önce aşağıdaki maddeleri tek tek işaretlemeni öneririz. Her satır, sahada en az bir bayinin para kaybettiği gerçek bir olaydan çıkmıştır. Listeyi özellikler sayfasındaki teslimat akışıyla yan yana okursan, hangi maddeyi yazılımın hâlihazırda çözdüğünü de görürsün.
| Kontrol maddesi | Neden kritik | Durum |
|---|---|---|
| Sunucunun dış IP'si panele tanımlı mı? | Yetki reddinin bir numaralı sebebi | Zorunlu |
| Her siparişe benzersiz referans üretiliyor mu? | Çift teslimatı engeller | Zorunlu |
| Zaman aşımı süresi sabitlenmiş mi? | Sunucunun kilitlenmesini önler | Zorunlu |
| Sipariş durum sorgulama ucu bağlı mı? | Belirsiz sonucu netleştirir | Zorunlu |
| Kuyruk ve arka plan işleyici çalışıyor mu? | Yoğun saatte satışı ayakta tutar | Önerilir |
| Hassas alanlar logda maskeli mi? | Anahtar ve kod sızmasını engeller | Zorunlu |
| Bakiye eşiği uyarısı kurulu mu? | Sessiz satış durmasını önler | Önerilir |
| Ürün eşleştirmesi otomatik doğrulanıyor mu? | Kapanan ürünü satmanı engeller | Önerilir |
Hangi hatayı müşteriye göstermeli, hangisini asla?
Teknik mesajları müşteriye olduğu gibi yansıtmak güven kaybettirir. Müşterinin görmesi gereken tek şey, kendi yapabileceği bir eylem varsa o eylemdir: "ürün geçici olarak tükendi, alternatif paketleri görebilirsin" ya da "teslimatın hazırlanıyor, ortalama süre bir dakika". Bakiye yetersizliği, anahtar reddi, sunucu arızası gibi kalemler tamamen senin tarafında kalmalı ve yöneticiye anlık bildirim olarak düşmelidir.
Bu ayrımı kurduğun anda destek yükü de düşer. Çünkü müşteri artık ne olduğunu anlamadığı bir kod görmez; ne olacağını söyleyen bir cümle görür. Fiyatlandırma ve paket farklarını merak ediyorsan fiyat bölümünde teslimat otomasyonunun hangi seviyede geldiğini karşılaştırabilirsin.
Entegrasyonu tek tek elle kurmak zorunda değilsin
Pinova, tedarikçi bağlantısı, kuyruk, tekrar deneme ve maskeli log katmanını kurulumdan çıkar çıkmaz hazır verir. Sen ürünleri ve fiyatını yönetirsin, hata yönetimini yazılım üstlenir.
Zaman aşımı alan siparişi hemen iade etmeli miyim?
Hayır. Önce sipariş durum sorgulamasıyla tedarikçi tarafındaki gerçek sonucu öğren. İade kararını ancak "işlem yok" cevabı aldıktan sonra ver; aksi hâlde hem kodu hem parayı kaybedersin.
Anahtarım doğru olduğu hâlde niye yetki hatası alıyorum?
En yaygın sebep sunucunun dışa çıkan IP adresinin bayi panelindeki izin listesinde olmaması. Bulut veya proxy arkasındaysan görünen IP ile çıkış IP'si farklı olabilir; çıkış IP'sini doğrulayıp panele ekle.
Stok yok hatası gelen ürünü otomatik kapatmak mantıklı mı?
Evet, ama süreli olarak. Ürünü belirli bir süre pasife almak hem boşa sipariş almanı önler hem de tedarikçi stok tazelediğinde ürünün kendiliğinden geri açılmasına imkân verir.
Tüm istek ve yanıtları loglamak güvenlik riski yaratır mı?
Maskeleme yapmazsan evet. Anahtar, imza gizi ve teslim edilen kodun tamamı logda düz metin görünmemeli. Doğru kurulumda bu alanlar maskelenir, kodlar şifreli saklanır ve log erişimi yalnızca yönetici rolündedir.
Hata kodları düşmanın değil; sistemin sana tuttuğu ayna. Her kodu bir karara, her kararı bir otomasyona bağladığında entegrasyon artık sürekli uğraştığın bir yer değil, arka planda sessizce çalışan bir motor olur. Bu motorun nasıl göründüğünü kendi gözünle test etmek istersen canlı demo üzerinden sipariş oluşturup teslimat akışını, kuyruğu ve log ekranını birebir inceleyebilir, ardından kurulum adımına geçebilirsin.