API.SHAHPANEL

⚡ اتصال Perfect Panel / Smart Panel و پنل‌های استاندارد

در تنظیمات Provider پنل خود، فقط URL و API Key را وارد کنید:

کپیAPI URL اصلی: https://api.shahpanel.com/api/v2API URL سازگار قدیمی: https://api.shahpanel.com/api/v1
API Key: sp_live_xxxxxxxxxxxxxxxxx

فرمت API استاندارد از اکشن‌های services، add، status، refill، refill_status، cancel و balance پشتیبانی می‌کند.

🔐 احراز هویت و امنیت

Standard API

کپیkey=sp_live_xxxxxxxxx

REST API

کپیAuthorization: Bearer sp_live_xxxxxxxxx

• کلیدها به‌صورت Hash ذخیره می‌شوند.
• می‌توانید دسترسی را فقط به IPهای مشخص محدود کنید.
• Rate Limit پیش‌فرض هر حساب در ربات و Dashboard نمایش داده می‌شود.
• برای ثبت سفارش REST از Idempotency-Key یکتا استفاده کنید.

📦 شناسه و جدول کامل سرویس‌ها

شناسه ستون اول همان مقداری است که باید در پارامتر service ارسال شود. نرخ نمایش‌داده‌شده قیمت عمومی هر ۱٬۰۰۰ واحد به تومان است؛ قیمت حساب نماینده می‌تواند بر اساس سطح یا تخفیف اختصاصی متفاوت باشد.

🚀 ثبت سفارش

Standard API

POST/api/v2

کپیcurl -X POST "https://api.shahpanel.com/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=SERVICE_ID" \
  -d "link=TARGET" \
  -d "quantity=QUANTITY" \
  -d "client_order_id=YOUR_UNIQUE_ID"

پاسخ:

{
  "status": "success",
  "order": 1570
}

REST API

POST/v1/orders

کپیcurl -X POST "https://api.shahpanel.com/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: site-order-10001" \
  -d '{
    "service": 1,
    "target": "https://t.me/channelname",
    "quantity": 100,
    "client_order_id": "site-order-10001"
  }'

کپی<?php
$payload = [
  'service' => 1,
  'target' => 'https://t.me/channelname',
  'quantity' => 100,
  'client_order_id' => 'site-order-10001',
];

$ch = curl_init('https://api.shahpanel.com/v1/orders');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer YOUR_API_KEY',
    'Content-Type: application/json',
    'Idempotency-Key: site-order-10001',
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

کپیimport requests

response = requests.post(
    "https://api.shahpanel.com/v1/orders",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "site-order-10001",
    },
    json={
        "service": 1,
        "target": "https://t.me/channelname",
        "quantity": 100,
        "client_order_id": "site-order-10001",
    },
    timeout=30,
)
print(response.json())

کپیconst response = await fetch("https://api.shahpanel.com/v1/orders", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "site-order-10001"
  },
  body: JSON.stringify({
    service: 1,
    target: "https://t.me/channelname",
    quantity: 100,
    client_order_id: "site-order-10001"
  })
});
console.log(await response.json());

🔄 دریافت وضعیت سفارش

Standard API

کپیcurl -X POST "https://api.shahpanel.com/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "order=ORDER_ID"

دریافت گروهی حداکثر ۱۰۰ سفارش:

کپیcurl -X POST "https://api.shahpanel.com/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=1001,1002,1003"

REST API

GET/v1/orders/{id}

کپیcurl "https://api.shahpanel.com/v1/orders/1570" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/orders/status

{
  "orders": [1570, 1571, 1572]
}

{
  "order": "1570",
  "status": "completed",
  "charge": "12500.0000",
  "start_count": "125000",
  "remains": "0"
}

نمونه پاسخ چندگانه:

{
  "1570": {
    "order": "1570",
    "status": "completed",
    "charge": "12500.0000",
    "start_count": "125000",
    "remains": "0"
  },
  "2": "Incorrect order ID"
}

♻️ جبران ریزش و وضعیت آن

فقط سرویس‌هایی که ضمانت ریشارژ دارند این عملیات را می‌پذیرند.

کپیcurl -X POST "https://api.shahpanel.com/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=refill" \
  -d "order=ORDER_ID"

{"refill":"1"}

کپیcurl -X POST "https://api.shahpanel.com/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=refill_status" \
  -d "refill=1"

{"status":"Completed"}

🚫 درخواست لغو سفارش

لغو فقط برای سرویس‌هایی فعال است که در کاتالوگ مقدار cancel=true دارند. بازگشت وجه پس از تأیید وضعیت لغو توسط Provider انجام می‌شود.

Standard API

کپیcurl -X POST "https://api.shahpanel.com/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=1001,1002"

[
  {"order": 1001, "cancel": 1},
  {"order": 1002, "cancel": {"error": "Provider rejected cancellation"}}
]

REST API

کپیcurl -X POST "https://api.shahpanel.com/v1/orders/1570/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

💰 دریافت موجودی

Standard API

کپیcurl -X POST "https://api.shahpanel.com/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"

{
  "status": "success",
  "balance": "1320411.00",
  "currency": "TOMAN"
}

REST API

کپیcurl "https://api.shahpanel.com/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

⚙️ مسیرهای REST API

🌐 Webhook و امضای HMAC

وقتی وضعیت سفارش تغییر کند، رویدادهای زیر به URL شما ارسال می‌شوند:

هدرهای امنیتی:

X-ShahPanel-Event: order.completed
X-ShahPanel-Delivery: 1250
X-ShahPanel-Timestamp: 1782180000
X-ShahPanel-Signature: sha256=...

فرمول امضا:

hash_hmac('sha256', TIMESTAMP + '.' + RAW_BODY, WEBHOOK_SECRET)

تأیید امضا در PHP

کپی<?php
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_SHAHPANEL_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_SHAHPANEL_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $body,
    'YOUR_WEBHOOK_SECRET'
);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($body, true);
http_response_code(200);
echo 'OK';

🧪 محیط آزمایشی Sandbox

Sandbox هیچ موجودی واقعی کم نمی‌کند و سفارشی به Provider ارسال نمی‌شود. سفارش آزمایشی پس از حدود ۲۰ ثانیه به Completed تغییر می‌کند.

کپیcurl -X POST "https://api.shahpanel.com/sandbox/api/v2" \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=SERVICE_ID" \
  -d "link=TARGET" \
  -d "quantity=QUANTITY"

📌 وضعیت‌ها و خطاها

HTTP Statusهای REST