---
title: ممبر با ادمین کردن ربات — POST /api/v1/services/members/invite | Stard API
url: https://stard-market.ir/docs/reference/members-invite
markdown: https://stard-market.ir/docs/reference/members-invite.md
language: fa
updated: 2026-11-18
description: به‌جای فرستادن لینک، ربات Stard را در کانال/گروه ادمین کن (با مجوز «دعوت کاربران»): پاسخ add_bot_url و token می‌دهد. بعد از ادمین شدن، ربات یک لینک دعوت اخ
---

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

`POST /api/v1/services/members/invite`

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

## درخواست

| نام | محل | نوع |  | توضیح |
|---|---|---|---|---|
| `Authorization` | header | `string` | الزامی | `Bearer sk_live_…` یا `Bearer sk_test_…` |
| `Idempotency-Key` | header | `string` | اختیاری | کلید یکتا |

### بدنه (JSON)

| فیلد | نوع |  | توضیح |
|---|---|---|---|
| `service` | `string` | اختیاری | `members` (پیش‌فرض) یا `premium_members` |
| `kind` | `string` | الزامی | `channel` یا `group` |
| `quantity` | `integer` | الزامی | تعداد ممبر |
| `option` | `string` | اختیاری | سطح ضمانت |
| `drip_runs` | `integer` | اختیاری | ارسال تدریجی |
| `drip_interval` | `integer` | اختیاری | فاصله به دقیقه |
| `max_price` | `integer` | اختیاری | سقف مبلغ |
| `pay_currency` | `string` | اختیاری | TON یا IRT |
| `metadata` | `object` | اختیاری | داده‌ی دلخواه |

## نمونه

```bash
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"}'
```

```javascript
const res = await fetch("https://stard-market.ir/api/v1/services/members/invite", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "mem-1001",
  },
  body: JSON.stringify({
    "kind": "channel",
    "quantity": 1000,
    "option": "g30"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data);
```

```typescript
type StardError = { error: { type: string; code: string; message: string; param: string | null; request_id: string } };

const res = await fetch("https://stard-market.ir/api/v1/services/members/invite", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STARD_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "mem-1001",
  },
  body: JSON.stringify({
    "kind": "channel",
    "quantity": 1000,
    "option": "g30"
  }),
});
if (!res.ok) {
  const { error } = (await res.json()) as StardError;
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}
const data: Record<string, unknown> = await res.json();
```

```python
import os
import requests

r = requests.post(
    "https://stard-market.ir/api/v1/services/members/invite",
    headers={
    "Authorization": f"Bearer {os.environ['STARD_API_KEY']}",
    "Idempotency-Key": "mem-1001",
    },
    json={
        "kind": "channel",
        "quantity": 1000,
        "option": "g30"
    },
    timeout=20,
)
data = r.json()
if r.status_code >= 400:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)
```

```php
<?php
$ch = curl_init("https://stard-market.ir/api/v1/services/members/invite");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("STARD_API_KEY"),
    "Content-Type: application/json",
    "Idempotency-Key: mem-1001",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "kind" => "channel",
    "quantity" => 1000,
    "option" => "g30"
  ]),
  CURLOPT_TIMEOUT => 20,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($status >= 400) {
  throw new RuntimeException($data["error"]["code"] . ": " . $data["error"]["message"]);
}
print_r($data);
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"kind": "channel", "quantity": 1000, "option": "g30"}`)
	req, _ := http.NewRequest("POST", "https://stard-market.ir/api/v1/services/members/invite", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("STARD_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "mem-1001")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode, string(b))
}
```

**پاسخ — 201**

```json
{
  "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 استفاده کن."
}
```

**هدرهای پاسخ**

```http
content-type: application/json
```

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

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

1. این اندپوینت را صدا بزن؛ پاسخ `add_bot_url` (لینک ادمین کردن ربات Stard با مجوز «دعوت کاربران») و `token` می‌دهد.
2. `add_bot_url` را به صاحب کانال بده؛ با باز کردنش ربات را در کانال یا گروه ادمین می‌کند. درخواست تا `expires_in` ثانیه معتبر است.
3. بعد از ادمین شدن، ربات لینک دعوت اختصاصی می‌سازد و سفارش ممبر با همان لینک خودکار ثبت و هزینه کسر می‌شود.
4. وضعیت را با [`GET /services/members/invite/{token}`](https://stard-market.ir/docs/reference/members-invite-get) بگیر: `pending` → `done` همراه شیء `order`.

- ورود و خروج اعضا فقط از همین لینک اختصاصی شمرده می‌شود ([آمار اعضا](https://stard-market.ir/docs/reference/service-order-members)).
- در محیط test ربات ادمین نمی‌شود و پاسخ فقط شکل خروجی را نشان می‌دهد؛ برای آزمون کامل سفارش ممبر از [`POST /services/orders`](https://stard-market.ir/docs/reference/service-order) استفاده کن.
- با `max_price` سقف مبلغ بگذار تا اگر قیمت بین نمایش و ثبت بالا رفت، سفارشی با مبلغ بیشتر ثبت نشود.

## خطاها

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

## محدودیت نرخ

پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای `X-RateLimit-*` برمی‌گردد — [جزئیات](https://stard-market.ir/docs/rate-limits).
