واجهة برمجة التطبيقات للمطورين

نظرة عامة

واجهة برمجة التطبيقات للمطورين هي واجهة REST تحت /api/v1. جميع الطلبات والردود بصيغة JSON. العقد الكامل والتفاعلي موجود في مرجع API؛ تنقلك هذه الصفحة إلى أول استدعاء ناجح لك.

المصادقة

صادِق باستخدام مفتاح API لمساحة العمل يُرسل كرمز Bearer. أنشئ واحدًا في Studio → API للمطورين (الخطط المدفوعة). يُعرض السر مرة واحدة فقط - احفظه في مكان آمن؛ إذا فقدته، فألغِ المفتاح وأنشئ مفتاحًا جديدًا.

Authorization: Bearer $POLLSLIVE_KEY

تعمل المفاتيح بصلاحية المسؤول داخل مساحة العمل الخاصة بها. لا تكشف أبدًا عن مفتاح في كود من جانب العميل. استدعِ API من خادمك.

You can also authenticate using an OAuth 2.0 Client Credentials access token for machine-to-machine integrations.

البدء السريع

أنشئ استطلاعًا، وانشره، ثم اقرأ النتائج:

curl -X POST https://pollslive.com/api/v1/polls \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Lunch vote",
    "content": {
      "questions": [{
        "id": "q1", "kind": "multiple_choice", "text": "Where to?",
        "type": "single",
        "options": [
          { "id": "a", "label": "Tacos" },
          { "id": "b", "label": "Sushi" }
        ]
      }]
    }
  }'

curl -X PATCH https://pollslive.com/api/v1/polls/POLL_ID \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "publish": true }'

curl https://pollslive.com/api/v1/polls/POLL_ID/results \
  -H "Authorization: Bearer $POLLSLIVE_KEY"

أنواع الأسئلة

الاستطلاع هو مجموعة من الشرائح المُحدّدة الأنواع. اضبط kind على كل شريحة. يمكن إنشاء كل نوع من هذه الأنواع عبر API:

• multiple_choice: type (single/multiple)، options[]. قابل للتصويت بشكل غير متزامن.
• quiz: options[], correctOptionIds[], timeLimitSec, points, speedBonus.
• quiz_typed: acceptedAnswers[], timeLimitSec, points, speedBonus (في الجلسات المباشرة فقط؛ 1-10 إجابات مقبولة، حتى 60 حرفًا لكل منها، تُطابق دون اعتبار لحالة الأحرف أو المسافات الزائدة؛ يكتب اللاعبون حتى 40 حرفًا).
• quiz_order: items[], timeLimitSec, points, speedBonus (في الجلسات المباشرة فقط؛ 3-6 عناصر لكل منها id وlabel، محفوظة بالترتيب الصحيح؛ يراها اللاعبون مخلوطة ولا تُمنح النقاط إلا للترتيب التام).
• scale: min, max, minLabel, maxLabel, statements[].
• ranking: options[] (يرتّبها المُجيبون).
• open_ended: maxLength, render (قائمة/سحابة).
• qa: moderated, allowUpvotes.
• estimation: cards[], deckPreset (Planning Poker؛ في الجلسات المباشرة فقط، تبقى الأصوات مخفية حتى تكشفها).
• brainstorm: maxLength, moderated, groups[], votesPerPerson (في الجلسات المباشرة فقط؛ يصوّت الجمهور على المجموعات التي تبنيها من الأفكار).
• content - للعرض فقط.

{
  "questions": [
    {
      "id": "s1", "kind": "scale", "text": "How likely are you to recommend us?",
      "min": 0, "max": 10, "minLabel": "Not likely", "maxLabel": "Very likely"
    },
    {
      "id": "q2", "kind": "quiz", "text": "Capital of France?",
      "options": [{ "id": "a", "label": "Paris" }, { "id": "b", "label": "Rome" }],
      "correctOptionIds": ["a"], "timeLimitSec": 20, "points": 100, "speedBonus": true
    },
    {
      "id": "q3", "kind": "ranking", "text": "Rank these features by importance",
      "options": [
        { "id": "r1", "label": "Speed" },
        { "id": "r2", "label": "Reliability" },
        { "id": "r3", "label": "Price" }
      ]
    },
    {
      "id": "q4", "kind": "open_ended", "text": "Any other feedback?",
      "maxLength": 300, "render": "list"
    },
    {
      "id": "q5", "kind": "qa", "text": "Questions for the presenter",
      "moderated": true, "allowUpvotes": true
    }
  ]
}

الصور والفيديو والروابط

يمكن لأي شريحة وأي خيار أن يحمل media. ارفع أو مرّر عنوان URL إلى POST /media وضمّن الكائن المُعاد. الصور تُنزّل، ويُعاد ترميزها إلى WebP، ويُعاد استضافتها (حمولات أصغر). YouTube وفيديوهات روابط الويب تحتفظ بعنوان URL الخاص بها وتُعرض من جانب العميل، لذا لن تدفع أبدًا مقابل استضافة الفيديو. يمكنك أيضًا تمرير media: { type, url } مضمّنًا على شريحة/خيار وتقوم API بحلّه عند الحفظ.

