# مرجع API مشترکان

Source: https://instatus.com/help/fa/api/subscribers

## دریافت مشترکان

**نقطه پایانی:**

```bash
GET /v2/:page_id/subscribers?page=:page&per_page=:per_page&search=:search_query&status=:status
```

- شماره صفحه پیش‌فرض ۱ است.
- مقدار پیش‌فرض per_page برابر ۵۰ و بیشینه ۱۰۰ آیتم در هر صفحه است.
- پرس‌وجوی جست‌وجوی اختیاری برای فیلتر کردن مشترکان بر اساس نشانی ایمیل یا شماره تلفن به کار می‌رود.
- پارامتر اختیاری `status` مشترکان را بر اساس وضعیت اشتراکشان فیلتر می‌کند. از `status=confirmed` استفاده کنید تا کسانی که هنوز تأیید نکرده‌اند کنار گذاشته شوند.

| مقدار | مشترکان برگردانده‌شده |
| --- | --- |
| `confirmed` | مشترکان تأییدشده که اعلان‌ها را دریافت می‌کنند. |
| `unconfirmed` | مشترکان تصویب‌شده‌ای که هنوز اشتراک خود را تأیید نکرده‌اند. |
| `unapproved` | مشترکانی که در انتظار تصویب هستند، مانند فهرست‌های واردشده. |

**نمونه پاسخ**

```json
[
  {
    "id": "cm1111x6ofgsd5666mzxcw978qh",
    "email": "ali@instatus.com",
    "phone": null,
    "webhook": null,
    "webhookEmail": null,
    "confirmed": false,
    "approved": true,
    "all": true,
    "components": []
  },
  {
    "id": "cm1111x6ofgsd5666mzxcw978qh",
    "email": null,
    "phone": "5417543010",
    "webhook": null,
    "webhookEmail": null,
    "confirmed": false,
    "approved": true,
    "all": true,
    "components": []
  }
]
```

## افزودن یک مشترک

**نقطه پایانی:**

```bash
POST /v1/:page_id/subscribers
```

وقتی کسی مشترک می‌شود، رفتار تأیید از تنظیم `subscriberConfirmationMode` صفحه پیروی می‌کند. برای بازنویسی این رفتار برای یک مشترک خاص، از `autoConfirm` در این نقطه پایانی استفاده کنید.

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

```json
{
  "email": "sarah@instatus.com",
  "all": true,
  "autoConfirm": false
}
```

- `autoConfirm` — اختیاری. وقتی `true` باشد، مشترک را بی‌درنگ و بدون فرستادن ایمیل تأیید یا خوش‌آمد اضافه می‌کند، فارغ از تنظیم صفحه. فقط Pro.

**نمونه پاسخ**

```json
{
  "id": "cm1111x6ofgsd5666mzxcw978df",
  "name": null,
  "email": "sarahs@instatus.com",
  "phone": null,
  "confirmed": false,
  "all": true,
  "createdAt": "2024-10-01T03:48:41.474Z",
  "updatedAt": "2024-10-01T03:48:41.474Z",
  "siteId": "cm1111x6ofgsd5666mzxcw978qh",
  "unsubscribeToken": "e3b51de6-1234-4664-zxyv-1679gg524260",
  "webhook": null,
  "webhookEmail": null,
  "discord": null,
  "discordTeam": null,
  "slack": null,
  "slackTeam": null,
  "language": "en",
  "company": null,
  "microsoftTeamsWebhook": null,
  "googleChatWebhook": null,
  "googleChatSpace": null,
  "failedAttempts": 0,
  "approved": true,
  "importedFrom": null,
  "hideUnsubLink": false,
  "webhookIncidentBody": null,
  "webhookMaintenanceBody": null,
  "webhookComponentBody": null,
  "webhookHttpMethod": "POST",
  "webhookHeaders": null,
  "site": {
    "id": "cm1111x6ofgsd5666mzxcw978qh"
  }
}
```

### اشتراک در اجزای مشخص

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

```json
{
  "email": "adam@instatus.com",
  "all": false,
  "components": ["cl2xv23rl0119e7jlk2mweepd"],
  "autoConfirm": false
}
```

**نمونه پاسخ**

```json
{
  "id": "cl09gt11151422bjluflghewx",
  "email": "adam@instatus.com",
  "site": {
    "id": "ckg8a112344s5v86wrn",
    "name": "Test",
    "logoUrl": null,
    "subdomain": "test",
    "publicEmail": null,
    "language": "en"
  }
}
```

