نظرسنجی‌ها (Polls)

نظرسنجی‌ها (Polls) ابزاری برای جمع‌آوری نظرات کاربران در فضای کاری هستند. هر نظرسنجی دارای بازه زمانی مشخص، نوع رأی‌گیری و چندین گزینه است.

رأی دادن و حذف رأی تنها در بازه زمانی فعال نظرسنجی (بین start_at و end_at) امکان‌پذیر است.

نوع‌های مشترک (Common Types)

نام	توضیح
`Poll`	شیء اصلی نظرسنجی
`PollOption`	شیء گزینه نظرسنجی

فیلدهای Poll:

فیلد	نوع	توضیح
`id`	`number`	شناسه یکتای نظرسنجی
`created_at`	`string`	تاریخ و زمان ایجاد (فرمت ISO 8601)
`workspace_id`	`number`	شناسه فضای کاری مربوطه
`title`	`string`	عنوان نظرسنجی
`description`	`string \| null`	توضیحات نظرسنجی
`type`	`'single' \| 'multiple' \| 'ranking'`	نوع رأی‌گیری
`start_at`	`string`	تاریخ و زمان شروع (فرمت ISO 8601)
`end_at`	`string`	تاریخ و زمان پایان (فرمت ISO 8601)
`status`	`'not_started' \| 'active' \| 'expired'`	وضعیت جاری نظرسنجی
`total_votes`	`number`	تعداد کل رأی‌های ثبت شده
`is_voted`	`boolean`	آیا کاربر جاری رأی داده است؟
`options`	`[]PollOption`	آرایه گزینه‌های نظرسنجی
`author`	`User`	اطلاعات کاربر سازنده

فیلدهای PollOption:

فیلد	نوع	توضیح
`id`	`number`	شناسه یکتای گزینه
`title`	`string`	متن گزینه
`order`	`number`	ترتیب نمایش گزینه
`votes_count`	`number`	تعداد رأی‌های این گزینه
`percentage`	`number`	درصد رأی‌های این گزینه
`is_voted`	`boolean`	آیا کاربر جاری به این گزینه رأی داده است؟
`user_rank`	`number \| null`	رتبه‌ای که کاربر به این گزینه داده (فقط در نوع `ranking`)

فیلدهای User:

فیلد	نوع	توضیح
`id`	`string`	شناسه یکتای کاربر (UUID)
`created_at`	`string`	تاریخ و زمان ایجاد (فرمت ISO 8601)
`email`	`string`	ایمیل
`full_name`	`string`	نام کامل
`avatar_url`	`string \| null`	آدرس آواتار

مدیریت نظرسنجی‌ها (Polls)

دریافت لیست نظرسنجی‌ها

GET https://api.fidegah.ir/v1/polls

curl -X GET https://api.fidegah.ir/v1/polls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

پارامترهای Query (Query Parameters):

پارامتر	نوع	توضیح
`search`	`string`	جستجو بر اساس عنوان
`status`	`string`	فیلتر بر اساس وضعیت (`active`، `ended`، `not_started`) — با کاما جدا کنید
`sortBy`	`string`	فیلد مرتب‌سازی (پیش‌فرض `created_at`)
`sortOrder`	`'asc' \| 'desc'`	جهت مرتب‌سازی (پیش‌فرض `desc`)

خروجی درخواست:

فیلد	نوع	توضیح
`success`	`boolean`	وضعیت موفقیت‌آمیز بودن درخواست
`data`	`[]Poll`	آرایه شامل لیست نظرسنجی‌ها
`pagination`	`Pagination`	اطلاعات صفحه‌بندی (مشاهده جزئیات)

دریافت نظرسنجی با شناسه

GET https://api.fidegah.ir/v1/polls/:pollId

curl -X GET https://api.fidegah.ir/v1/polls/{pollId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

پارامترهای مسیر (Path Parameters):

پارامتر	نوع	توضیح
`pollId`	`number`	شناسه نظرسنجی مورد نظر

خروجی درخواست:

