SosyalHawk
SOSYALHAWK DEVELOPERS

Panelini tek API ile SosyalHawk'a bağla.

Servis kataloğu, hesabına özel bayi fiyatı, sipariş oluşturma, durum takibi, bakiye, telafi, iptal ve HMAC imzalı webhook bildirimleri tek geliştirici altyapısında. Entegrasyonun yalnızca SosyalHawk servis ve sipariş kimlikleriyle çalışır.

POST https://sosyalhawk.com/api/v2
Authorization: Bearer sh_live_••••••••

action=add
service=128
link=https://...
quantity=1000
request_id=550e8400-e29b-41d4-a716-446655440000

{
  "order": 8421,
  "charge": "18.4000",
  "status": "Pending"
}
API

SMM + REST

Yaygın action tabanlı SMM entegrasyonlarının yanında modern JSON REST endpointleri.

IP

IP güvenliği

Anahtarı yalnızca belirlediğin IPv4/IPv6 sunucularından kullanılabilir hale getir.

↗

İmzalı webhook

Durum değişikliklerini HMAC-SHA256 imzası ve otomatik retry ile kendi paneline taşı.

₺

Bayi fiyatı

Bayi seviyen ve varsa servis bazlı özel fiyatın API kataloğuna otomatik uygulanır.

API V2 · TRY

Entegrasyon dokümantasyonu

API erişimi onaylı partner hesaplarına açılır. Önce API / Bayi Merkezi'nden erişim talebi gönderirsin; onaylandıktan sonra API anahtarını kendin oluşturursun ve tam anahtar yalnızca oluşturulduğu anda gösterilir. Anahtarı tarayıcı koduna veya herkese açık repoya koyma.

1. Kimlik doğrulama ve güvenlik

Tercih edilen yöntem Authorization: Bearer veya X-API-Key header'ıdır. SMM uyumluluğu için form içindeki key alanı da desteklenir.

Bearer

Authorization: Bearer sh_live_...

X-API-Key

X-API-Key: sh_live_...
180 istek / dakikaHer API anahtarı için ayrı limit.
IP whitelistOpsiyonel; tanımlanırsa diğer IP'ler reddedilir.
Hash ile saklamaAPI anahtarının kalıcı kaydında yalnızca hash tutulur; bir kerelik gösterim verisi oturumda şifreli taşınır.

2. Otomatik bayi seviyeleri

API hesabın son 30 günlük gerçek API sipariş hacmine göre otomatik seviyelenir. Seviye yükseldiğinde indirim sonraki API fiyatlarına uygulanır; services yanıtındaki rate hesabına uygulanmış nihai TRY fiyatıdır.

StandardBaşlangıç seviyesi · %0 otomatik indirim
Pro₺5.000 / 30g → %2.5'e kadar
Business₺25.000 / 30g → %5'e kadar

Yüksek hacimli veya özel anlaşmalı hesaplarda hesap bazlı özel indirim ve servis bazlı özel API fiyatı tanımlanabilir.

3. SMM uyumlu API

POSThttps://sosyalhawk.com/api/v2application/x-www-form-urlencoded
actionAlanlarSonuç
serviceskeyServis kataloğu ve hesabına özel TRY fiyatı
addservice, link/target, quantity, request_id?Yerel SosyalHawk sipariş numarası
statusorder veya ordersTek/bulk sipariş durumu
balancekeyMevcut TRY bakiye
refillorderUygun sipariş için telafi talebi
refill_statusrefillTelafi talebi durumu
cancelorderUygun sipariş için iptal talebi

Servisler

curl -X POST 'https://sosyalhawk.com/api/v2' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'key=sh_live_...' \
  --data-urlencode 'action=services'

Yeni sipariş

curl -X POST 'https://sosyalhawk.com/api/v2' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'key=sh_live_...' \
  --data-urlencode 'action=add' \
  --data-urlencode 'service=128' \
  --data-urlencode 'link=https://example.com/post' \
  --data-urlencode 'quantity=1000'

4. REST API

