الوکام را به نرم‌افزار خود متصل کنید
با وب‌سرویس (API) الوکام، مدیریت رویدادها، کاربران و گزارش‌ها را به سیستم خود متصل کنید و همه فرآیندها را به‌صورت خودکار کنترل کنید.
چرا الوکام انتخابی مطمئن برای کلاس آنلاین است؟
ایجاد و مدیریت رویدادها
ایجاد، ویرایش و حذف کلاس‌ها و وبینارها.
ورود خودکار
ساخت لینک‌های ورود مستقیم و امن برای هر کاربر بدون نیاز به رمز عبور.
کنترل دسترسی و نقش‌ها
تعیین نقش دقیق هر کاربر در رویداد (شامل شرکت‌کننده، دستیار و مدیر).
یکپارچه‌سازی کامل
اتصال آسان به CRM، LMS و سایر سامانه‌های داخلی شما.
گزارش‌گیری
استخراج گزارش‌های حضور و غیاب و سایر داده‌های مربوط به رویداد.
مدیریت کاربران
ثبت‌نام، ویرایش و حذف کاربران و تخصیص آن‌ها به رویدادهای مختلف.
سوالات متداول
چگونه می‌توانم کار با API الوکام را شروع کنم؟
برای استفاده از وب‌سرویس‌های الوکام، ابتدا در سامانه الوکام ثبت‌نام کرده و سرویس مورد نظر خود را خریداری کنید. سپس برای شروع کار با 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) پنل مدیریت الوکام.
توکن‌های دریافتی دارای عمر محدود(۸ ساعت) هستند. بنابراین در پیاده‌سازی خود باید این سناریو را در نظر بگیرید: اگر در فراخوانی سایر سرویس‌ها با خطای عدم دسترسی(۴۰۱ 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: وضعیت رویداد(مقدار ۱ برای فعال و ۰ برای غیرفعال).
start_by_admin: مدیریت شروع کلاس.
مقدار ۱ (True): کاربران قبل از ورود مدیر اجازه ورود ندارند.
مقدار ۰ (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) مقداردهی کنید:
مقدار ۰: کاربران می‌توانند قبل از ورود مدیر وارد کلاس شوند.
مقدار ۱: کاربران نمی‌توانند وارد شوند و باید منتظر ورود مدیر بمانند.
نکته: این فیلد از نوع Boolean است و ارسال آن اجباری می‌باشد.
برای ورود مهمان به رویداد از چه پارامتری استفاده می‌شود؟
هنگام ساخت رویداد با متد /api/v1/agents/events، می‌توانید با استفاده از پارامترهای زیر، دسترسی مهمان را کنترل کنید:
فعال‌سازی (اجباری برای مهمان):
guest_access: یک فیلد Boolean است. برای فعال کردن ورود مهمان، مقدار آن را true (یا ۱) قرار دهید.
برای ایجاد رویداد از طریق API، آیا کاربران (ادمین و مهمان) باید از قبل در الوکام ثبت‌نام شده باشند؟
خیر، نیازی نیست کاربران از قبل در الوکام ثبت‌نام شده باشند. هنگامی که شما اطلاعات کاربران را در بدنه درخواست ارسال می‌کنید، سیستم به صورت خودکار بررسی می‌کند و اگر کاربری با آن مشخصات وجود نداشته باشد، همان لحظه برای او حساب کاربری ایجاد می‌شود؛ کاربران مهمان نیز اساساً نیازی به حساب کاربری ندارند و تنها با داشتن لینک رویداد می‌توانند وارد شوند.
علت دریافت خطای ۴۰۳ با پیام "backend_event_not_allowed" در درخواست ورود (Sign-in) چیست؟
این خطا نشان‌دهنده عدم عضویت کاربر در رویداد است. زمانی که شما برای دریافت لینک ورود(Sign-in) درخواست می‌دهید، سیستم بررسی می‌کند که آیا کاربر در لیست اعضای آن کلاس یا رویداد وجود دارد یا خیر. اگر کاربر تعریف نشده باشد، این خطا بازگردانده می‌شود.
برای انتخاب بهترین سرویس، با ما مشورت کنید.
نیاز شما را بررسی می‌کنیم تا مناسب‌ترین راهکار الوکام را انتخاب کنید.
