مستندات API خرید پلن BoxAPI

با استفاده از APIهای BoxAPI می‌توانید وضعیت پلن‌های فعال، محدودیت‌ها و موجودی کیف پول کاربر را دریافت کرده و همچنین به‌صورت برنامه‌نویسی‌شده پلن‌های BoxAPI را خریداری، تمدید یا افزایش ظرفیت کنید.

احراز هویت

تمامی درخواست‌ها به APIهای BoxAPI باید با استفاده از Bearer Token احراز هویت شوند.

توکن موردنیاز را می‌توانید از پنل کاربری BoxAPI، در بخش خرید اعتبار دریافت کنید.

Header احراز هویت

Authorization: Bearer BOXAPI_TOKEN

در تمامی درخواست‌ها باید Header بالا ارسال شود.

---

خرید، افزایش ظرفیت و تمدید پلن

این Endpoint برای خرید پلن جدید، افزایش ظرفیت پلن و تمدید پلن‌های BoxAPI استفاده می‌شود.

Endpoint

POST https://boxapi.ir/wallet/v1/purchase

Headers

Authorization: Bearer BOXAPI_TOKEN
Content-Type: application/json

Body

{
  "api_type": "API_TYPE",
  "quantity": 5,
  "duration": "yearly",
  "discount_code": "SUMMER20",
  "mode": "renew",
  "confirm_downgrade": false
}

پارامترها

پارامتر	نوع	اجباری	توضیحات
api_type	string	بله	نوع API موردنظر برای خرید
quantity	integer	بله	تعداد Request برای API دیتا یا تعداد پیج برای API دایرکت
duration	string	بله	مدت زمان پلن
discount_code	string	خیر	کد تخفیف یا کد معرف
mode	string	خیر	نوع درخواست برای API دایرکت روی پلن فعال. مقادیر increase و renew
confirm_downgrade	boolean	خیر	تأیید کاهش تعداد پیج هنگام تمدید پلن دایرکت

مقدار api_type

مقدار	توضیحات
instagram_dm_api	API رسمی دایرکت اینستاگرام
instagram_data_api	API دیتای اینستاگرام

پارامتر quantity

مقدار quantity بر اساس نوع API متفاوت است :

API دیتای اینستاگرام

در instagram_data_api، مقدار quantity نشان‌دهنده تعداد Requestهای خریداری‌شده است.

برای مثال:

{
  "api_type": "instagram_data_api",
  "quantity": 3000,
  "duration": "monthly"
}

اگر کاربر در حال حاضر یک پلن فعال داشته باشد، خرید جدید در صورت باقی‌ماندن هم زمان و هم Request، به‌صورت رزرو ثبت می‌شود و پس از پایان پلن فعلی به‌صورت خودکار فعال خواهد شد.

در صورتی که پلن زمانش تمام شده باشد، Requestهای آن تمام شده باشد یا کاربر پلنی نداشته باشد، خرید جدید بلافاصله فعال می‌شود.

در حالت فعال‌سازی به‌دلیل تمام‌شدن Requestها، ظرفیت جدید به ظرفیت قبلی اضافه می‌شود. در حالت پایان اعتبار زمانی، سقف و شمارنده پلن به‌طور کامل ریست می‌شوند.

API رسمی دایرکت اینستاگرام

در instagram_dm_api، مقدار quantity نشان‌دهنده تعداد پیج‌های اینستاگرام است.

اگر کاربر پلن فعال نداشته باشد یا پلن قبلی منقضی شده باشد، خرید جدید به‌صورت عادی فعال می‌شود.

در صورت داشتن پلن فعال، می‌توان از پارامتر mode برای تعیین نوع عملیات استفاده کرد.

افزایش تعداد پیج‌ها

با استفاده از:

"mode": "increase"

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

فرمول هزینه افزایش ظرفیت:

هزینه = روزهای باقی‌مانده × قیمت روزانه هر پیج × (تعداد جدید − تعداد فعلی)

تمدید پلن

با استفاده از:

"mode": "renew"

مدت زمان جدید به زمان باقی‌مانده پلن فعلی اضافه می‌شود و پلن بدون قطعی ادامه پیدا می‌کند.

مدت دوره‌ها به شکل زیر محاسبه می‌شود:

• ماهانه: ۳۰ روز
• سالانه: ۳۶۵ روز

در تمدید پلن، اگر تعداد پیج جدید بیشتر از تعداد فعلی باشد، هزینه افزایش ظرفیت برای بازه باقی‌مانده نیز محاسبه می‌شود.

