StardDevelopersداشبورد

ممبر با ادمین کردن ربات

POST/api/v1/services/members/invite
scope: orders:writeاحراز هویت: Bearerlive و test

به‌جای فرستادن لینک، ربات Stard را در کانال/گروه ادمین کن (با مجوز «دعوت کاربران»): پاسخ add_bot_url و token می‌دهد. بعد از ادمین شدن، ربات یک لینک دعوت اختصاصی می‌سازد و سفارش ممبر خودکار با همان لینک ثبت می‌شود (هزینه همان لحظه کسر می‌شود). ورود و خروج اعضا از همین لینک شمرده می‌شود. سفارش به حساب API تو لینک می‌شود و وب‌هوک order.created می‌آید.

درخواست

ناممحلنوعتوضیح
AuthorizationheaderstringالزامیBearer sk_live_… یا Bearer sk_test_…
Idempotency-Keyheaderstringاختیاریکلید یکتا

بدنه (JSON)

فیلدنوعتوضیح
servicestringاختیاریmembers (پیش‌فرض) یا premium_members
kindstringالزامیchannel یا group
quantityintegerالزامیتعداد ممبر
optionstringاختیاریسطح ضمانت
drip_runsintegerاختیاریارسال تدریجی
drip_intervalintegerاختیاریفاصله به دقیقه
max_priceintegerاختیاریسقف مبلغ
pay_currencystringاختیاریTON یا IRT
metadataobjectاختیاریداده‌ی دلخواه

نمونه

curl -X POST "https://stard-market.ir/api/v1/services/members/invite" \
  -H "Authorization: Bearer $STARD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mem-1001" \
  -d '{"kind": "channel", "quantity": 1000, "option": "g30"}'
پاسخ — 201
{
  "object": "member_invite",
  "environment": "test",
  "token": "mbr_test_k3Jd9QaZx1Lm",
  "status": "pending",
  "add_bot_url": "https://t.me/Stard_marketbot?startchannel=mem_test&admin=invite_users",
  "kind": "channel",
  "quantity": 1000,
  "amount": null,
  "expires_in": 3600,
  "order": null,
  "note": "در محیط test ربات ادمین نمی‌شود؛ برای آزمون سفارش ممبر از POST /services/orders استفاده کن."
}
هدرهای پاسخ
content-type: application/json

کاربرد و نکته‌ها

کی به کار می‌آید؟ وقتی صاحب کانال یا گروه نمی‌خواهد لینک دعوت بسازد و بفرستد. روند کامل:

  1. این اندپوینت را صدا بزن؛ پاسخ add_bot_url (لینک ادمین کردن ربات Stard با مجوز «دعوت کاربران») و token می‌دهد.
  2. add_bot_url را به صاحب کانال بده؛ با باز کردنش ربات را در کانال یا گروه ادمین می‌کند. درخواست تا expires_in ثانیه معتبر است.
  3. بعد از ادمین شدن، ربات لینک دعوت اختصاصی می‌سازد و سفارش ممبر با همان لینک خودکار ثبت و هزینه کسر می‌شود.
  4. وضعیت را با GET /services/members/invite/{token} بگیر: pending → done همراه شیء order.
  • ورود و خروج اعضا فقط از همین لینک اختصاصی شمرده می‌شود (آمار اعضا).
  • در محیط test ربات ادمین نمی‌شود و پاسخ فقط شکل خروجی را نشان می‌دهد؛ برای آزمون کامل سفارش ممبر از POST /services/orders استفاده کن.
  • با max_price سقف مبلغ بگذار تا اگر قیمت بین نمایش و ثبت بالا رفت، سفارشی با مبلغ بیشتر ثبت نشود.

خطاها

HTTPcodeکی
400invalid_requestسطح ضمانت/تنظیم تدریجی نامعتبر
409unavailableبرای این تعداد سرویسی موجود نیست
402insufficient_fundsموجودی کیف پول API (یا موجودی آزمایشی) کافی نیست
403insufficient_scopeکلید scope orders:write را ندارد
401invalid_api_key / missing_api_key / api_key_revoked / api_key_expiredکلید نیامده، نامعتبر، باطل یا منقضی است
429rate_limit_exceededسقف درخواست در دقیقه پر شده؛ بعد از Retry-After ثانیه دوباره بفرست

محدودیت نرخ

پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای X-RateLimit-* برمی‌گردد — جزئیات.