می‌خوای الوکام رو با سیستم خودت هماهنگ کنی؟ اینجا راهشه.

برای استفاده از وب‌سرویس‌های الوکام، ابتدا در سامانه الوکام ثبت‌نام کرده و سرویس مورد نظر خود را خریداری کنید. سپس برای شروع کار با API الوکام، لطفاً از مستند راهنما در این لینک استفاده نمایید.

برای ثبت‌نام کاربر در رویداد و دریافت لینک مستقیم ورود، باید شناسه رویداد(eventId) را در آدرس درخواست و مشخصات کاربر را در بدنه(Body) ارسال کنید.

آدرس: /api/v1/agents/events/{event}/enroll-user-with-token

هدر(Header): توکن احراز هویت(Authorization) الزامی است.

پارامترهای بدنه(Body):

name: نام کاربر

surname: نام خانوادگی

username: نام کاربری (باید یکتا باشد)

role: نقش کاربر (یکی از سه مقدار assistant, teacher, participant )

پاسخ این سرویس شامل توکن اختصاصی کاربر و لینک ورود به رویداد است.

اگر کاربری با این مشخصات از قبل در رویداد عضو باشد، خطایی رخ نمی‌دهد؛ سیستم صرفاً لینک ورود و توکن او را به‌روزرسانی کرده و در پاسخ برمی‌گرداند و تعداد کاربران حاضر تغییر نمی‌کند.

تعیین نقش کاربر از طریق پارامتر role در بدنه(Body) درخواست انجام می‌شود.

آدرس: /api/v1/agents/events/{event}/enroll-user-with-token

هنگام ارسال اطلاعات کاربر، باید یکی از سه مقدار زیر را برای این فیلد انتخاب کنید:

participant: شرکت‌کننده عادی

teacher: مدیر رویداد

assistant: دستیار رویداد

علاوه بر نقش، ارسال موارد زیر نیز الزامی است:

username: نام کاربری (باید یکتا باشد)

name: نام 

surname: نام خانوادگی

ثبت‌نام گروهی کاربران طی یک فرآیند دو مرحله‌ای انجام می‌شود:

مرحله ۱: بارگذاری فایل

ابتدا فایل حاوی اطلاعات کاربران را به آدرس زیر POST کنید.

آدرس: /api/v1/agents/users/import-by-excel

ورودی(Body): پارامتر file (فرمت‌های مجاز: xlsx, xls, csv)

مرحله ۲: تأیید نهایی و برچسب‌گذاری

پس از بارگذاری موفق، برای ثبت نهایی کاربران در سیستم، باید درخواست زیر را ارسال کنید.

آدرس: /api/v1/agents/users/confirm-import-by-excel

ورودی(Body): می‌توانید آرایه‌ای از برچسب‌ها را با کلید label ارسال کنید تا به این گروه از کاربران اختصاص یابد.

مرحله ۱: دریافت لیست نوبت‌های حضور و غیاب

ابتدا باید ببینید در تاریخ مورد نظرتان، چند بار حضور و غیاب انجام شده است.

آدرس: /api/v1/agents/events/{event}/attendance

بدنه(Body): فیلد date(تاریخ برگزاری) الزامی است.

خروجی: لیستی از نوبت‌های حضور و غیاب به همراه ID هر کدام برمی‌گردد.

مرحله ۲: دریافت جزئیات حاضرین و غایبین

حال با استفاده از ID مرحله قبل، جزئیات را دریافت کنید.

آدرس: /api/v1/agents/events/{event}/attendance/detail

بدنه(Body): فیلد id(شناسه حضور و غیاب دریافتی از مرحله ۱).

خروجی: در پاسخ نهایی، دو آرایه مجزا دریافت می‌کنید:

presents: لیست حاضرین

absents: لیست غایبین

نکته: این سرویس‌ها صرفاً برای خواندن گزارش‌ها هستند. عملیات ثبت حضور و غیاب توسط مدرس در داخل محیط کلاس انجام می‌شود.

اگر نیاز به ریز اطلاعات ورود و خروج کاربران دارید(بدون وابستگی به ثبت حضور و غیاب توسط استاد)، می‌توانید از اندپوینت logs/traffics استفاده کنید. این سرویس تمامی داده‌های تردد را به صورت سیستمی بازمی‌گرداند.

آدرس: /api/v1/agents/logs/traffics

پارامترهای اجباری(Body):

برای مدیریت حجم داده‌ها، این سرویس از صفحه‌بندی(Pagination) پشتیبانی می‌کند:

take: تعداد رکوردهایی که می‌خواهید دریافت کنید(Limit).

skip: تعداد رکوردهایی که باید از ابتدای لیست نادیده گرفته شوند(Offset).

برای مشاهده جزئیات کامل پارامترها و ساختار پاسخ، لطفاً به مستندات رسمی الوکام مراجعه نمایید.

اولین قدم برای ارتباط با وب‌سرویس، احراز هویت است.

آدرس: /api/v1/auth/login

ورودی(Body): نام کاربری(username) و رمز عبور(password) پنل مدیریت الوکام.

