Kısa cevap: Perfect Panel, SmartPanel ve çoğu kendi sunucunuzda çalışan panel betiği aynı fiili standardı konuşur; adres genelde /api/v2 ile biter. Sağlayıcı eklemek, bu adresi ve bir API anahtarını girip servis listesini içe aktarmaktan ibarettir. Sağlayıcı sözleşmeyi düzgün uyguluyorsa sipariş yönlendirme, durum sorgulama ve fiyatlandırma kendiliğinden yürür.
İşin mekaniği yeterince basit olduğu için çoğu rehber "anahtarı yapıştır" deyip biter. Atladıkları şey, entegrasyonun bir hafta sonra da çalışıp çalışmayacağını belirleyen kısımdır: sağlayıcının sözleşmenin hangi bölümlerini gerçekten uyguladığı, hangilerini yalnızca iddia ettiği ve sınır durumlarda ne olduğu. Bu yazı ikisini de kapsıyor.
API v2 sözleşmesi ne bekler?
Sözleşme küçüktür ve yıllardır neredeyse hiç değişmemiştir; standart hâline gelmesinin sebebi de budur. Sağlayıcı uç noktası, içinde bir API anahtarı ve bir işlem adı bulunan form kodlamalı bir HTTP POST kabul eder ve JSON döner.
Bir panelin sağlayıcıyı kullanılabilir sayması için beş şey gerekir. Kimlik, ad, tip, kategori, bin adet başına fiyat, minimum ve maksimum adet içeren bir dizi dönen servis listesi. Sipariş numarası dönen sipariş oluşturma. Ücret, başlangıç sayısı, durum ve kalan adet dönen durum sorgulama. Toplu durum sorgulama, çünkü siparişleri teker teker sorgulamak ölçeklenmez. Ve bakiye sorgulama, ki panel siz parasız kalmadan uyarabilsin.
Hatalar HTTP 200 ile ve içinde bir hata alanı olan JSON gövdesiyle döner. Normal REST alışkanlığı olan geliştiricileri şaşırtır ama bütün panellerin beklediği budur. Geçersiz servis numarası için 400 dönen bir sağlayıcı, onu içe aktaran panele bozuk görünür.
Durum değerleri sanılandan daha önemlidir. Paneller sabit bir sözlük tanır: beklemede, işleniyor, devam ediyor, tamamlandı, kısmi, iptal. Bu kümenin dışında bir durum uyduran sağlayıcı, sizin tarafınızda siparişleri belirsiz bir hâlde bırakır; çünkü paneliniz tanımadığı bir kelimeyle ne yapacağını bilmez.
Sağlayıcıyı adım adım eklemek
Perfect Panel'de akış kısadır. Yönetim ayarlarındaki sağlayıcı bölümünü açın ve sağlayıcı ekle deyin. Sağlayıcının API adresini ve panelinden ürettiğiniz anahtarı girin. Kaydedin, ardından servis içe aktarımını çalıştırın.
Bir ayrıntı çoğu kişiyi şaşırtır: Perfect Panel entegre sağlayıcıların kendi kaydını tutar. Eklediğiniz sağlayıcı bu kayıttaysa anahtarı girersiniz ve iş biter. Kayıtta değilse panelin destek ekibi talep üzerine ücretsiz olarak entegre eder; ancak bu anlık bir işlem değil, süresi olan bir taleptir. Lansman planı yapmadan önce sağlayıcı listesini kontrol edin ki hangi yolda olduğunuzu bilesiniz.
SmartPanel ve kendi sunucunuzda çalışan betiklerin çoğunda böyle bir kayıt adımı yoktur. Sağlayıcıyı aynı iki alanla yönetim panelinden eklersiniz ve içe aktarım hemen çalışır. Sözleşme aynı olduğu için birinde çalışan sağlayıcı genelde diğerinde de çalışır.
İçe aktarımdan sonra her şeyi açmayın. İçe aktarım sağlayıcının bütün kataloğunu getirir ve bu genelde satmayı düşündüğünüzden çok daha fazla servistir. Gerçekten istediğiniz kategorileri açın, kâr oranınızı belirleyin, gerisini kapalı bırakın; kısa liste hem daha iyi dönüşür hem de desteklemesi çok daha kolaydır.
Perdenin arkasındaki dört çağrı
Sağlayıcı bağlandıktan sonra paneliniz sonsuza kadar aynı küçük çağrı kümesini yapar.
Servis listesi. Kataloğu güncel tutmak için düzenli aralıklarla çekilir. Fiyat değişiklikleri size buradan ulaşır, dolayısıyla aralık önemlidir: seyrek çekerseniz sağlayıcının artık vermediği bir fiyattan satarsınız.
Sipariş oluşturma. Müşteri siparişinin karşılanması gerektiği anda gönderilir ve sağlayıcının sipariş numarasını döner. Paneliniz bu numarayı saklar ve sonrasındaki her şey için onu kullanır.
Durum sorgulama. Tekrar tekrar, genelde en fazla yüz numaralık gruplar hâlinde sorgulanır. Müşterinizin gördüğü her durum bunun çıktısıdır.
Bakiye. Düzenli okunur ki panel, siparişler bakiye yetersizliğinden düşmeye başlamadan sizi uyarabilsin.
Telafi ve iptal sözleşmede var ama zorunlu değil; bozuk görünen entegrasyonların en yaygın kaynağı da budur. Bir sağlayıcı servisleri telafi edilebilir olarak işaretliyor ama telafi işlemini uygulamıyorsa, paneliniz her seferinde hata dönen bir telafi butonu çizer. Telafiyi destek üzerinden elle yürüten sağlayıcıların bu bayrakları kapalı bildirmesi gerekir. Sağlayıcı değerlendiriyorsanız, bayraklarla uygulanan işlemlerin örtüşüp örtüşmediğine bakmak, API'yi ne kadar özenle kurduklarını anlamanın hızlı bir yoludur.
Servis listesini içe aktarmak ve fiyatlamak
Sağlayıcının döndüğü fiyat, kendi para biriminde bin adet başına fiyattır. Paneliniz bunu kâr oranınızla çarparak müşteri fiyatını üretir; yani bütün marjınız o oranın içinde yaşar.
Oranı genel yerine kategori bazında belirleyin. Bin servislik bir katalogda tek bir yüzde, müşterinin saniyeler içinde karşılaştırabildiği sıradan servislerde fazla yüksek, hareket alanınız olan zor servislerde ise fazla düşük kalır. Çoğu panel kategori bazlı istisnayı destekler; bunu kullanmak, rekabetçi bir listeyle kimsenin sipariş vermediği liste arasındaki farktır.
Para birimine dikkat edin. Sağlayıcı USD üzerinden faturalıyor ve paneliniz başka bir birimde satıyorsa, her kur hareketi gerçek marjınızı sessizce değiştirir. Ya aynı para biriminde satın ya da kâr oranına bilinçli bir tampon koyun; sonradan fark etmeyin.
İçe aktarımı düzenli tekrarlayın ve neyin değiştiğine bakın. Sağlayıcılar sürekli ekler, kaldırır ve fiyat değiştirir. Siz hâlâ satarken katalogdan kaybolan bir servis, müşteriye sizin hatanız gibi görünen başarısız siparişler üretir.
Ne bozulur, nasıl fark edilir?
Entegrasyon sorunlarının çoğu üç başarısızlık biçiminden gelir.
Birincisi servis tipi uyuşmazlığı. Sözleşmede varsayılan tipin dışında tipler de var: özel yorum, paket, etiketleme gibi. Bunlar panelinizin göndermeyebileceği ek parametreler ister. Sağlayıcı bu tipleri listeliyor ama sipariş çağrısı yalnızca link ve adet kabul ediyorsa, ek alanlar sessizce yutulur ve sipariş yanlış açılır. Özenli bir sağlayıcı ya parametreleri uygular ya da bu servisleri API kataloğunun tamamen dışında tutar.
İkincisi zaman aşımı belirsizliği. Sipariş isteği zaman aşımına uğrarsa sipariş sağlayıcı tarafında açılmış da olabilir, açılmamış da. Körlemesine tekrar denemek çift sipariş yaratır ve iki kez ücret ödersiniz; başarısız varsayıp iade etmek ise ödenmemiş gerçek bir siparişin çalışmasına yol açar. Doğru davranış, herhangi bir şey yapmadan önce durumu sorgulamaktır; bunu temiz biçimde yapmanızı sağlayan bir sağlayıcı, biraz daha ucuz olandan daha değerlidir.
Üçüncüsü sağlayıcının kendi üst kaynağında parasının bitmesi. Bazıları siparişi iptal edip iade eder; müşteriniz elinde hiçbir şey olmadan kalır, açıklama size düşer. Bazıları siparişi kuyruğa alır ve bakiye yüklenince tamamlar; sipariş hiç olmamak yerine geç biter. İkisi de yanlış değil ama sizin tarafınızda farklı bir iletişim gerektirir, o yüzden hangisiyle çalıştığınızı sorun.
TelegramBoost'u sağlayıcı olarak bağlamak
Biz ana sağlayıcı olduğumuz için bizi bağlamak paneliniz ile teslim arasına ara katman koymaz: içe aktardığınız katalog bize aittir ve ödediğiniz fiyat, başkasının listesine kâr eklenmiş hâli değil kaynak fiyatıdır.
Bayi uç noktamız yukarıdaki sözleşmeyi izler: HTTP POST, form kodlamalı veya JSON gövde, anahtar gövdede ya da X-Api-Key başlığında, yanıtlar JSON ve hatalar hata alanıyla. Servis listesi, sipariş oluşturma, tekli ve toplu durum sorgulama ile bakiye sorgulama uygulanmış durumda; fiyatlar USD ve bin adet üzerinden.
Telafi ve iptal API yerine destek talebiyle yürüyor; servis listemiz de bu bayrakları çalışmayan buton üretecek şekilde açık göstermek yerine kapalı bildiriyor. API anahtarlarını panelden kendiniz üretiyorsunuz, anahtar yalnızca oluşturulurken bir kez gösteriliyor ve aynı anda en fazla beş aktif anahtar tutulabiliyor. Üst kaynakta bakiye biterse sipariş iptal olmuyor, kuyrukta bekliyor. Parametre listesinin tamamı API dokümantasyon sayfamızda; işin ticari tarafı için bayilik rehberine bakabilirsiniz.
Sıkça sorulan sorular
Sağlayıcımın Perfect Panel tarafından önceden onaylanması gerekir mi?
Yalnızca Perfect Panel'in entegre sağlayıcı kaydı anlamında. Sağlayıcı listede ise bir API anahtarı girip işi bitirirsiniz. Değilse destek ekipleri talep üzerine ücretsiz entegre eder, ama bu anlık değil süresi olan bir adımdır; planınızı buna göre yapın.
İçe aktarılan serviste telafi butonu neden hata veriyor?
Neredeyse her zaman, sağlayıcı servisleri telafi edilebilir işaretlediği hâlde API'de telafi işlemini uygulamadığı için. Paneliniz bayrağa güvenip butonu çizer, çağrı ise hata döner. Telafiyi elle yürüten sağlayıcıların bu bayrağı kapalı bildirmesi gerekir.
Servis listesini ne sıklıkla yeniden çekmeliyim?
Çoğu katalog için günde bir veya iki kez yeterlidir. Yeniden çekmenin amacı, fiyat değişikliklerini ve kaldırılan servisleri müşteri siparişi onlara çarpmadan yakalamaktır; doğru aralık, bayat fiyattan hiç satmayacağınız kadar kısa olandır.
Sipariş isteği zaman aşımına uğrarsa ne yapmalıyım?
Başka bir şey yapmadan önce sipariş durumunu sorgulayın. Zaman aşımı, isteğin gittiği ama yanıtın kaybolduğu anlamına gelir; sipariş üst tarafta zaten var olabilir. Yeniden göndermek çift sipariş yaratıp iki kez ücret keser, başarısız varsaymak ise iade ettiğiniz gerçek bir siparişin çalışmasına yol açar.