## افزودن چند مشترک

**نقطه پایانی:**

```bash
POST /v1/:page_id/subscribers/bulk
```

این نقطه پایانی به شما امکان می‌دهد چند مشترک را در یک درخواست بسازید.

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

```json
{
  "subscribers": [
    {
      "email": "sarah@instatus.com",
      "all": true
    },
    {
      "email": "john@instatus.com",
      "components": ["cl2xv23rl0119e7jlk2mweepd"]
    },
    {
      "name": "Jane Doe",
      "phone": "5417543010",
      "all": true
    }
  ],
  "autoConfirm": false
}
```

- `autoConfirm` روی همه مشترکان دسته اعمال می‌شود. فقط Pro.

**نمونه پاسخ**

```json
{
  "success": true,
  "created": 3,
  "failed": 0,
  "results": {
    "created": [
      {
        "id": "cm1111x6ofgsd5666mzxcw978df",
        "email": "sarah@instatus.com",
        "phone": null,
        "confirmed": false,
        "all": true,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm2222x6ofgsd5666mzxcw978df",
        "email": "john@instatus.com",
        "phone": null,
        "confirmed": false,
        "all": false,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm3333x6ofgsd5666mzxcw978df",
        "email": null,
        "phone": "5417543010",
        "name": "Jane Doe",
        "confirmed": false,
        "all": true,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      }
    ],
    "failed": []
  }
}
```

**پاسخ وقتی ساخت برخی مشترکان ناموفق باشد**

اگر ساخت برخی مشترکان ناموفق باشد (مثلاً ایمیل تکراری یا قالب نادرست)، پاسخ شامل جزئیات ناکامی‌ها خواهد بود:

```json
{
  "success": false,
  "created": 2,
  "failed": 1,
  "results": {
    "created": [
      {
        "id": "cm1111x6ofgsd5666mzxcw978df",
        "email": "sarah@instatus.com",
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm2222x6ofgsd5666mzxcw978df",
        "email": "john@instatus.com",
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      }
    ],
    "failed": [
      {
        "index": 2,
        "subscriber": {
          "email": "duplicate@instatus.com",
          "all": true
        },
        "error": {
          "code": "creation_failed",
          "message": "Subscriber with this email already exists"
        }
      }
    ]
  }
}
```

**نکته‌ها:**

- حداکثر ۱۰۰ مشترک در هر درخواست
- هر شیء مشترک می‌تواند همان فیلدهای نقطه پایانی تک‌مشترکی را داشته باشد
- موفقیت جزئی پشتیبانی می‌شود — مشترکانی که با موفقیت ساخته شده‌اند برگردانده می‌شوند حتی اگر برخی ناموفق باشند

## رفتار تأیید

صفحه‌های وضعیت نحوه برخورد با مشترکان جدید را از طریق `subscriberConfirmationMode` در نقطه پایانی [به‌روزرسانی یک صفحه وضعیت](https://instatus.com/help/fa/api/status-pages) کنترل می‌کنند:

| مقدار | رفتار |
| --- | --- |
| `REQUIRED` | مشترکان باید پیش از دریافت به‌روزرسانی‌ها با ایمیل تأیید کنند. پیش‌فرض. |
| `WELCOME` | مشترکان بی‌درنگ اضافه می‌شوند و ایمیل خوش‌آمد دریافت می‌کنند. فقط Pro. |
| `NONE` | مشترکان بی‌درنگ و بدون هیچ ایمیلی اضافه می‌شوند. فقط Pro. |

پارامتر `autoConfirm` در نقاط پایانی ساخت، تنظیم صفحه را برای آن درخواست بازنویسی می‌کند و مانند `NONE` رفتار می‌کند.

## حذف یک مشترک

**نقطه پایانی:**

```bash
DELETE /v1/:page_id/subscribers/:subscriber_id
```

**نمونه پاسخ**

```json
{
  "id": "cm1zvzm3434dlp9255d6jgy8",
  "name": null,
  "email": "sarah@instatus.com",
  "phone": null,
  "webhook": null,
  "webhookEmail": null,
  "discord": null,
  "microsoftTeamsWebhook": null,
  "company": null,
  "site": {
    "id": "cm180slpo000g9343478qh"
  }
}
```