فرمول کلی:

هزینه دوره جدید
+
هزینه ارتقای بازه باقی‌مانده
−
تخفیف

در صورتی که تعداد پیج جدید کمتر از تعداد فعلی باشد، کاهش تعداد پیج نیازمند تأیید صریح کاربر است.

کاهش تعداد پیج

اگر در حالت renew تعداد پیج درخواستی کمتر از تعداد فعلی باشد، درخواست ابتدا با خطای bpm_direct_downgrade_confirm مواجه می‌شود.

برای ادامه باید پارامتر زیر ارسال شود:

"confirm_downgrade": true

پس از کاهش تعداد پیج، تمامی پیج‌های لاگین‌شده غیرفعال می‌شوند و کاربر باید حداکثر به تعداد سقف جدید، پیج‌های موردنظر خود را مجدداً فعال کند.

پارامتر duration

مدت زمان پلن با پارامتر duration مشخص می‌شود.

مقدار	توضیحات
monthly	پلن ماهانه
yearly	پلن سالانه

پارامتر mode

پارامتر mode فقط برای API دایرکت اینستاگرام و زمانی که پلن فعال وجود دارد کاربرد دارد.

مقدار	توضیحات
auto	حالت پیش‌فرض؛ رفتار قبلی و افزایش تعداد پیج
increase	افزایش تعداد پیج بدون تغییر تاریخ انقضا
renew	تمدید زمان پلن و اضافه‌شدن دوره جدید به زمان باقی‌مانده

شرایط ثبت خرید

برای ثبت موفق خرید، حساب کاربر باید دارای موجودی کافی در کیف پول BoxAPI باشد.

مبلغ خرید از موجودی کیف پول کاربر کسر می‌شود و در صورت موفقیت، پلن خریداری‌شده، افزایش‌یافته یا تمدیدشده خواهد شد.

نمونه درخواست

curl -X POST "https://boxapi.ir/wallet/v1/purchase" \
  -H "Authorization: Bearer BOXAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_type": "instagram_dm_api",
    "quantity": 8,
    "duration": "yearly",
    "discount_code": "SUMMER20",
    "mode": "renew",
    "confirm_downgrade": false
  }'

نمونه پاسخ موفق

{
  "success": true,
  "data": {
    "message": "پلن API دایرکت اینستاگرام با موفقیت تمدید شد.",
    "warning": null,
    "order_id": 812,
    "amount_paid": 1450000,
    "new_balance": 320000,
    "status": {
      "quantity": 8,
      "expires_at": "2026-11-04 09:12:00",
      "is_effectively_active": true
    }
  }
}

توضیح Response

فیلد	توضیحات
success	مشخص می‌کند درخواست با موفقیت انجام شده است یا خیر.
message	پیام مربوط به نتیجه عملیات خرید، افزایش ظرفیت یا تمدید.
warning	هشدار مربوط به عملیات، در صورت وجود.
order_id	شناسه سفارش ایجادشده.
amount_paid	مبلغ پرداخت‌شده برای عملیات.
new_balance	موجودی کیف پول کاربر پس از کسر مبلغ خرید.
status.quantity	ظرفیت فعلی پلن؛ تعداد Request برای API دیتا و تعداد پیج برای API دایرکت.
status.expires_at	تاریخ و زمان پایان اعتبار پلن.
status.is_effectively_active	مشخص می‌کند پلن از نظر عملیاتی فعال است یا خیر.

خطای کاهش تعداد پیج بدون تأیید

اگر کاربر هنگام تمدید تعداد پیج کمتری نسبت به ظرفیت فعلی درخواست کند، ابتدا پاسخ زیر دریافت می‌شود:

{
  "success": false,
  "requires_confirmation": true,
  "current_pages": 8,
  "requested_pages": 3,
  "total_price": 1200000,
  "code": "bpm_direct_downgrade_confirm",
  "message": "با کاهش تعداد پیج از ۸ به ۳، تمامی پیج‌های لاگین‌شدهٔ شما غیرفعال می‌شوند و باید با اندپوینت فعال‌سازی پیج، حداکثر ۳ پیج موردنظرتان را دوباره فعال کنید. برای ادامه، confirm_downgrade را true بفرستید."
}

برای ادامه عملیات باید همان درخواست با مقدار زیر ارسال شود:

"confirm_downgrade": true

---

دریافت وضعیت پلن‌ها

این Endpoint برای دریافت موجودی کیف پول، پلن‌های فعال، محدودیت‌ها، میزان مصرف و وضعیت APIهای کاربر استفاده می‌شود.

