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

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

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

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

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

فیلدهای Poll:

فیلد	نوع	توضیح
`id`	`string`	شناسه یکتای نظرسنجی (UUID)
`createdAt`	`string`	تاریخ و زمان ایجاد (فرمت ISO 8601)
`workspaceId`	`string`	شناسه فضای کاری مربوطه (UUID)
`userId`	`string`	شناسه کاربر ایجادکننده (UUID)
`title`	`string`	عنوان نظرسنجی
`description`	`string \| null`	توضیحات نظرسنجی
`type`	`'single' \| 'multiple' \| 'ranked'`	نوع رأی‌گیری
`startAt`	`string`	تاریخ و زمان شروع (فرمت ISO 8601)
`endAt`	`string`	تاریخ و زمان پایان (فرمت ISO 8601)
`status`	`'not_started' \| 'active' \| 'expired'`	وضعیت جاری نظرسنجی (محاسبه‌شده)
`totalVotes`	`number`	تعداد کل رأی‌های ثبت شده
`isVoted`	`boolean`	آیا کاربر جاری رأی داده است؟
`options`	`[]PollOption`	آرایه گزینه‌های نظرسنجی

فیلدهای PollOption:

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

مدیریت نظرسنجی‌ها (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`	`'not_started' \| 'active' \| 'expired'`	فیلتر بر اساس وضعیت نظرسنجی

نتایج بر اساس جدیدترین تاریخ ایجاد مرتب می‌شوند. صفحه‌بندی نتایج طبق ساختار عمومی صفحه‌بندی API پشتیبانی می‌شود (مشاهده جزئیات).

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

فیلد	نوع	توضیح
`data`	`[]Poll`	آرایه شامل لیست نظرسنجی‌ها
`pagination`	`Pagination`	اطلاعات صفحه‌بندی

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

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

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

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

پارامتر	نوع	توضیح
`id`	`string`	شناسه نظرسنجی مورد نظر (UUID)

خروجی درخواست: شیء 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",
    "startAt": "2026-06-10T00:00:00Z",
    "endAt": "2026-06-20T00:00:00Z",
    "options": [
      { "title": "React", "order": 0 },
      { "title": "Vue", "order": 1 }
    ]
  }'

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

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

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

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

خروجی درخواست: شیء Poll ایجادشده.

حذف نظرسنجی

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

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

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

پارامتر	نوع	توضیح
`id`	`string`	شناسه نظرسنجی مورد نظر (UUID)

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

فیلد	نوع	توضیح
`message`	`string`	پیام نتیجه حذف

رأی‌گیری (Voting)

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

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

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

curl -X POST https://api.fidegah.ir/v1/polls/{id}/vote \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "optionIds": ["c1a2...", "c3b4...", "c5d6..."]
  }'

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

پارامتر	نوع	توضیح
`id`	`string`	شناسه نظرسنجی مورد نظر (UUID)

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

پارامتر	نوع	ضرورت	توضیح
`optionIds`	`[]string`	الزامی	آرایه شناسه گزینه‌های انتخابی (UUID، حداقل ۱ عدد). در نوع `ranked` ترتیب آرایه به عنوان رتبه در نظر گرفته می‌شود؛ در نوع `single` باید دقیقاً یک شناسه ارسال شود

فقط زمانی که نظرسنجی در بازه‌ی زمانی فعال (بین startAt و endAt) باشد، ثبت رأی امکان‌پذیر است.

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

فیلد	نوع	توضیح
`message`	`string`	پیام نتیجه ثبت رأی

حذف رأی

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

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

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

پارامتر	نوع	توضیح
`id`	`string`	شناسه نظرسنجی مورد نظر (UUID)

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

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

فیلد	نوع	توضیح
`message`	`string`	پیام نتیجه حذف رأی

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

On this page