GET/api/v2/servicesKatalog + bayi fiyatı
GET/api/v2/balanceTRY bakiye
POST/api/v2/ordersYeni sipariş
GET/api/v2/orders/:idSipariş durumu
POST/api/v2/orders/:id/refillTelafi
GET/api/v2/refills/:idTelafi durumu
POST/api/v2/orders/:id/cancelİptal talebi

Node.js · yeni sipariş

const response = await fetch('https://sosyalhawk.com/api/v2/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sh_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    service: 128,
    link: 'https://example.com/post',
    quantity: 1000,
    request_id: crypto.randomUUID()
  })
});
const data = await response.json();

5. Sipariş alanları

AlanGerekliAçıklama
serviceEvetservices yanıtındaki SosyalHawk servis ID'si.
link / targetServise göreGönderinin/profilin hedef adresi veya servis hedefi.
quantityServise göreServisin min/max aralığında adet.
request_idÖnerilirUUID. Retry durumunda aynı UUID aynı siparişi ikinci kez oluşturmaz.
order_fieldsGelişmiş servislerdeJSON nesnesi. Yorum, kullanıcı adı, abonelik vb. servis özel alanları.

Gelişmiş servislerde comments, usernames, username, posts, runs, interval, min, max gibi desteklenen alanlar doğrudan veya order_fields içinde gönderilebilir. Zorunlu alanlar servis tipine göre doğrulanır.

6. Güvenli retry / idempotency

Sipariş verirken RFC uyumlu UUID biçiminde request_id göndermen önerilir. Ağ timeout'u sonrasında aynı isteği aynı request_id ile tekrar gönderirsen sistem mevcut yerel siparişi döndürür; ikinci kez bakiye kesmez.

Aynı hedef ve servisin birkaç saniye içinde yanlışlıkla çift gönderilmesine karşı ayrıca kısa süreli duplicate koruması bulunur. Yine de entegrasyon tarafında kalıcı retry anahtarı olarak request_id kullan.

7. Sipariş durumları

PendingSipariş alındı ve sırada.
In progressİşlem devam ediyor.
CompletedSipariş tamamlandı.
PartialKısmi tamamlandı.
Canceledİptal/başarısız son durum.
PendingSonucu doğrulanan belirsiz gönderimler güvenli şekilde beklemede gösterilir.

8. HMAC imzalı webhook

API Merkezi'nden HTTPS webhook adresini kaydet, imza anahtarını bir kez kopyala ve istersen Test Webhooku Gönder ile bağlantını doğrula. Sipariş durum olayları order.updated olarak gönderilir.

X-SosyalHawk-Eventorder.updated veya webhook.test
X-SosyalHawk-Signaturesha256=<hex>

Node.js · imza doğrulama

import crypto from 'node:crypto';

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.SOSYALHAWK_WEBHOOK_SECRET)
  .update(rawRequestBody)
  .digest('hex');

const actual = req.headers['x-sosyalhawk-signature'] || '';
const valid = actual.length === expected.length && crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(actual)
);

Webhook yalnızca HTTPS public hedeflere gider. Local/private ağ adresleri reddedilir, DNS hedefi doğrulanıp bağlantı sırasında aynı public IP'ye pinlenir, redirect takip edilmez. Başarısız teslimatlar artan aralıklarla en fazla 5 kez tekrar denenir.

9. Yaygın hata kodları

KodAnlamı
invalid_keyAnahtar geçersiz veya API erişimi kapalı.
ip_not_allowedİstek IP whitelist içinde değil.
rate_limitAnahtarın dakika limiti aşıldı.
insufficient_balanceHesap bakiyesi sipariş için yetersiz.
service_not_foundSosyalHawk servis ID'si bulunamadı.
request_id_invalidrequest_id geçerli UUID formatında değil.
refill_not_availableSipariş telafi koşullarını karşılamıyor.
cancel_not_availableSipariş iptal için uygun değil.
order_submission_uncertainGönderim sonucu doğrulanıyor; aynı işi farklı request_id ile tekrar yollama.
Geliştirici altyapısı ölçülebilir ve kendi kimliğiyle çalışır.

Public durum ekranındaki 24 saatlik API metrikleri gerçek istek günlüklerinden hesaplanır; doğrulanmamış “%99.99 uptime” veya yapay işlem sayıları gösterilmez.

Sistem Durumunu Gör →