راهنمای API پنگو

همهٔ کارهای ربات @GoPenguPanel_bot را می‌توانید از برنامهٔ خودتان انجام دهید: خرید پنل، خرید حجم و زمان، دیدن وضعیت و مدیریت پنل‌ها.

شروع

در ربات به 👛 کیف پول ← 🔌 دسترسی API بروید و ساخت کلید API را بزنید.
کلید فقط یک بار نمایش داده می‌شود؛ آن را امن نگه دارید. هر کس کلید را داشته باشد می‌تواند با موجودی کیف پول شما خرید کند. اگر لو رفت، از همان صفحه باطلش کنید یا کلید جدید بسازید.
کیف پول را از داخل ربات شارژ کنید. همهٔ خریدهای API از موجودی کیف پول کم می‌شود.

آدرس پایه:

https://go-pengu-bot.gopengu.ir/v1

کلید را در هر درخواست در هدر بفرستید:

Authorization: Bearer pgb_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

هدر X-API-Key هم قبول می‌شود. بدنهٔ درخواست‌ها JSON است (Content-Type: application/json).

واحدها: مبلغ‌ها به تومان؛ حجم در خرید به گیگابایت (gb) و در وضعیت پنل به بایت؛ زمان‌ها ISO-8601 و به وقت UTC. مقدار null برای حجم یا مدت یعنی نامحدود / بدون انقضا.
محدودیت: ۶۰ درخواست در دقیقه برای هر کلید.

قالب پاسخ

پاسخ موفق:

{ "ok": true, "data": { ... } }

پاسخ خطا:

{ "ok": false, "error": { "code": "insufficient_balance", "message": "موجودی کیف پول کافی نیست.", "price": 650000, "balance": 120000 } }

code ثابت و انگلیسی است و برای برنامه‌تان مناسب است؛ message فارسی است و برای نمایش به کاربر.

کدهای خطا

HTTP	code	یعنی
400	`invalid_json` · `invalid_field` · `invalid_username` · `invalid_coupon` · `below_minimum` · `confirm_required` · `nothing_to_change`	ورودی نادرست
401	`unauthorized`	کلید نیامده، اشتباه است یا باطل شده
402	`insufficient_balance`	موجودی کیف پول کافی نیست (قیمت و موجودی در پاسخ هست)
403	`blocked` · `purchase_needs_approval` · `disabled_by_admin` · `expired`	اجازهٔ این کار را ندارید
404	`panel_not_found` · `package_not_found` · `plan_not_found` · `order_not_found` · `not_found`	پیدا نشد
409	`username_taken` · `panel_limit` · `trial_panel` · `unlimited_panel` · `already_active` · `already_disabled` · `cannot_delete`	با وضعیت فعلی جور نیست
429	`rate_limited`	درخواست زیاد؛ `retry_after` ثانیه صبر کنید
502	`panel_error`	پنل خطا داد؛ اگر پولی کم شده بود به کیف پول برگشته است
503	`api_disabled` · `service_closed` · `wallet_payments_disabled` · `pricing_not_set`	سرویس فعلاً در دسترس نیست

حساب و کیف پول

/v1/meGET

اطلاعات حساب، موجودی، درصد تخفیف دائمی و نام پنل‌ها.

{ "telegram_id": 123456789, "username": "ali", "balance": 1250000,
  "discount_percent": 0, "panels": ["ali_shop"] }

/v1/wallet?limit=20GET

موجودی و آخرین تراکنش‌ها (حداکثر ۱۰۰). مبلغ منفی یعنی برداشت.

{ "balance": 1250000, "transactions": [
  { "id": 812, "kind": "purchase", "amount": -650000, "panel": "ali_shop",
    "detail": "خرید ۵۰۰ گیگ حجم", "created_at": "2026-11-10T10:21:04+00:00" } ] }

/v1/pingGET

بررسی در دسترس بودن سرویس. کلید لازم ندارد.

قیمت‌ها

/v1/pricesGET

پکیج‌های خرید پنل، پلن‌های تمدید و قیمت حجم. your_price قیمت بعد از تخفیف دائمی شماست.

{ "currency": "toman", "discount_percent": 0,
  "packages": [ { "id": 3, "title": "Pro", "gb": 500, "days": 30, "max_users": null,
                  "price": 650000, "your_price": 650000 } ],
  "plans":    [ { "id": 1, "title": "ماهانه", "days": 30, "price": 300000, "your_price": 300000 } ],
  "traffic":  { "tiers": [ { "up_to_gb": 1000, "price_per_gb": 1100 },
                           { "up_to_gb": null, "price_per_gb": 1000 } ],
                "flat_price_per_gb": null, "min_gb": 200 } }

در tiers قیمت هر گیگ بر اساس کل مقدار خرید است؛ پلهٔ up_to_gb: null یعنی «بیشتر از پلهٔ قبل».

/v1/traffic/price?gb=500GET

قیمت دقیق یک مقدار حجم، پیش از خرید.

{ "gb": 500, "price_per_gb": 1100, "base_price": 550000, "discount_percent": 0, "price": 550000 }

پنل‌ها

/v1/panelsGET

همهٔ پنل‌های شما با وضعیت زنده.

