REST API v2

Genel bakış

Bu, bir yapay zeka ajanının sürdüğü yüzeydir. Her çağrı, action tarafından seçilen tek bir fiildir, böylece bir ajan kataloğu arar, birim fiyatı ve limitleri geri okur, sonra harekete geçer; önce-ara-sonra-uygula, her para hareket etmeden önce fiyat onaylı. MCP sunucusu ve CLI aynı çağrıları sarar; bu sayfa altındaki ham protokoldür.

API, yaygın biçimde benimsenen SMM API v2 yapısını izler, böylece mevcut panel yazılımları, betikler ve ajan entegrasyonları en az değişiklikle çalışır. Her işlem tek bir uç noktadan geçer ve fiili action parametresiyle seçer. Yanıtlar JSON'dır. Bir betiğin ya da bir LLM'in ayrıştırıp zincirlemesi kolaydır.

Uç nokta

POST https://api.socialgo.com/api/v2

Kimlik doğrulama

Kimlik doğrulama istek başınadır; oturum yok, el sıkışma yok, bu da onu tam olarak bir ajan tarafından çağrılabilir kılan şeydir. Gizli key değerinizi her çağrıda gönderin. Panelde Hesap → API altında bulun ve döndürün. Anahtara bir parola gibi davranın: sunucu tarafında tutun, asla istemci kodunda ya da bir ajan istemcisinde değil.

İstek biçimi

application/x-www-form-urlencoded form parametrelerini POST ile gönderin. Her yanıt JSON'dır. Her çağrıda iki parametre bulunur:

• key: API anahtarınız (zorunlu)
• action: çalıştırılacak fiil (zorunlu)

Hata biçimi

Başarısızlıkta yanıt, insan tarafından okunabilir bir mesaj içeren bir error alanı taşır ve HTTP durumu sorunu yansıtır (ör. 400 hatalı istek, 401 geçersiz anahtar). Tek, öngörülebilir bir yapı; böylece bir betik ya da ajan tahmin yürütmeden dallanabilir.

{
  "error": "Incorrect request"
}

Eylemler

Her fiil tek bir iş yapar. Bir ajan onları sırayla zincirler: ne satın alacağını bulmak için services, satın almak için add, takip için status. Okuma çağrıları (services, status, balance), yazma çağrıları (add, refill, cancel) herhangi bir şey harcamadan önce fiyatı ve fonları onaylamasını sağlar.

1. Hizmetleri listele

Bir ajanın ilk okuduğu katalog: sipariş edebileceği her hizmet, hizmet numarası, kategorisi, birim fiyatı (1000 başına fiyat) ve min/maks miktarlarıyla. Sipariş vermek için dönen service numaralarını, harcamadan önce maliyeti onaylamak için de birim fiyatı kullanır.

İstek

key=YOUR_API_KEY
action=services

Yanıt

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. Sipariş ekle

Yazma çağrısı. Bir hizmet için sipariş verir. service numarasını, hedef link ve quantity değerini geçin. Yanıt, takip edilecek yeni order numarasını döndürür. Bir ajan bunu yalnızca birim fiyatı ve limitleri onayladıktan sonra çalıştırır.

Parametreler

• service: hizmet listesindeki hizmet numarası
• link: gönderinin / profilin / kanalın URL'si
• quantity: teslim edilecek birim sayısı

İstek

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

Yanıt

{
  "order": 23501
}

3. Sipariş ekle, drip-feed

Daha istikrarlı bir eğri için bir siparişi zamana yayılmış daha küçük teslimatlara böler. runs (kaç teslimat) ve interval (her biri arasındaki dakika) değerlerini ayarlayın. Toplam teslim edilen quantity × runs'tur. Bir ajanın, siz elle hesaplamadan bir kampanyayı boyutlandırmak için kullandığı matematik.

Ek parametreler

• runs: teslimat parti sayısı
• interval: her parti arasındaki dakika

İstek

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

Yanıt

{
  "order": 23502
}

4. Sipariş durumu

Bir siparişin güncel durumunu döndürür: ücret, başlangıç sayısı, durum, kalan miktar ve para birimi. Bir ajanın, siz paneli yenilemeden bir siparişi izlemesi ve telafiye değer bir düşüşü fark etmesi böyle olur.

İstek

key=YOUR_API_KEY
action=status
order=23501

Yanıt

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

Olası status değerleri: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Çoklu sipariş durumu

Tek çağrıda birçok siparişi kontrol edin. orders parametresinde virgülle ayrılmış bir numara listesi geçin. Yanıt sipariş numarasına göre anahtarlanır, böylece bir ajan sipariş başına bir çağrı yerine tüm bir kampanyayı tek gidiş-dönüşte yoklar.

İstek

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

Yanıt

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. Telafi

Hizmeti telafiyi destekleyen (hizmet listesinde refill: true) bir sipariş için telafi ister ve takip edilecek bir telafi numarası döndürür. Tek bir order ya da virgülle ayrılmış bir orders listesi geçin. Böylece bir ajan, durum kontrolü düşüşleri işaretledikten sonra toplu telafi isteyebilir.

İstek (tekli)

key=YOUR_API_KEY
action=refill
order=23501

Yanıt

{
  "refill": 4001
}

İstek (çoklu)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Yanıt

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. İptal

Henüz işlenmemiş siparişlerin iptalini ister (cancel: true olan hizmetler). Virgülle ayrılmış bir orders listesi geçin; yanıt sonucu sipariş başına raporlar. Bir şey yanlışlıkla sıraya girdiğinde bir ajanın başvurduğu geri alma.

İstek

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Yanıt

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. Bakiye

Hesap bakiyenizi ve para biriminizi döndürür. Bir ajan, sipariş vermeden önce harcamayı sınırlamak için okur; kendi paneliniz de fonları göstermek için okur. Harcanacak para olduğunu onaylayacak en ucuz çağrı.

İstek

key=YOUR_API_KEY
action=balance

Yanıt

{
  "balance": "182.45",
  "currency": "USD"
}

Her yerden çağırın

Tek uç nokta, sade form parametreleri. Böylece bir kabuk, bir cron işi ya da bir ajan onu aynı şekilde sürebilir. İşte komut satırından verilmiş eksiksiz bir sipariş:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

Notlar ve en iyi uygulamalar

• Yazmadan önce okuyun. Birim fiyatı, limitleri ve fonları onaylamak için services (ya da balance) çağırın, sonra add çağırın. Panelin ve MCP sunucusunun kullandığı aynı önce-ara-sonra-uygula güvencesi; böylece hiçbir şey onaylı bir fiyat olmadan harcanmaz.
• Hizmet listesini önbelleğe alın ve düzenli olarak yenileyin; numaralar, birim fiyatlar ve limitler değişir.
• Reddedilen çağrılardan kaçınmak için bir sipariş göndermeden önce min/max miktarlarını doğrulayın.
• Sipariş başına bir istek yerine çoklu-sipariş çağrısıyla durumu partiler hâlinde yoklayın.
• Anahtarınızı sunucu tarafında tutun. Bir şekilde ifşa olursa, panelden anında döndürün.