توکن‌های دریافتی دارای عمر محدود(8 ساعت) هستند. بنابراین در پیاده‌سازی خود باید این سناریو را در نظر بگیرید: اگر در فراخوانی سایر سرویس‌ها با خطای عدم دسترسی(401 Unauthorized) مواجه شدید، باید مجدداً متد login را صدا زده و توکن جدید دریافت کنید.

برای مشاهده لیست تمام فایل‌ها (شامل فایل‌های بارگذاری شده توسط کاربر و فیلم‌های ضبط شده کلاس)، از اندپوینت زیر استفاده کنید:

آدرس: /api/v1/agents/agent-services/{agentservice}/files

(منظور از {agentservice} شناسه سرویس خریداری شده است.)

پارامترهای بدنه درخواست (Body):

پارامترهای اجباری (جهت صفحه‌بندی):

take: تعداد رکوردهایی که می‌خواهید دریافت کنید(Limit).

skip: تعداد رکوردهایی که باید از ابتدای لیست رد شوند(Offset).

پارامترهای اختیاری (جهت فیلتر کردن):

title: برای جستجو بر اساس نام فایل.

flag: اگر می‌خواهید فقط فیلم‌های ضبط شده را ببینید، مقدار این فیلد را برابر با رشته ‘record’ قرار دهید. در غیر این صورت، همه فایل‌ها نمایش داده می‌شوند.

برای ساخت رویداد جدید، از متد POST /api/v1/agents/events استفاده کنید و پارامترهای زیر را در بدنه (Body) درخواست خود ارسال کنید. این پارامترها به سه دسته تقسیم می‌شوند:

۱. پارامترهای اجباری (Required):

title: عنوان رویداد(رشته متنی).

slug: نام لاتین و یکتای رویداد(جهت استفاده در URL).

id_service_agent: شناسه سرویس خریداری شده که از ‌APIهای قبلی دریافت کرده‌اید.

status: وضعیت رویداد(مقدار 1 برای فعال و 0 برای غیرفعال).

start_by_admin: مدیریت شروع کلاس.

مقدار 1 (True): کاربران قبل از ورود مدیر اجازه ورود ندارند.

مقدار 0 (False): کاربران می‌توانند قبل از مدیر وارد شوند.

۲. تنظیمات پیشرفته (Optional):

time_duration: زمان برگزاری کلاس به دقیقه.(پس از این مدت، کلاس به صورت خودکار بسته شده و تخته/چت‌ها پاک می‌شوند).

link_back: لینک بازگشت.(آدرس URL سایت شما که کاربر پس از زدن دکمه خروج، به آن هدایت می‌شود).

۳. تنظیمات کاربران و مهمانان:

users: آرایه‌ای از کاربران اولیه شامل userid و role(نقش‌ها: participant, teacher, assistant).

access_guest: آیا ورود مهمان مجاز است؟ (Boolean).

code_guest: آرایه‌ای از رمزهای عبور مجاز برای مهمانان.

count_guest: حداکثر تعداد مهمان مجاز.

برای مشاهده لیست سرویس‌ها، باید پارامترهای زیر را در بدنه درخواست(Body) ارسال کنید:

api/v1/agents/agent-services :آدرس

take: تعداد رکوردهایی که می‌خواهید دریافت کنید (Limit).

skip: تعداد رکوردهایی که باید از ابتدای لیست رد شوند (Offset).

این پارامترها اجباری می‌باشند.

این قابلیت در زمان ساخت رویداد با متد /api/v1/agents/events تنظیم می‌شود.

شما باید پارامتر start_by_admin را در بدنه درخواست (Body) مقداردهی کنید:

مقدار 0: کاربران می‌توانند قبل از ورود مدیر وارد کلاس شوند.

مقدار 1: کاربران نمی‌توانند وارد شوند و باید منتظر ورود مدیر بمانند.

نکته: این فیلد از نوع Boolean است و ارسال آن اجباری می‌باشد.

هنگام ساخت رویداد با متد /api/v1/agents/events، می‌توانید با استفاده از پارامترهای زیر، دسترسی مهمان را کنترل کنید:

فعال‌سازی (اجباری برای مهمان):

guest_access: یک فیلد Boolean است. برای فعال کردن ورود مهمان، مقدار آن را true (یا 1) قرار دهید.

خیر، نیازی نیست کاربران از قبل در الوکام ثبت‌نام شده باشند. هنگامی که شما اطلاعات کاربران را در بدنه درخواست ارسال می‌کنید، سیستم به صورت خودکار بررسی می‌کند و اگر کاربری با آن مشخصات وجود نداشته باشد، همان لحظه برای او حساب کاربری ایجاد می‌شود؛ کاربران مهمان نیز اساساً نیازی به حساب کاربری ندارند و تنها با داشتن لینک رویداد می‌توانند وارد شوند.

این خطا نشان‌دهنده عدم عضویت کاربر در رویداد است. زمانی که شما برای دریافت لینک ورود(Sign-in) درخواست می‌دهید، سیستم بررسی می‌کند که آیا کاربر در لیست اعضای آن کلاس یا رویداد وجود دارد یا خیر. اگر کاربر تعریف نشده باشد، این خطا بازگردانده می‌شود.