# 1) Ingest an image (returns { data: { type, url, storedUrl, width, height } })
curl -X POST https://pollslive.com/api/v1/media \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/cat.jpg" }'

# 2) Embed the storedUrl on a slide option
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://pollslive.com/media/abc.webp" } }

# Or pass the original URL inline - the API resolves it on save:
{ "id": "a", "label": "Option A", "media": { "type": "image", "url": "https://example.com/cat.jpg" } }

# YouTube on a question slide
{ "id": "q1", "kind": "content", "text": "Watch this first",
  "media": { "type": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ" } }

الردود والنتائج

multiple_choice تتلقى الشرائح الأصوات عبر POST /polls/{id}/votes. يتلقى كل نوع آخر ردودًا غير متزامنة عبر POST /polls/{id}/responses - أرسل الحقل المطابق للشريحة (scaleValue, rankingOrder, text, أو optionIds). اقرأ التجميعات لكل شريحة من GET /polls/{id}/results.

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "s1", "scaleValue": 9 }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voterId": "user-123",
    "slideId": "q3",
    "rankingOrder": ["r2", "r1", "r3"]
  }'

curl -X POST https://pollslive.com/api/v1/polls/POLL_ID/responses \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voterId": "user-123", "slideId": "q4", "text": "Great product!" }'

الجلسات المباشرة والتحكم في الجلسة

A live session lets you drive a poll in real time in front of an audience. Create a session via the API, share the PIN or QR code, then control pacing and results visibility with the control endpoint.

curl -X POST https://pollslive.com/api/v1/sessions \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pollId": "POLL_ID" }'
# Response includes: id, pin, status, currentSlideIndex, hostToken (once)

curl -X POST https://pollslive.com/api/v1/sessions/SESSION_ID/control \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "next" }'

جميع إجراءات التحكم في الجلسة

أرسل طلب POST إلى /api/v1/sessions/{id}/control (Bearer) مع إحدى سلاسل action التالية.

{ "action": "goto", "slideIndex": 2 }

تصدير النتائج

نزّل النتائج المجمّعة كملف CSV بترميز UTF-8 وفق RFC 4180، أو كتقرير PDF عبر ?format=pdf. يحتوي كل صف على رقم الشريحة ونص السؤال والنوع وتسمية الإجابة والعدد أو القيمة. متوافق مع Excel وGoogle Sheets وأي أداة CSV. في الخطط المدفوعة فقط.

curl https://pollslive.com/api/v1/polls/POLL_ID/export \
  -H "Authorization: Bearer $POLLSLIVE_KEY" \
  --output results.csv

# CSV structure:
# Slide, Question, Type, Answer / Label, Count / Value
# 1, "Where to?", multiple_choice, Tacos, 12
# 1, "Where to?", multiple_choice, Sushi, 8
# 2, "Rate your experience", scale, Average, 8.50
# 2, "Rate your experience", scale, Rating 10, 5

نقاط النهاية

• الاستطلاعات: GET/POST /polls, GET/PATCH/DELETE /polls/{id}
• النتائج: GET /polls/{id}/results, GET/POST /polls/{id}/responses
• الأصوات: GET/POST /polls/{id}/votes
• الوسائط: POST /media
• الجلسات: POST /sessions, GET /sessions/{id}, POST /sessions/{id}/control
• التصدير: GET /polls/{id}/export

اطّلع على أشكال الطلب/الرد وجرّب الاستدعاءات مباشرة في مرجع API.

الأخطاء وحدود المعدل

تستخدم الأخطاء غلافًا ثابتًا:

{ "error": { "code": "not_found", "message": "Poll not found." } }

الرموز الشائعة: 401 مفتاح غير صالح/مفقود، 402 يلزم ترقية الخطة، 404 غير موجود، 409 تعارض (مثل التصويت مسبقًا، أو إغلاق الاستطلاع)، 422 فشل التحقق، 429 تجاوز حد المعدل. تسمح,

حدود المعدل

تسمح الواجهة بـ 120 طلبًا في الدقيقة لكل مفتاح على جميع نقاط النهاية. ولاستيعاب الوسائط (POST /media) حد منفصل قدره 30 طلبًا في الدقيقة. ويُعاد HTTP 429 عند تجاوز أي حد. انتظر ثم أعد المحاولة.

OAuth2 (من Pro فما فوق)

يمكن لأي مساحة عمل مدفوعة (Pro فما فوق) استخدام بيانات اعتماد عميل OAuth2 بدلاً من المفاتيح الثابتة. أنشئ العملاء في Studio، ويشرح دليل OAuth التدفق الكامل.

تغييرات واجهة برمجة التطبيقات للمطورين

تغييرات واجهة برمجة التطبيقات للمطورين، الأحدث أولًا. تغييرات المنتج موجودة في سجل التغييرات.

سياسة إصدارات API

تُصدَّر واجهة REST على مستوى الرابط (/api/v1/). ولا تُطرَح التغييرات الجذرية إلا مع بادئة إصدار جديدة وبمهلة تشغيل متوازٍ لا تقل عن 90 يومًا. أما التغييرات الإضافية (حقول جديدة، أو نقاط نهاية جديدة، أو أحداث Webhook جديدة) فلا تكسر شيئًا ويمكن إطلاقها في أي وقت.