SMM panel API metotları: add, status, refill ve cancel

Bir paneli bota, kendi sitenize ya da başka bir panele bağlarken API\'nin ne olduğuna dair genel anlatım işe yaramaz olur - size çağrıların tam listesi, parametreleri ve yanıt biçimleri gerekir. Bu başvuru alışılmış dokümanlardan farklı kuruldu: gerçek sözleşmeyi on bir canlı panelde ölçtük ve kendi çekirdeğimizle karşılaştırdık. Aşağıda on çağrının tamamı, hizmet türüne göre sipariş alanları ve entegrasyonların en sık kırıldığı üç yer var.

Aşağıdaki başvuru neyin çağrılacağını anlatır. Bu sırada panelin kendisinin neyi denetlemesi gerektiği - miktar sınırları, aynı bağlantıya çift sipariş, müşteri yetkileri, istek bütçesi - için API kötüye kullanımı üzerine ayrı bir yazı var: bu kurallar gözetilmeden yazılan entegrasyon onlara canlı ortamda toslar.

Neredeyse her panel neden aynı API\'yi konuşuyor

Pratikte bütün sektör tek bir protokol konuşur, yaygın adıyla API v2. Bu tarihsel olarak oluştu: bir motor biçimi belirledi, geri kalanlar da başka yerde yazılmış bayi istemcileri kendilerine karşı da çalışsın diye onu kopyaladı. Bir entegratör için bu ender bir şans - bir panel için yazılmış istemci, neredeyse hiç değişiklik olmadan bir başkasında çalışır.

Hepsinde ortak olan tam olarak dört kural var:

• Tek uç nokta. Genelde /api/v2, metot her zaman POST, yanıt her zaman JSON.
• Anahtar bir alandır, başlık değil. Sıradan bir key parametresi olarak gider - ne Authorization, ne Bearer.
• İşlem action içinde yaşar. Ne yol, ne HTTP metodu - ne olacağına o alanın değeri karar verir.
• Yol dışında sürümleme yok. «v2», uç noktanın parçasıdır; başlık ya da parametre değil.

Panel sahibi için pratik sonuç: kendi biçiminizi uydurmayın. Özel bir protokol, entegrasyonu hâlihazırda yazılmış bayilerden sizi koparır - ve hacmi getirenler onlardır. Anahtarları neden ve kime dağıtacağınız panel API\'si ve bayilerle çalışmak yazısında.

Yedi action, on çağrı

Standartta yedi action var, ama dördü toplu biçimde de gelir - bu da desteklenecek on ayrı çağrı demektir:

• action=services - hizmet listesi. service (herkese açık numara), name, type, category, rate, min, max, refill, cancel alanlarından oluşan bir dizi döndürür.
• action=add - sipariş oluşturma. service her zaman zorunludur; geri kalan alanlar hizmet türüne bağlıdır. Yanıt {"order": 23501}.
• action=status ile order - tek sipariş: charge, start_count, status, remains, currency.
• action=status ile orders - tek istekte virgülle ayrılmış yüze kadar numara.
• action=refill ile order - refill oluşturma. Yanıt refill numarasıdır, çoğu zaman metin olarak: {"refill": "1"}.
• action=refill ile orders - toplu refill, yüze kadar sipariş.
• action=refill_status ile refill - refill\'in kendi numarasıyla durumu.
• action=refill_status ile refills - aynısı toplu hâlde.
• action=cancel ile orders - iptal, yalnızca toplu biçimde belgelenmiş.
• action=balance - {"balance": "100.84292", "currency": "USD"}.

Bu listenin dışındaki her şey tek bir panelin uzantısıdır. Bizimki örneğin order ile tek bir cancel kabul eder ve action=create\'i add ile eşanlamlı sayar - ama bir istemci asla böyle kolaylıklara göre yazılmamalıdır, çünkü sıradaki panelde onlar olmayacak.

Sipariş alanları hizmet türüne bağlı

İlk entegrasyondaki en büyük yanılgı, siparişin bir bağlantı ve bir miktar olduğudur. Bu yalnızca temel türdür. services içindeki type alanı metin bir ad olarak gelir ve add\'in bütün parametre setini o belirler:

• Default - link ve quantity, kademeli teslim için isteğe bağlı runs ve interval.
• Custom Comments - link ve comments: miktar hiç gönderilmez, listedeki satır sayısından türetilir.
• Mentions ailesi - yalnızca kitlenin nereden geldiğiyle ayrışan altı ayrı tür: hazır bir usernames listesi, bir hashtag, başka bir hesabın takipçileri ya da belirli bir gönderiyi beğenenler.
• SEO miktarın yanında keywords alır; Poll ise oy verilecek seçeneğin sırası olan answer_number\'ı.
• Package - yalnızca link: ne miktar, ne ek alan, hacim hizmetin kendisine gömülü.
• Subscriptions - link diye bir şey yok. Yerine username, min ve max sınırları, kapalı bir dakika listesinden bir delay, ve d/m/Y biçiminde bir expiry tarihi var.
• Web Traffic - en genişi: country, device, type_of_traffic, üçü de kelime değil, bir eşleme tablosundan gelen sayılar olarak. Anahtar kelime trafiği ek olarak google_keyword, özel bir yönlendirici ise referring_url ister.

İki teknik ayrıntı neredeyse herkesi düşürür. Listeler - yorumlar, anahtar kelimeler, kullanıcı adları, hashtag\'ler - JSON dizisi olarak değil, ayırıcı olarak yeni satır kullanan tek bir metin olarak gönderilir. Ve device ile type_of_traffic\'in arkasındaki sayısal karşılıklar services yanıtında hiç dönmez: o değerleri panelin dokümanından önceden bilmeniz gerekir.

Açıkça kabul etmeye değer bir şey daha: tür numaralandırmasında boşluklar var. Motorların bildiği en az altı numara, ölçtüğümüz panellerin hiçbirinde görünmüyor. Dolayısıyla «her türü destekliyoruz» kimsenin tutamayacağı bir vaat - alıcı panel için doğru strateji, bilinmeyen türde alanları tahmin etmek yerine net bir ret vermektir. Türlerin gerçekte ne anlama geldiği sağlayıcının hizmet türleri yazısında açılıyor.

Entegrasyonların kırıldığı üç yer

Bu üçü neredeyse hiçbir doküman setinde yok, ve açılıştan bir hafta sonra yüzeye çıkan hataları üreten tam olarak onlar.

• Toplu yanıtın biçimi action\'a bağlıdır. status için sipariş numarasıyla anahtarlanmış bir nesne. refill, refill_status ve cancel için ise numarası her elemanın içinde duran bir nesne dizisi. Bütün toplu yanıtlar için tek bir ayrıştırıcı olmaz.
• Eleman başına hatalar iç içe gelir. İstek genelinde bir {"error": ...} olarak değil, elemanın kendi içinde, sonucun kullanacağı aynı anahtarın altında. Yalnızca en üst seviyeyi okuyan kod, yüz siparişten doksan dokuzunu işler ve yüzüncüsünü sessizce kaybeder.
• Refill, siparişin numarasıyla değil kendi numarasıyla adreslenir. action=refill bir refill numarası döndürür, ve refill_status onu yalnızca o numarayla bulur. API\'de sipariş ile refill arasında hiç bağ yoktur: o numarayı saklamak istemcinin işidir. Bazı paneller orada bir uzantı olarak sipariş numarasını da kabul eder - bizimki eder, böylece mevcut entegrasyonlar çalışmaya devam eder - ama standartta böyle bir şey yok.

İptal de aynı listeye ait: standartta tek siparişlik cancel yok, yalnızca toplu olan var. Siparişleri tek tek iptal eden bir istemcinin bile tek elemanlı bir liste göndermesi ve karşılığında bir dizi ayrıştırması gerekir.

Durumlar ve hatalar sabit değil, metindir

Sipariş durumu insan okuyabilir metin olarak gelir: Pending, In progress, Processing, Partial, Completed, Canceled, Fail, Error. Refill\'lerin kendi seti var - Completed, Rejected ve aradaki In progress - ve bilinmeyen bir refill numarası Refill not found olarak döner.

Bu da istemciye dört kural verir:

• Büyük-küçük harfe duyarsız karşılaştırın ve boşluklara güvenmeyin: farklı paneller aynı durumu birbirinden biraz farklı yazar.
• Bilinmeyen durum bir başarısızlık değildir. «Hiçbir şey değişmedi, sonra tekrar sor» demektir, «sipariş öldü» demez. Aksi hâlde bir panel setini ilk genişlettiğinde bir çığ hâlinde yanlış iade alırsınız.
• Parayı metin olarak ayrıştırın. charge ve balance dört ondalık basamaklı metin olarak gelir - float üzerinden geçmek onları başkasının lehine yuvarlar.
• İstek düzeyindeki hatalar da metindir: Incorrect API key, Incorrect order ID, Incorrect action. HTTP kodu pekâlâ 200 kalabilir, dolayısıyla yalnızca kodu kontrol etmek yetmez.

Durumların alıcı için ne anlama geldiği ve her durumda panelin ona ne borçlu olduğu SMM panelinde sipariş durumları yazısında; teslim edilen hacmin neden eridiği ve refill\'in buna nasıl cevap verdiği drop ve refill yazısında.

Entegrasyon canlıya çıkmadan nasıl sınanır

İlk gerçek siparişten önce neredeyse her şeyi yakalayan altı kontrol:

• services\'i çalıştırın ve gelen türleri kodunuzun ele aldıklarıyla karşılaştırın. Bilinmeyen bir tür, boş alanlı bir sipariş değil, net bir ret üretmelidir.
• Satmayı düşündüğünüz her türden bir sipariş verin. Alan seti hataları yalnızca böyle görünür, çünkü panel tarafındaki doğrulama katıdır.
• Yüz numarayla toplu status, ve bunlardan biri kesinlikle var olmasın. Bu, iç içe hata testidir - onsuz siparişler tek tek kaybolur.
• Tam refill döngüsü: refill, numarayı sakla, refill_status\'ı refill numarasıyla sor. Kodunuz sipariş numarasıyla sorup yine de yanıt alıyorsa, tek bir panelin uzantısına yaslanıyorsunuz.
• Yanlış anahtar. Yanıt yine JSON olmalı. HTML geliyorsa karşınızda API değil, web sunucusunun hata sayfası var, ve istemciniz bu ikisini ayırt etmek zorunda - aksi hâlde panel tarafındaki bir kesinti, bütün siparişlerin reddi gibi görünür.
• Yoklama hızı. Yüze kadar gruplar, sipariş başına dakikada birden fazla değil, her hatadan sonra büyüyen bir bekleme. Bitmiş siparişleri asla yoklamayın - hız sınırına boşuna çarpmanın en yaygın yolu budur.

Sağlayıcı tarafında ek iş var: anahtar başına limitler, çağrı günlüğü ve aynı siparişin iki kez gönderilmesine karşı koruma. Bir bayiye anahtar vermeden önce neyi kontrol etmeli, sağlayıcı olarak SMM hizmetleri nasıl satılır yazısında. Kendi sağlayıcınızın bizim tarafta desteklenip desteklenmediğini sağlayıcı kontrol sayfasında bakabilirsiniz.

Toparlarsak

API v2 basit görünür - tek uç nokta, yedi action - ve tam bu yüzden hafife alınır. Gerçek karmaşıklık üç noktada: hizmet türü sipariş alanlarını belirler, toplu yanıtın biçimi action\'a bağlıdır, ve refill kendi numarasının altında yaşar. Bu üçüne saygı gösteren bir istemci paneller arasında neredeyse hiç düzenleme olmadan taşınır; bunları kaçıran bir istemci siparişleri sessizce kaybeder.

İhtiyacınız olan API başkasının değil kendi panelinizinse, bütün bunlar peşin ödeme olmadan sınanabilir: kendi kataloğumuzdan giden siparişler kaç tane olursa olsun hiç faturalandırılmaz, üçüncü taraf sağlayıcılarda ise ayda ilk 100 sipariş ücretsizdir. Anahtar ve tam dokümantasyon hemen verilir, böylece panelin ilk müşterisi olmadan bir istemci yazıp on çağrının hepsini çalıştırabilirsiniz. O limitin nasıl sayıldığı kiralama planı nasıl hesaplanır yazısında anlatılıyor.