[ { "name": "ali_shop", "is_trial": false, "expires_at": "2026-12-10T09:00:00+00:00",
    "status": "active", "disabled_by_you": false,
    "data_limit": 536870912000, "used_traffic": 104857600000, "remaining_traffic": 432013312000,
    "total_users": 85, "profile_title": "Ali VPN", "support_url": "https://t.me/ali" } ]

status یکی از active، disabled، limited، expired است.

/v1/panels/{name}GET

جزئیات یک پنل؛ همان فیلدهای بالا به‌اضافهٔ login_url و در صورت وجود custom_domain.

خرید (از کیف پول)

همهٔ خریدها فوری انجام می‌شوند: مبلغ از کیف پول کم و همان لحظه روی پنل اعمال می‌شود. اگر پنل خطا بدهد، پول به کیف پول برمی‌گردد. در هر خرید می‌توانید coupon (کد تخفیف) هم بفرستید.

پاسخ همهٔ خریدها:

{ "order_id": 1543, "price": 550000, "result": "۵۰۰ گیگ به حجم پنل «ali_shop» اضافه شد.", "balance": 700000 }

/v1/panelsPOST

خرید پنل نمایندگی جدید. نام کاربری ۳ تا ۳۲ کاراکتر، فقط حروف انگلیسی، عدد و _.

{ "package_id": 3, "username": "ali_shop2", "coupon": "OFF20" }

در پاسخ، اطلاعات ورود پنل جدید هم هست (در ربات هم برایتان فرستاده می‌شود):

{ "order_id": 1544, "price": 650000, "result": "...", "balance": 50000,
  "panel": { "name": "ali_shop2", "password": "Xy7...", "login_url": "https://.../dashboard/" } }

/v1/panels/{name}/trafficPOST

خرید حجم برای یک پنل.

{ "gb": 500 }

/v1/panels/{name}/renewPOST

تمدید زمان پنل با یکی از پلن‌ها. پاسخ expires_at جدید را هم دارد.

{ "plan_id": 1 }

مدیریت پنل

/v1/panels/{name}/passwordPOST

ساخت رمز جدید برای ورود به پنل. رمز قبلی همان لحظه از کار می‌افتد.

{ "name": "ali_shop", "password": "Qw9..." }

/v1/panels/{name}PATCH

عنوان پروفایل (اسمی که کاربرانتان در برنامه می‌بینند) و لینک پشتیبانی. هر کدام را بخواهید بفرستید؛ لینک خالی یعنی حذف.

{ "profile_title": "Ali VPN", "support_url": "@ali_support" }

/v1/panels/{name}/disablePOST

غیرفعال کردن پنل: ورود بسته و اتصال همهٔ کاربرانش قطع می‌شود. زمان اشتراک متوقف نمی‌شود.

/v1/panels/{name}/enablePOST

فعال کردن دوباره؛ فقط برای پنلی که خودتان غیرفعال کرده‌اید و هنوز اشتراک دارد.

/v1/panels/{name}DELETE

حذف همیشگی پنل و همهٔ کاربرانش. برگشت‌پذیر نیست و هزینه‌ای برنمی‌گردد. برای جلوگیری از اشتباه، نام پنل را در confirm تکرار کنید. اگر سفارش باز یا انتقال کاربر در جریان باشد، حذف انجام نمی‌شود.

{ "confirm": "ali_shop" }

سفارش‌ها

/v1/orders?limit=20GET

آخرین سفارش‌های شما (از ربات و API).

[ { "id": 1543, "kind": "traffic", "panel": "ali_shop", "title": "خرید ۵۰۰ گیگ حجم",
    "gb": 500, "days": null, "amount": 550000, "status": "approved",
    "created_at": "2026-11-10T10:21:04+00:00" } ]

kind: signup، traffic، plan، wallet، … — status: approved، pending، awaiting_receipt، rejected، cancelled.

/v1/orders/{id}GET

یک سفارش.

نمونهٔ کامل

curl:

KEY="pgb_..."
API="https://go-pengu-bot.gopengu.ir/v1"

curl -s "$API/me" -H "Authorization: Bearer $KEY"

curl -s "$API/traffic/price?gb=500" -H "Authorization: Bearer $KEY"

curl -s -X POST "$API/panels/ali_shop/traffic" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"gb": 500}'

Python:

import requests

API = "https://go-pengu-bot.gopengu.ir/v1"
s = requests.Session()
s.headers["Authorization"] = "Bearer pgb_..."

me = s.get(f"{API}/me").json()["data"]
print("balance:", me["balance"])

r = s.post(f"{API}/panels/ali_shop/traffic", json={"gb": 500}).json()
if r["ok"]:
    print(r["data"]["result"], "| balance:", r["data"]["balance"])
else:
    print("error:", r["error"]["code"], r["error"]["message"])

چیزهایی که فقط در ربات است

شارژ کیف پول (کارت به کارت و ارسال رسید)
پنل تست رایگان
انتقال پنل به اکانت دیگر، انتقال کاربران از پنل قبلی، دامنهٔ اختصاصی ساب
خرید حجم یکجا و تقسیمش بین چند پنل

سؤال یا مشکل: از دکمهٔ «💬 پشتیبانی» در ربات.