Endpoint

GET https://boxapi.ir/wallet/v1/status

Headers

Authorization: Bearer BOXAPI_TOKEN

نمونه درخواست

curl -X GET "https://boxapi.ir/wallet/v1/status" \
  -H "Authorization: Bearer BOXAPI_TOKEN"

نمونه پاسخ

{
  "success": true,
  "data": {
    "balance": 0,
    "instagram_data_api": {
      "limit": 10,
      "count": 1,
      "remaining": 9,
      "expires_at": "2026-08-07 10:01:21",
      "has_plan": true,
      "is_time_expired": true,
      "is_request_exhausted": false,
      "is_effectively_active": false
    },
    "instagram_dm_api": {
      "limit": 4,
      "expires_at": "2026-09-12 15:03:48",
      "has_plan": true,
      "is_time_expired": false,
      "is_effectively_active": true,
      "remaining_days": 27,
      "remaining_seconds": 2351437,
      "used": 2,
      "is_registered": true,
      "remote_error": null,
      "plan_name": "BoxAPI Free Plan",
      "is_active": true
    }
  }
}

فیلدهای عمومی

فیلد	توضیحات
balance	موجودی فعلی کیف پول کاربر.

فیلدهای instagram_data_api

فیلد	توضیحات
limit	تعداد کل Requestهای خریداری‌شده در پلن.
count	تعداد Requestهای مصرف‌شده.
remaining	تعداد Requestهای باقی‌مانده.
expires_at	تاریخ و زمان پایان اعتبار پلن.
has_plan	مشخص می‌کند کاربر برای این API پلن دارد یا خیر.
is_time_expired	مشخص می‌کند زمان اعتبار پلن به پایان رسیده است یا خیر.
is_request_exhausted	مشخص می‌کند تمام Requestهای پلن مصرف شده‌اند یا خیر.
is_effectively_active	مشخص می‌کند پلن در حال حاضر از نظر عملیاتی فعال است یا خیر.

فیلدهای instagram_dm_api

فیلد	توضیحات
limit	حداکثر تعداد پیج‌هایی که کاربر می‌تواند با پلن مدیریت کند.
expires_at	تاریخ و زمان پایان اعتبار پلن.
has_plan	مشخص می‌کند کاربر برای API دایرکت پلن دارد یا خیر.
is_time_expired	مشخص می‌کند زمان اعتبار پلن به پایان رسیده است یا خیر.
is_effectively_active	مشخص می‌کند پلن در حال حاضر از نظر عملیاتی فعال است یا خیر.
remaining_days	تعداد روزهای باقی‌مانده از اعتبار پلن.
remaining_seconds	تعداد ثانیه‌های باقی‌مانده از اعتبار پلن.
used	تعداد پیج‌های استفاده‌شده از ظرفیت پلن.
is_registered	مشخص می‌کند سرویس دایرکت برای کاربر ثبت و راه‌اندازی شده است یا خیر.
remote_error	خطای دریافت‌شده از سرویس راه دور، در صورت وجود. در حالت عادی مقدار null است.
plan_name	نام پلن فعال کاربر.
is_active	وضعیت فعال بودن پلن.

---

نکات مهم

• هر دو Endpoint نیازمند احراز هویت با Bearer Token هستند.
• برای خرید پلن، کیف پول کاربر باید موجودی کافی داشته باشد.
• در API دیتای اینستاگرام، quantity نشان‌دهنده تعداد Requestها است.
• در API دایرکت اینستاگرام، quantity نشان‌دهنده تعداد پیج‌ها است.
• در API دایرکت، روی پلن فعال می‌توان از mode= increase برای افزایش تعداد پیج یا mode=renew برای تمدید زمان استفاده کرد.
• در تمدید پلن دایرکت، زمان باقی‌مانده پلن قبلی از بین نمی‌رود و به دوره جدید اضافه می‌شود.
• در صورت کاهش تعداد پیج هنگام تمدید، ارسال confirm_downgrade: true الزامی است.
• در صورت کاهش تعداد پیج، تمامی پیج‌های لاگین‌شده غیرفعال می‌شوند و باید مجدداً فعال شوند.
• پارامتر discount_code برای اعمال کد تخفیف یا کد معرف قابل استفاده است.
• مقدار duration فقط می‌تواند monthly یا yearly باشد.
• وضعیت واقعی فعال بودن پلن را می‌توان با فیلد is_effectively_active بررسی کرد.