Bayi API belgeleri

SHOP2TOPUP bayi API'si; kendi mağazanızdan, vitrininizden veya botunuzdan oyun yüklemeleri, oyun bakiyesi ve kupon kodları satmanız için hazırlanmış bir JSON REST API'dir. Bu referans, herkese açık her uç noktayı, parametrelerini ve yanıtlarını belgeler.

Temel URL ve aktarım

Bu referanstaki her yol aşağıdaki temel URL'ye görelidir. İstekler ve yanıtlar HTTPS üzerinden JSON'dur, tutarlar kayan nokta yuvarlaması sızmasın diye metin olarak gelir ve her zaman damgası ISO 8601 biçiminde UTC'dir.

https://shop2topup.com/api/endpoints/v1

Kimlik doğrulama

Her istek tek bir başlık taşır. Anahtar çifti bayi panelinizin API Access sayfasından üretilir ve bir IP izin listesiyle sınırlanabilir; başka bir adresten gelen çağrı, herhangi bir iş mantığına ulaşmadan IP_NOT_ALLOWED ile reddedilir.

İstek başlığı

Authorization: Bearer <keyId>.<secret>

İlk çağrı

Kurulacak bir şey yok. Kendi anahtarınızı yerleştirin; bu çağrı canlı katalog verisi döndürür.

İstek — cURL

curl -s "https://shop2topup.com/api/endpoints/v1/catalog/categories?bigCategoryId=1" \
  -H "Authorization: Bearer YOUR_KEY_ID.YOUR_KEY_SECRET"

Yanıt kuralları

Her yanıt boolean bir success alanı taşır; böylece tek bir dal, mutlu yolu her tür hatadan ayırır.
Hatalar; kararlı bir code, insan için yazılmış bir message ve isteğe bağlı details içeren bir error nesnesi döndürür. Mesaj üzerinden değil, kod üzerinden dallanın.
Para her zaman USD cinsinden "0.950000" gibi ondalık bir metindir. Karşılaştırmadan veya toplamadan önce ikili kayan noktaya çevirmeyin.
Liste uç noktaları page, limit, total ve total_pages alanlarını içeren bir pagination nesnesi döndürür.
Sipariş oluşturma, sağladığınız order_id UUID'si üzerinden idempotenttir; bu yüzden bir yeniden deneme asla iki kez tahsilat yapamaz.

Hata yanıtı

{
  "success": false,
  "error": {
    "code": "PRICE_INCREASED",
    "message": "Price has increased beyond expected",
    "details": {
      "expected_unit_price": "0.950000",
      "current_unit_price": "0.980000"
    }
  }
}

Referans bölümleri

KatalogKatalog üç seviyeli bir ağaçtır: büyük kategoriler kategorileri, kategoriler alt kategorileri barındırır ve alt kategori de asıl satın aldığınız kalemdir. Bu uç noktalar, ağacı kendi veritabanınıza yansıtmanızı ve siparişten hemen önce bir kalemi fiyatlandırmanızı sağlar.Oyuncu doğrulamaOyuncu doğrulama, para hareket etmeden önce oyun içi hesabı çözümler. Kimliğin o ürün için var olduğunu doğrular, alıcınızın kontrol edebilmesi için oyun içi adı döndürür ve bölgeyi açığa çıkarır; böylece bölgeler arası bir sipariş, ödemeden sonra başarısız olmak yerine baştan reddedilir.SiparişlerSiparişler, sizin ürettiğiniz bir UUID ile oluşturulur. Bu UUID idempotency anahtarıdır: yinelendiğinde iki kez tahsilat yapmak yerine orijinal siparişi döndürür. Durum daha sonra sipariş başına, elliye kadar toplu halde veya sayfalanmış bir liste olarak okunur.Hesap ve erişimHer istek tek bir başlık taşır. GET /account; bir anahtarın çalıştığını kanıtlamak, siparişlerinizin harcadığı cüzdan bakiyesini okumak ve toplu bir çalıştırmaya başlamadan önce hesabın etkin olduğunu doğrulamak için çağırdığınız uç noktadır.Hata kodlarıHer hata, HTTP durumunun yanında kararlı ve makine tarafından okunabilir bir kod döndürür. Mesaj metni üzerinden değil kod üzerinden dallanın: mesajlar insanlar için yazılmıştır ve yeniden ifade edilebilir, kodlar ise sözleşmenin parçasıdır.

Hız sınırları

Sınırlar, kayan bir pencerede hesap bazında uygulanır. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset taşır; kısıtlanan bir çağrı ise Retry-After başlığıyla 429 döner.

Rota	İstek	Pencere	Sayım birimi
GET /catalog/* (all five)	80	60s	per account
POST /orders/create	120	60s	per account
GET /orders/:orderId	3	60s	per account + order id
POST /orders/batch	2	60s	per account
GET /orders	2	60s	per account
GET /account	60	60s	per account
POST /player/validate	dedicated limiter	—	per account

Webhook'lar

Sipariş sonuçları, kaydettiğiniz bir HTTPS uç noktasına gönderilir ve ham gövde üzerinden HMAC-SHA256 ile imzalanır. Olay listesi, başlık listesi, yük biçimi ve bir doğrulama örneği API genel bakış sayfasında belgelenmiştir.

Webhook yükü ve imza referansını okuyun

Platformda yeni misiniz? bayiler için oyun yükleme API'sine genel bakış ile başlayın veya SHOP2TOPUP bayi programına genel bakış sayfasından iş ortağı hesabının nasıl çalıştığını okuyun.