فیلد	نوع	توضیح
`success`	`boolean`	وضعیت موفقیت‌آمیز بودن درخواست
`data`	`Poll`	شیء نظرسنجی درخواستی

ایجاد نظرسنجی جدید

POST https://api.fidegah.ir/v1/polls

curl -X POST https://api.fidegah.ir/v1/polls \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "بهترین فریمورک فرانت‌اند؟",
    "type": "single",
    "start_at": "2026-06-10T00:00:00Z",
    "end_at": "2026-06-20T00:00:00Z",
    "options": [
      { "title": "React", "order": 0 },
      { "title": "Vue", "order": 1 }
    ]
  }'

بدنه درخواست (Request Body):

پارامتر	نوع	ضرورت	توضیح
`title`	`string`	الزامی	عنوان نظرسنجی (حداقل ۱، حداکثر ۲۵۵ کاراکتر)
`type`	`'single' \| 'multiple' \| 'ranking'`	الزامی	نوع رأی‌گیری
`start_at`	`string`	الزامی	تاریخ شروع (فرمت ISO 8601)
`end_at`	`string`	الزامی	تاریخ پایان (فرمت ISO 8601، باید بعد از `start_at` باشد)
`options`	`[]object`	الزامی	آرایه گزینه‌ها (حداقل ۲، حداکثر ۱۰ گزینه)
`description`	`string`	اختیاری	توضیحات نظرسنجی

ساختار هر گزینه در options:

پارامتر	نوع	ضرورت	توضیح
`title`	`string`	الزامی	متن گزینه (حداقل ۲، حداکثر ۲۰ کاراکتر)
`order`	`number`	اختیاری	ترتیب نمایش گزینه (پیش‌فرض بر اساس ترتیب ارسال)

خروجی درخواست:

فیلد	نوع	توضیح
`success`	`boolean`	وضعیت موفقیت‌آمیز بودن درخواست
`data`	`Poll`	شیء نظرسنجی ایجاد شده

حذف نظرسنجی

DELETE https://api.fidegah.ir/v1/polls/:pollId

curl -X DELETE https://api.fidegah.ir/v1/polls/{pollId} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

پارامترهای مسیر (Path Parameters):

پارامتر	نوع	توضیح
`pollId`	`number`	شناسه نظرسنجی مورد نظر

خروجی درخواست:

فیلد	نوع	توضیح
`success`	`boolean`	وضعیت موفقیت‌آمیز بودن درخواست
`message`	`string`	پیام نتیجه حذف

رأی‌گیری (Voting)

ثبت یا ویرایش رأی

POST https://api.fidegah.ir/v1/polls/:pollId/vote

در صورتی که کاربر قبلاً رأی داده باشد، رأی قبلی حذف و رأی جدید ثبت می‌شود.

curl -X POST https://api.fidegah.ir/v1/polls/{pollId}/vote \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "option_ids": [3, 1, 2]
  }'

پارامترهای مسیر (Path Parameters):

پارامتر	نوع	توضیح
`pollId`	`number`	شناسه نظرسنجی مورد نظر

بدنه درخواست (Request Body):

پارامتر	نوع	ضرورت	توضیح
`option_ids`	`[]number`	الزامی	آرایه شناسه گزینه‌های انتخابی. در نوع `ranking` ترتیب آرایه به عنوان رتبه در نظر گرفته می‌شود

خروجی درخواست:

فیلد	نوع	توضیح
`success`	`boolean`	وضعیت موفقیت‌آمیز بودن درخواست
`message`	`string`	پیام نتیجه ثبت رأی

حذف رأی

DELETE https://api.fidegah.ir/v1/polls/:pollId/vote

curl -X DELETE https://api.fidegah.ir/v1/polls/{pollId}/vote \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

پارامترهای مسیر (Path Parameters):

پارامتر	نوع	توضیح
`pollId`	`number`	شناسه نظرسنجی مورد نظر

خروجی درخواست:

فیلد	نوع	توضیح
`success`	`boolean`	وضعیت موفقیت‌آمیز بودن درخواست
`message`	`string`	پیام نتیجه حذف رأی

نظرسنجی‌ها (Polls)

On this page