بکاند آماده آکادمی آنلاین
دوره، سرفصل و درس، فروش دوره با کد تخفیف و پرداخت زرینپال، محتوای قفلشده برای ثبتنامکردهها، پیشرفت، آزمون با تصحیح سمت سرور، نظر دانشجو و گواهی با کد قابلتأیید — بکاند کامل یک آکادمی، بیآنکه چیزی به آن اضافه کنید.
۱۵ روز اول رایگانبا پلنکاپوچینو
اعتبار هدیهٔ ثبتنام هزینهاش را میدهد؛ لازم نیست حتی یک تومان پرداخت کنید.
مناسب برای
- آکادمی آنلاین با فروش دورهٔ ویدیویی
- اپ موبایل آموزشی یا آزمون (Flutter / Kotlin / Swift / React Native)
- دورهٔ رایگان یا پولی با آزمون پایانی و گواهی قابلتأیید
همان لحظهٔ ساخت، اینها در جدول هستند
/v1/course- ساخت اپ فروشگاهی با Flutter۲٬۴۰۰٬۰۰۰ تومان
- طراحی API برای اپهای موبایلمقدماتی
- تحلیل داده با پایتون۱٬۸۰۰٬۰۰۰ تومان
۱۵ جدولورود کاربران۱۲ قانون۱۰ فانکشن۳۷ ردیف نمونه
با این قالب چه میشود ساخت
کارهایی که اپ یا سایت شما از روز اول روی همین بکاند انجام میدهد.
ویترین دورهها با کلید عمومی
دستهبندی، دوره، سرفصل، درس، آزمون، سؤال، نظرها و تنظیمات آکادمی عمومیاند؛ اپ پیش از ورود کاربر نشانشان میدهد. ویدیو و متن درس، پاسخ درست سؤال و یادداشت داخلی دوره هیچوقت در پاسخ نیستند.
GET /v1/courseثبتنام دانشجو
دانشجو با ایمیل و رمز ثبتنام میکند؛ از این به بعد ثبتنام، سفارش، پیشرفت، نمره و گواهیاش فقط برای خودش است.
POST /v1/auth/signupثبتنام در دورهٔ رایگان
با course_id فانکشن enroll_free را صدا بزنید؛ ثبتنام ساخته میشود و ایمیل خوشآمد برای دانشجو میرود. دورهٔ پولی رد میشود و صدا زدن دوباره همان ثبتنام را برمیگرداند. POST مستقیم به /v1/enrollment برای دانشجو بسته است.
POST /v1/fn/enroll_freeخرید دوره
با course_id (و در صورت نیاز coupon_code) فانکشن buy_course را صدا بزنید؛ سفارش «در انتظار پرداخت» با مبلغی که سرور از قیمت دوره و کد تخفیف حساب کرده برمیگردد.
POST /v1/fn/buy_courseشروع پرداخت
با order_id و callback_url فانکشن pay_start را صدا بزنید و کاربر را به payment_url بفرستید. پیش از آن مرچنتکد زرینپال را با نام ZARINPAL_MERCHANT_ID در secrets پروژه بگذارید. سفارش صفرتومانی بیدرگاه پرداختشده و ثبتنام میشود.
POST /v1/fn/pay_startتأیید پرداخت و ثبتنام
صفحهٔ بازگشت، order_id و Authority و Status را از نشانی برمیدارد و به pay_verify میفرستد؛ سفارش «پرداختشده» و دانشجو در دوره ثبتنام میشود. صدا زدن دوبارهاش بیخطر است.
POST /v1/fn/pay_verifyپخش درس
با lesson_id فانکشن lesson_content را صدا بزنید تا video_url و body برگردد؛ درس پیشنمایش برای همه باز است و بقیه فقط برای ثبتنامکردهها (بقیه ۴۰۳ میگیرند). GET هم کار میکند: /v1/fn/lesson_content?lesson_id=…
POST /v1/fn/lesson_contentثبت پیشرفت
با lesson_id فانکشن complete_lesson را صدا بزنید؛ درس «تمامشده» ثبت و شمار درسهای تمامشدهٔ ثبتنام بهروز میشود. پیشرفت را مستقیم نمیشود نوشت.
POST /v1/fn/complete_lessonشرکت در آزمون
سؤالها را از /v1/question بخوانید و پاسخها را به شکل {"<question id>": شمارهٔ گزینه} با quiz_id به submit_quiz بفرستید؛ نمره و قبولی برمیگردد، پاسخ درست نه.
POST /v1/fn/submit_quizصدور گواهی
وقتی همهٔ درسها تمام و همهٔ آزمونها قبول شده، issue_certificate را با course_id و holder_name صدا بزنید؛ گواهی با کد یکتا صادر و برای دانشجو ایمیل میشود. پیش از آن میگوید چند درس و آزمون مانده.
POST /v1/fn/issue_certificateتأیید اصالت گواهی
هر کسی، بیورود و بیکلید، با code فانکشن verify_certificate را صدا میزند و فقط نام دارنده، عنوان دوره و تاریخ صدور را میگیرد. GET هم کار میکند: /v1/fn/verify_certificate?code=…
GET /v1/fn/verify_certificateنوشتن نظر
دانشجوی ثبتنامکرده با course_id، rating (عدد صحیح ۱ تا ۵) و comment فانکشن add_review را صدا میزند؛ هر دوره یک نظر. ویرایش بعدی با PATCH /v1/review/{id} است.
POST /v1/fn/add_reviewلغو دسترسی یا استرداد
با توکن مدیر یا کلید Production دو کار بکنید: ثبتنام را با PATCH /v1/enrollment/{id} و status: revoked لغو کنید (سفارش استردادشده را refunded و گواهیاش را revoked)، و یک ردیف access_block با student_id و course_id بسازید. بدون access_block، دانشجو ثبتنام خودش را حذف میکند و دوباره ثبتنام میکند؛ این ردیف را دانشجو نه میبیند نه حذف میکند، و همهٔ فانکشنها آن را میسنجند.
POST /v1/access_blockپاک کردن دادهٔ نمونه پیش از راهاندازی
هر آکادمی تازه با دادهٔ نمونه ساخته میشود: کاربرهای student@example.com و admin@example.com، کد تخفیف زندهٔ PAEEZ20، گواهی AC-DEMO-7K2M که verify_certificate آن را اصیل نشان میدهد، سفارش AC-DEMO-0001 و سه دورهٔ نمونه. پیش از فروش واقعی همه را از پنل حذف کنید.
DELETE /v1/coupon/{id}ساخت دوره و درس از طرف آکادمی
با توکن کاربر مدیر یا کلید Production، دوره، سرفصل، درس (با video_url و body)، آزمون و سؤال (با correct_option) بسازید؛ دانشجو هیچکدام را نمیتواند بسازد یا تغییر دهد.
POST /v1/lesson
دادهای که همان لحظه دارید
این ردیفها با ساخت پروژه در جدولها هستند. رکورد معمولیاند و هر وقت خواستید از پنل ویرایش یا پاکشان میکنید.
دستهبندی
۲ ردیف/v1/category| نام | نشانی | ترتیب نمایش |
|---|---|---|
| برنامهنویسی موبایل | mobile | ۱ |
| بکاند و API | backend | ۲ |
دوره
۳ ردیف/v1/course| عنوان | قیمت (تومان) | قیمت پیش از تخفیف (تومان) | سطح |
|---|---|---|---|
| ساخت اپ فروشگاهی با Flutter | ۲٬۴۰۰٬۰۰۰ | ۳٬۲۰۰٬۰۰۰ | متوسط |
| طراحی API برای اپهای موبایل | ۰ | — | مقدماتی |
| تحلیل داده با پایتون | ۱٬۸۰۰٬۰۰۰ | — | مقدماتی |
سرفصل
۴ ردیف/v1/section| عنوان | ترتیب |
|---|---|
| شروع کار | ۱ |
| ساخت فروشگاه | ۲ |
| اصول طراحی | ۱ |
و ۱ ردیف دیگر
درس
۷ ردیف/v1/lesson| عنوان | خلاصه | ترتیب | مدت (دقیقه) |
|---|---|---|---|
| راهاندازی پروژه و ساختار پوشهها | نصب ابزارها و چیدمانی که تا آخر دوره با آن کار میکنیم. | ۱ | ۱۸ |
| فهرست محصولات با بارگذاری تدریجی | اتصال به API و مدیریت حالت بارگذاری و خطا. | ۲ | ۳۲ |
| سبد خرید و ثبت سفارش | نگهداری سبد و ارسال سفارش به سرور. | ۳ | ۴۱ |
و ۴ ردیف دیگر
آزمون
۲ ردیف/v1/quiz| عنوان | نمرهٔ قبولی (از ۱۰۰) | سقف دفعات شرکت | مهلت پاسخ (دقیقه، راهنمای اپ) |
|---|---|---|---|
| آزمون پایانی Flutter | ۷۰ | ۳ | ۱۰ |
| آزمون طراحی API | ۶۰ | ۳ | ۵ |
سؤال
۵ ردیف/v1/question| متن سؤال | ترتیب |
|---|---|
| کدام ویجت برای فهرستی با بارگذاری تدریجی مناسبتر است؟ | ۱ |
| حالت سبد خرید را کجا نگه میداریم تا بین صفحهها بماند؟ | ۲ |
| قیمت نهایی سفارش را چه کسی باید حساب کند؟ | ۳ |
و ۲ ردیف دیگر
کد تخفیف
۱ ردیف/v1/coupon| عنوان | مقدار (درصد یا تومان) | نوع | سقف دفعات استفاده |
|---|---|---|---|
| ۲۰٪ تخفیف پاییزه | ۲۰ | درصدی | ۱۰۰ |
تنظیمات آکادمی
۱ ردیف/v1/academy_settings| نام آکادمی | تلفن | تلگرام | اینستاگرام |
|---|---|---|---|
| آکادمی کدنویس | 021-88005678 | codenevis_academy | codenevis.academy |
ثبتنام
۲ ردیف/v1/enrollment| عنوان دوره | مبلغ پرداختی (تومان) | راه ثبتنام | وضعیت |
|---|---|---|---|
| ساخت اپ فروشگاهی با Flutter | ۲٬۴۰۰٬۰۰۰ | خرید | در حال گذراندن |
| طراحی API برای اپهای موبایل | ۰ | دورهٔ رایگان | تکمیلشده |
سفارش دوره
۱ ردیف/v1/course_order| شمارهٔ سفارش | قیمت دوره (تومان) | تخفیف (تومان) | مبلغ قابل پرداخت (تومان) |
|---|---|---|---|
| AC-DEMO-0001 | ۲٬۴۰۰٬۰۰۰ | ۰ | ۲٬۴۰۰٬۰۰۰ |
پیشرفت درس
۴ ردیف/v1/lesson_progress| عنوان درس |
|---|
| راهاندازی پروژه و ساختار پوشهها |
| فهرست محصولات با بارگذاری تدریجی |
| صفحهبندی: offset یا cursor؟ |
و ۱ ردیف دیگر
شرکت در آزمون
۲ ردیف/v1/quiz_attempt| عنوان آزمون | نمره (از ۱۰۰) | پاسخ درست | تعداد سؤال |
|---|---|---|---|
| آزمون پایانی Flutter | ۳۳ | ۱ | ۳ |
| آزمون طراحی API | ۱۰۰ | ۲ | ۲ |
گواهی
۱ ردیف/v1/certificate| کد گواهی | وضعیت | نام دارنده | عنوان دوره |
|---|---|---|---|
| AC-DEMO-7K2M | معتبر | مریم احمدی | طراحی API برای اپهای موبایل |
نظر دانشجو
۲ ردیف/v1/review| نظر | نام نمایشی | امتیاز (۱ تا ۵) |
|---|---|---|
| کوتاه و کاربردی؛ بخش صفحهبندی دقیقاً مشکلی بود که در اپ خودم داشتم. | مریم | ۵ |
| توضیحها روشن است و پروژه واقعی؛ کاش درس سبد خرید کمی طولانیتر بود. | مریم | ۴ |
جدولها و دسترسی
هر جدول یک مسیر API دارد و از قبل مشخص است چه کسی میخواندش. فیلدهای هر جدول زیر همان جدول باز میشوند.
دستهبندی
/v1/categoryعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
دستهبندی دورهها — عمومی، برای منوی اپ
۳ فیلدو ۱ رابطه
nameناممتنضروریslugنشانیمتنضروریsort_orderترتیب نمایشعدد= 0
- رابطه با دورهیک به چند
category_id
دوره
/v1/courseعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
دورهها — عمومی، ویترین آکادمی؛ فقط دورهٔ «منتشرشده» خریدنی است
۱۷ فیلدو ۵ رابطه
titleعنوانمتنضروریقابل جستجوslugنشانیمتنضروریsummaryمعرفی کوتاهمتنdescriptionتوضیحاتمتنcoverتصویر دورهفایلcategory_idدستهبندیمتنlevelسطحگزینهای= "beginner"priceقیمت (تومان)عددضروریcompare_at_priceقیمت پیش از تخفیف (تومان)عددlanguageزبان دورهگزینهای= "fa"duration_minutesمدت کل (دقیقه)عدد= 0statusوضعیتگزینهای= "draft"instructor_nameمدرسمتنinstructor_bioدربارهٔ مدرسمتنlesson_countتعداد درسعدد= 0student_countتعداد دانشجوعدد= 0internal_noteیادداشت داخلیمتنفقط مدیر
- رابطه با دستهبندیچند به یک
category_id - رابطه با سرفصلیک به چند
course_id - رابطه با درسیک به چند
course_id - رابطه با آزمونیک به چند
course_id - رابطه با نظر دانشجویک به چند
course_id
سرفصل
/v1/sectionعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
فصلهای هر دوره، به ترتیب — عمومی
۳ فیلدو ۲ رابطه
course_idدورهمتنضروریtitleعنوانمتنضروریpositionترتیبعددضروری
- رابطه با دورهچند به یک
course_id - رابطه با درسیک به چند
section_id
درس
/v1/lessonعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
درسهای هر دوره — عنوان و خلاصه عمومیاند تا خریدار بداند چه میخرد؛ ویدیو و متن درس فقط از فانکشن lesson_content
۹ فیلدو ۲ رابطه
course_idدورهمتنضروریsection_idسرفصلمتنpositionترتیبعددضروریtitleعنوانمتنضروریsummaryخلاصهمتنduration_minutesمدت (دقیقه)عدد= 0is_free_previewپیشنمایش رایگانبله/خیر= falsevideo_urlنشانی ویدیونشانی وبفقط مدیرbodyمتن درسمتنفقط مدیر
- رابطه با دورهچند به یک
course_id - رابطه با سرفصلچند به یک
section_id
آزمون
/v1/quizعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
آزمونهای هر دوره — عمومی؛ برای گرفتن گواهی، قبولی در همهٔ آزمونهای دوره لازم است
۶ فیلدو ۲ رابطه
course_idدورهمتنضروریtitleعنوانمتنضروریdescriptionتوضیحاتمتنpass_scoreنمرهٔ قبولی (از ۱۰۰)عدد= 70max_attemptsسقف دفعات شرکتعدد= 3time_limit_minutesمهلت پاسخ (دقیقه، راهنمای اپ)عدد= 0
- رابطه با دورهچند به یک
course_id - رابطه با سؤالیک به چند
quiz_id
سؤال
/v1/questionعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
سؤالهای چهارگزینهای هر آزمون — متن و گزینهها عمومیاند، پاسخ درست هرگز در پاسخ API نمیآید
۵ فیلدو ۱ رابطه
quiz_idآزمونمتنضروریpositionترتیبعددضروریtextمتن سؤالمتنضروریoptionsگزینههاJSONضروریcorrect_optionگزینهٔ درست (از ۰)عددضروریفقط مدیر
- رابطه با آزمونچند به یک
quiz_id
کد تخفیف
/v1/couponکاربران واردشده: هر کاربری که وارد شده باشد همه را میبیند.
کدهای تخفیف خرید دوره — کاربر واردشده شرطها را میبیند، خود کد را هیچوقت
۹ فیلدو ۱ رابطه
titleعنوانمتنضروریcodeکدمتنضروریفقط مدیرkindنوعگزینهای= "percent"valueمقدار (درصد یا تومان)عددضروریcourse_idفقط برای دورهٔمتنexpires_atتاریخ انقضاتاریخusage_limitسقف دفعات استفادهعدد= 0used_countدفعات استفادهشدهعدد= 0activeفعالبله/خیر= true
- رابطه با دورهچند به یک
course_id
تنظیمات آکادمی
/v1/academy_settingsعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
یک ردیف: نام، لوگو، تماس و امضای گواهی — عمومی، برای سربرگ و پانویس اپ
۹ فیلد
academy_nameنام آکادمیمتنضروریlogoلوگوفایلaboutدربارهٔ آکادمیمتنphoneتلفنمتنemailایمیلایمیلtelegramتلگراممتنinstagramاینستاگراممتنcertificate_signerامضاکنندهٔ گواهیمتنtermsقوانین و شرایطمتن
ثبتنام
/v1/enrollmentفقط صاحب ردیف: هر کاربر فقط ردیفهای خودش را میبیند. مالکیت از روی
student_idثبتنامها — فقط enroll_free و پرداخت تأییدشده میسازند؛ دانشجو فقط ثبتنامهای خودش را میخواند
۱۰ فیلدو ۲ رابطه
student_idدانشجومتنcourse_idدورهمتنضروریcourse_titleعنوان دورهمتنsourceراه ثبتنامگزینهای= "manual"order_idسفارشمتنprice_paidمبلغ پرداختی (تومان)عدد= 0statusوضعیتگزینهای= "active"completed_lessonsدرسهای تمامشدهعدد= 0completed_atتاریخ اتمامتاریخenroll_keyکلید یکتاییمتنفقط مدیر
- رابطه با کاربرچند به یک
student_id - رابطه با دورهچند به یک
course_id
سفارش دوره
/v1/course_orderفقط صاحب ردیف: هر کاربر فقط ردیفهای خودش را میبیند. مالکیت از روی
student_idخرید دوره — فقط buy_course میسازد و فقط پرداخت تأییدشده پرداختشدهاش میکند؛ خریدار فقط سفارش خودش را میخواند
۱۲ فیلدو ۲ رابطه
order_numberشمارهٔ سفارشمتنstudent_idخریدارمتنcourse_idدورهمتنضروریcourse_titleعنوان دورهمتنpriceقیمت دوره (تومان)عددضروریdiscountتخفیف (تومان)عدد= 0amountمبلغ قابل پرداخت (تومان)عددضروریcoupon_codeکد تخفیفمتنstatusوضعیتگزینهای= "pending"paid_atزمان پرداختتاریخpayment_authorityAuthority زرینپالمتنفقط مدیرpayment_refکد پیگیری پرداختمتن
- رابطه با کاربرچند به یک
student_id - رابطه با دورهچند به یک
course_id
پیشرفت درس
/v1/lesson_progressفقط صاحب ردیف: هر کاربر فقط ردیفهای خودش را میبیند. مالکیت از روی
student_idدرسهایی که هر دانشجو تمام کرده — فقط complete_lesson مینویسد، فقط خود دانشجو میبیند
۶ فیلدو ۲ رابطه
student_idدانشجومتنenrollment_idثبتناممتنcourse_idدورهمتنضروریlesson_idدرسمتنضروریlesson_titleعنوان درسمتنprogress_keyکلید یکتاییمتنفقط مدیر
- رابطه با ثبتنامچند به یک
enrollment_id - رابطه با درسچند به یک
lesson_id
شرکت در آزمون
/v1/quiz_attemptفقط صاحب ردیف: هر کاربر فقط ردیفهای خودش را میبیند. مالکیت از روی
student_idهر بار شرکت در آزمون با نمرهاش — فقط submit_quiz مینویسد، فقط خود دانشجو میبیند
۱۰ فیلدو ۱ رابطه
student_idدانشجومتنquiz_idآزمونمتنضروریcourse_idدورهمتنضروریquiz_titleعنوان آزمونمتنscoreنمره (از ۱۰۰)عددضروریcorrect_countپاسخ درستعدد= 0question_countتعداد سؤالعدد= 0passedقبولبله/خیر= falseanswersپاسخهاJSONattempt_keyکلید یکتاییمتنفقط مدیر
- رابطه با آزمونچند به یک
quiz_id
گواهی
/v1/certificateفقط صاحب ردیف: هر کاربر فقط ردیفهای خودش را میبیند. مالکیت از روی
student_idگواهی پایان دوره — فقط issue_certificate صادر میکند؛ دانشجو گواهی خودش را میبیند و هر کسی با کدش از verify_certificate اصالتش را میسنجد
۸ فیلدو ۲ رابطه
student_idدانشجومتنcourse_idدورهمتنضروریenrollment_idثبتناممتنcodeکد گواهیمتنضروریholder_nameنام دارندهمتنضروریcourse_titleعنوان دورهمتنstatusوضعیتگزینهای= "valid"cert_keyکلید یکتاییمتنفقط مدیر
- رابطه با کاربرچند به یک
student_id - رابطه با دورهچند به یک
course_id
نظر دانشجو
/v1/reviewعمومی: هر کسی میخواندش، حتی بدون ورود و با کلید عمومی داخل اپ.
امتیاز و نظر دانشجویان — همه میخوانند؛ فقط ثبتنامکرده با add_review مینویسد، هر دوره یک بار، و بعد خودش ویرایشش میکند
۶ فیلدو ۲ رابطه
student_idنویسندهمتنفقط مدیرcourse_idدورهمتنضروریauthor_nameنام نمایشیمتنratingامتیاز (۱ تا ۵)عددضروریcommentنظرمتنreview_keyکلید یکتاییمتنفقط مدیر
- رابطه با دورهچند به یک
course_id - رابطه با کاربرچند به یک
student_id
مسدودی دسترسی
/v1/access_blockکاربران واردشده: هر کاربری که وارد شده باشد همه را میبیند.
دانشجویی که دسترسیاش به یک دوره بسته شده (استرداد، تخلف) — فقط آکادمی مینویسد و میخواند؛ همهٔ فانکشنها پیش از ثبتنام، پرداخت، محتوا، آزمون و گواهی آن را میسنجند
۳ فیلدو ۲ رابطه
student_idدانشجومتنضروریفقط مدیرcourse_idدورهمتنضروریفقط مدیرreasonدلیلمتنفقط مدیر
- رابطه با کاربرچند به یک
student_id - رابطه با دورهچند به یک
course_id
قوانین آماده
منطقی که همراه قالب نصب میشود و از لحظهٔ ساخت فعال است، بدون اینکه یک خط کد بنویسید.
شمارش درسهای دوره
تریگرروی درسشمارش دانشجویان دوره
تریگرروی ثبتنامثبت تاریخ اتمام دوره
تریگرروی ثبتنامثبت زمان پرداخت سفارش دوره
تریگرروی سفارش دورهوضعیت ثبتنام فقط رو به جلو
اعتبارسنجیروی ثبتنامپیامی که کاربر میگیرد: «وضعیت ثبتنام فقط رو به جلو تغییر میکند: در حال گذراندن ← تکمیلشده ← لغوشده. ثبتنام لغوشده را حذف کنید تا دانشجو از نو ثبتنام کند»
وضعیت سفارش دوره فقط رو به جلو
اعتبارسنجیروی سفارش دورهپیامی که کاربر میگیرد: «وضعیت سفارش فقط رو به جلو تغییر میکند: در انتظار پرداخت ← پرداختشده یا لغوشده، و پرداختشده ← مستردشده»
امتیاز نظر بین ۱ و ۵
اعتبارسنجیروی نظر دانشجوپیامی که کاربر میگیرد: «امتیاز باید عدد صحیحی بین ۱ و ۵ باشد»
امتیاز نظر بین ۱ و ۵ (ویرایش)
اعتبارسنجیروی نظر دانشجوپیامی که کاربر میگیرد: «امتیاز باید عدد صحیحی بین ۱ و ۵ باشد»
گزینهٔ درست عدد صحیح
اعتبارسنجیروی سؤالپیامی که کاربر میگیرد: «گزینهٔ درست شمارهٔ یکی از گزینههاست: عدد صحیحی از ۰ تا ۹»
گزینهٔ درست عدد صحیح (ویرایش)
اعتبارسنجیروی سؤالپیامی که کاربر میگیرد: «گزینهٔ درست شمارهٔ یکی از گزینههاست: عدد صحیحی از ۰ تا ۹»
ایمیل ثبتنام در دوره
تریگرروی ثبتنامایمیل صدور گواهی
تریگرروی گواهی
فانکشنهای آماده
منطقی که نباید دست اپ باشد همراه قالب نصب میشود و از لحظهٔ ساخت روشن است. هر فانکشن یک آدرس دارد که اپ یا سرور شما صدایش میزند، و از سهمیهٔ فانکشن پلن حساب میشود.
ثبتنام در دورهٔ رایگان
POST /v1/fn/enroll_freeدانشجوی واردشده را در یک دورهٔ رایگانِ منتشرشده ثبتنام میکند. دورهٔ پولی را رد میکند (آن را با buy_course بخرید)، و دانشجویی را که دسترسیاش به دوره بسته شده هم. صدا زدن دوبارهاش همان ثبتنام قبلی را برمیگرداند. ورودی: course_id.
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
کد فانکشن
// The only way into a free course. A paid one goes through buy_course // and a verified payment; an enrollment row cannot be POSTed directly. // // Idempotent: a student already enrolled gets that enrollment back. Two // racing requests both pass the read; the unique enroll_key refuses the // second write, and it answers with the first one's row. // // An access_block row (written by the academy, never by a student) keeps // a revoked student out even after they delete their own enrollment. // // Ownership is by hand: an admin's own handle reads every student's rows, // and this must still only ever look at — and write — the CALLER's. function fail(status, code, message) { throw {status: status, code: code, message: message}; } // A row that is not there — or an id that cannot be one — is null; any // other refusal (the call budget, authorization being unavailable) is // not «not found» and goes up as is. function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } function view(row) { delete row.enroll_key; return row; } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "ثبتنام با توکن دانشجوی واردشده انجام میشود، نه با کلید API"); } const me = ctx.user.id; const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const courseId = typeof input.course_id === "string" ? input.course_id.trim() : ""; if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید"); const course = getOrNull(ctx.db.admin, "course", courseId); if (!course || course.status !== "published") { fail(404, "course_not_found", "این دوره پیدا نشد یا هنوز منتشر نشده است"); } const mine = {student_id: me, course_id: course.id}; if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const found = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (found.length > 0) { if (found[0].status === "revoked") { fail(403, "enrollment_revoked", "ثبتنام شما در این دوره لغو شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } ctx.respond(view(found[0])); } if (Number(course.price) > 0) { fail(409, "course_not_free", "این دوره رایگان نیست؛ آن را با فانکشن buy_course بخرید"); } let enrollment = null; let raced = false; try { enrollment = ctx.db.admin.create("enrollment", { student_id: me, course_id: course.id, course_title: course.title, source: "free", price_paid: 0, status: "active", enroll_key: me + ":" + course.id, }); } catch (e) { if (!e || e.status !== 409) throw e; raced = true; } if (raced) { const again = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (again.length === 0) fail(409, "enrollment_conflict", "ثبتنام همزمان انجام نشد؛ دوباره تلاش کنید"); enrollment = again[0]; } ctx.respond(view(enrollment));خرید دوره
POST /v1/fn/buy_courseبرای دانشجوی واردشده سفارش خرید یک دورهٔ پولیِ منتشرشده میسازد: قیمت را از خود دوره و تخفیف را از کد تخفیف میخواند. اگر سفارش «در انتظار پرداخت» برای همین دوره دارد، همان را بهروز میکند (یا اگر پرداختش شروع شده، همان را برمیگرداند). کسی که ثبتنام دارد یا دسترسیاش بسته شده رد میشود، و مبلغی بین صفر و ۱٬۰۰۰ تومان (کمتر از حداقل زرینپال) هم. ورودی: course_id و در صورت نیاز coupon_code.
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
کد فانکشن
// Creates (or reprices) the caller's order for one paid course. The // amount is read here, from the course and the coupon table; the request // names only WHICH course and WHICH code — never a price. // // One pending order per student and course. A second call reprices it — // a different coupon, a changed price — unless its payment has started: // then the same order comes back unchanged, so the gateway link the buyer // already has still matches the amount pay_verify will check. // // The coupon's use is counted when the order is PAID (pay_start's free // path, pay_verify), not here, and both of those check the coupon again // before charging: an order nobody pays must not use it up, and a pile // of pending orders must not all pay under a coupon with one use left. const MIN_AMOUNT = 1000; // toman: ZarinPal refuses anything smaller function fail(status, code, message) { throw {status: status, code: code, message: message}; } function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } function view(order) { delete order.payment_authority; return order; } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "خرید دوره با توکن دانشجوی واردشده انجام میشود، نه با کلید API"); } const me = ctx.user.id; const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const courseId = typeof input.course_id === "string" ? input.course_id.trim() : ""; const couponCode = input.coupon_code == null ? "" : String(input.coupon_code).trim().toUpperCase(); if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید"); const course = getOrNull(ctx.db.admin, "course", courseId); if (!course || course.status !== "published") { fail(404, "course_not_found", "این دوره پیدا نشد یا هنوز منتشر نشده است"); } const price = Number(course.price || 0); if (price <= 0) { fail(409, "course_is_free", "این دوره رایگان است؛ با فانکشن enroll_free ثبتنام کنید"); } const mine = {student_id: me, course_id: course.id}; if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (enrolled.length > 0) { if (enrolled[0].status === "revoked") { fail(403, "enrollment_revoked", "ثبتنام شما در این دوره لغو شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } fail(409, "already_enrolled", "شما در این دوره ثبتنام کردهاید و همهٔ درسهایش برایتان باز است"); } const pending = ctx.db.admin.list("course_order", {filter: {student_id: me, course_id: course.id, status: "pending"}, limit: 1}); const existing = pending.length > 0 ? pending[0] : null; if (existing && existing.payment_authority) { ctx.respond(view(existing)); } // ── coupon (the code is admin-read: only this handle can match it) ───── let coupon = null; let discount = 0; if (couponCode) { const found = ctx.db.admin.list("coupon", {filter: {code: couponCode}, limit: 1}); coupon = found.length > 0 ? found[0] : null; if (!coupon || coupon.active === false) { fail(400, "coupon_invalid", "این کد تخفیف معتبر نیست"); } if (coupon.course_id && coupon.course_id !== course.id) { fail(400, "coupon_invalid", "این کد تخفیف برای این دوره نیست"); } if (coupon.expires_at && new Date(coupon.expires_at).getTime() <= Date.now()) { fail(400, "coupon_expired", "مهلت استفاده از این کد تخفیف تمام شده است"); } const limit = Number(coupon.usage_limit || 0); if (limit > 0 && Number(coupon.used_count || 0) >= limit) { fail(400, "coupon_used_up", "ظرفیت استفاده از این کد تخفیف پر شده است"); } discount = coupon.kind === "percent" ? Math.floor(price * Number(coupon.value) / 100) : Number(coupon.value); if (discount > price) discount = price; if (discount < 0) discount = 0; } const amount = price - discount; if (amount > 0 && amount < MIN_AMOUNT) { fail(400, "amount_below_gateway_minimum", "مبلغ پس از تخفیف " + amount + " تومان میشود و درگاه زرینپال کمتر از ۱٬۰۰۰ تومان را نمیپذیرد؛ بدون این کد تخفیف بخرید"); } const terms = { course_title: course.title, price: price, discount: discount, amount: amount, coupon_code: coupon ? coupon.code : "", }; let order = null; if (existing) { order = ctx.db.admin.update("course_order", existing.id, terms); } else { // A readable, practically unique number: the millisecond in base 36 // plus two random characters. The field is unique, so a collision // refuses the order and the buyer simply retries. const suffix = ("0" + Math.floor(Math.random() * 1296).toString(36)).slice(-2); order = ctx.db.admin.create("course_order", Object.assign({ order_number: "AC-" + (Date.now().toString(36) + suffix).toUpperCase(), student_id: me, course_id: course.id, status: "pending", }, terms)); } ctx.respond(view(order));شروع پرداخت
POST /v1/fn/pay_startبرای سفارش «در انتظار پرداخت» خودِ دانشجو تراکنش زرینپال میسازد و نشانی درگاه را برمیگرداند. ورودی: order_id و callback_url (نشانی https صفحهٔ بازگشت اپ شما). شناسهٔ سفارش به callback_url اضافه میشود. پیش از هر پرداخت، ثبتنام قبلی، بسته بودن دسترسی و اعتبار کد تخفیف دوباره سنجیده میشود. سفارشی که قبلاً تراکنش گرفته همان نشانی درگاه را پس میگیرد، و سفارش صفرتومانی بیدرگاه پرداختشده و ثبتنام میشود.
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
مقدارهایی که از شما میخواهد:ZARINPAL_MERCHANT_IDمرچنتکد ۳۶ نویسهای درگاه زرینپال شما؛ از پنل زرینپال، بخش درگاهها.STORE_URLاختیاری: نشانی سایت یا اپ آکادمی، مثل https://academy.example.com — اگر بگذارید، پرداخت فقط به صفحهای زیر همین نشانی برمیگردد.ZARINPAL_SANDBOXاختیاری: برای آزمایش بیهزینه 1 بگذارید تا پرداخت به درگاه آزمایشی زرینپال (sandbox) برود؛ پیش از فروش واقعی پاکش کنید.
کد فانکشن
// Starts a ZarinPal (v4) payment for one of the caller's own pending // orders. The amount is the order's own, read here; the request only says // which order and where the gateway should send the buyer back. // // Before anything is charged: a blocked student is refused, a student // already enrolled (an admin's grant, a second order) is refused with // already_enrolled, and the order's coupon is checked again — one that has // since run out, expired or been switched off cancels the order, and the // buyer places a new one with buy_course. // // An order of 0 (a 100% coupon) needs no gateway: it is settled here — // paid, enrolled, the coupon counted — before the merchant id is asked for. function fail(status, code, message) { throw {status: status, code: code, message: message}; } function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } // Why a coupon can no longer pay, or "". function couponProblem(c, courseId) { if (!c || c.active === false) return "کد تخفیف این سفارش دیگر معتبر نیست"; if (c.course_id && c.course_id !== courseId) return "کد تخفیف این سفارش برای این دوره نیست"; if (c.expires_at && new Date(c.expires_at).getTime() <= Date.now()) return "مهلت کد تخفیف این سفارش تمام شده است"; const limit = Number(c.usage_limit || 0); if (limit > 0 && Number(c.used_count || 0) >= limit) return "ظرفیت کد تخفیف این سفارش پر شده است"; return ""; } // The caller's enrollment in the order's course, made if it is missing. // Same idempotent shape as enroll_free: read, write, and on a unique // conflict read again. function ensureEnrollment(order) { const mine = {student_id: order.student_id, course_id: order.course_id}; const found = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (found.length > 0) return found[0]; let made = null; try { made = ctx.db.admin.create("enrollment", { student_id: order.student_id, course_id: order.course_id, course_title: order.course_title || "", source: "purchase", order_id: order.id, price_paid: Number(order.amount || 0), status: "active", enroll_key: order.student_id + ":" + order.course_id, }); } catch (e) { if (!e || e.status !== 409) throw e; } if (made) return made; const again = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (again.length === 0) fail(409, "enrollment_conflict", "ثبتنام همزمان انجام نشد؛ دوباره تلاش کنید"); return again[0]; } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "پرداخت با توکن دانشجوی واردشده شروع میشود، نه با کلید API"); } const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const orderId = typeof input.order_id === "string" ? input.order_id.trim() : ""; const callback = typeof input.callback_url === "string" ? input.callback_url.trim() : ""; if (!orderId) fail(400, "order_required", "شناسهٔ سفارش را با order_id بفرستید"); // The admin handle is what reads the stored Authority; whose order it is // is checked by hand, for an admin's own handle would see them all. const order = getOrNull(ctx.db.admin, "course_order", orderId); if (!order || order.student_id !== ctx.user.id) { fail(404, "order_not_found", "این سفارش پیدا نشد یا مال شما نیست"); } if (order.status !== "pending") { fail(409, "order_not_payable", "فقط سفارش «در انتظار پرداخت» پرداخت میشود"); } // ── nothing is charged past these ───────────────────────────────────── const mine = {student_id: order.student_id, course_id: order.course_id}; if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (enrolled.length > 0) { if (enrolled[0].status === "revoked") { fail(403, "enrollment_revoked", "ثبتنام شما در این دوره لغو شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } fail(409, "already_enrolled", "شما در این دوره ثبتنام کردهاید؛ این سفارش نیازی به پرداخت ندارد"); } let coupon = null; if (order.coupon_code) { const found = ctx.db.admin.list("coupon", {filter: {code: order.coupon_code}, limit: 1}); coupon = found.length > 0 ? found[0] : null; const problem = couponProblem(coupon, order.course_id); if (problem) { ctx.db.admin.update("course_order", order.id, {status: "cancelled"}); fail(409, "coupon_no_longer_valid", problem + "؛ این سفارش لغو شد — دوباره با buy_course سفارش بدهید"); } } if (Number(order.amount) <= 0) { ctx.db.admin.update("course_order", order.id, {status: "paid", paid_at: new Date().toISOString(), payment_ref: "FREE"}); const enrollment = ensureEnrollment(order); if (coupon) { ctx.db.admin.update("coupon", coupon.id, {used_count: Number(coupon.used_count || 0) + 1}); } delete enrollment.enroll_key; ctx.respond({order_id: order.id, order_number: order.order_number, amount: 0, paid: true, enrollment: enrollment}); } const merchant = ctx.secrets.ZARINPAL_MERCHANT_ID; if (!merchant) { fail(400, "payment_not_configured", "درگاه پرداخت هنوز تنظیم نشده است: مرچنتکد زرینپال را با نام ZARINPAL_MERCHANT_ID در secrets پروژه بگذارید"); } const sandboxFlag = String(ctx.secrets.ZARINPAL_SANDBOX || "").trim(); const gateway = /^(1|true|yes)$/i.test(sandboxFlag) ? "sandbox.zarinpal.com" : "payment.zarinpal.com"; // https only: the gateway sends the buyer back to this page with the // payment's Authority in the query string. if (!/^https:[/][/][^/\s?#]+([/?#]\S*)?$/.test(callback)) { fail(400, "invalid_callback_url", "callback_url باید نشانی کامل https باشد، مثل https://academy.example.com/pay/return"); } // Whitespace-only means unset; the comparison ignores case, as a host does. const storeUrl = String(ctx.secrets.STORE_URL || "").trim(); if (storeUrl) { const base = storeUrl.replace(/[/]+$/, "").toLowerCase(); const rest = callback.slice(base.length); const under = callback.slice(0, base.length).toLowerCase() === base && (rest === "" || rest.charAt(0) === "/" || rest.charAt(0) === "?" || rest.charAt(0) === "#"); if (!under) { fail(400, "invalid_callback_url", "callback_url باید زیر نشانی آکادمی (STORE_URL) باشد"); } } // One order, one transaction. A second request would overwrite the // stored Authority, and a buyer who then paid through the FIRST link // would be refused by pay_verify with the money already taken. if (order.payment_authority) { ctx.respond({ order_id: order.id, order_number: order.order_number, amount: order.amount, authority: order.payment_authority, payment_url: "https://" + gateway + "/pg/StartPay/" + order.payment_authority, }); } const sep = callback.indexOf("?") >= 0 ? "&" : "?"; let res = null; try { res = ctx.http.post("https://" + gateway + "/pg/v4/payment/request.json", { merchant_id: merchant, amount: Math.round(Number(order.amount) * 10), // toman → rial callback_url: callback + sep + "order_id=" + encodeURIComponent(order.id), description: "خرید دورهٔ " + (order.course_title || "") + " — سفارش " + (order.order_number || order.id), metadata: {order_id: order.id}, }, {headers: {Accept: "application/json"}}); } catch (e) { ctx.respond(502, {code: "gateway_unreachable", detail: "درگاه زرینپال در دسترس نبود؛ چند لحظهٔ دیگر دوباره تلاش کنید"}); } const data = res.json && res.json.data && !Array.isArray(res.json.data) ? res.json.data : null; if (!data || data.code !== 100 || !data.authority) { const errors = res.json && res.json.errors && !Array.isArray(res.json.errors) ? res.json.errors : {}; ctx.respond(502, { code: "gateway_refused", detail: "زرینپال درخواست پرداخت را نپذیرفت (کد " + (errors.code || (data && data.code) || res.status) + ")؛ مرچنتکد و نشانی بازگشت را بررسی کنید", }); } ctx.db.admin.update("course_order", order.id, {payment_authority: data.authority}); ctx.respond({ order_id: order.id, order_number: order.order_number, amount: order.amount, authority: data.authority, payment_url: "https://" + gateway + "/pg/StartPay/" + data.authority, });تأیید پرداخت
POST /v1/fn/pay_verifyصفحهٔ بازگشت اپ بعد از درگاه صدایش میزند: Authority را با تراکنش ذخیرهشدهٔ سفارش میسنجد، ثبتنام قبلی، بسته بودن دسترسی و اعتبار کد تخفیف را دوباره میسنجد، پرداخت را با مبلغ خود سفارش از زرینپال تأیید میگیرد، سفارش را «پرداختشده» میکند و دانشجو را در دوره ثبتنام میکند. ورودی: order_id، authority و در صورت وجود status (همان Status بازگشتی). صدا زدن دوبارهاش بیخطر است و ثبتنامِ جامانده را هم میسازد.
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
مقدارهایی که از شما میخواهد:ZARINPAL_MERCHANT_IDمرچنتکد ۳۶ نویسهای درگاه زرینپال شما؛ همان که pay_start میخواند.ZARINPAL_SANDBOXاختیاری: همان مقدار pay_start؛ 1 یعنی تأیید از درگاه آزمایشی زرینپال (sandbox).
کد فانکشن
// Verifies a ZarinPal (v4) payment the gateway has just redirected back, // then enrolls the buyer. // // Nothing is verified — so nothing is charged; ZarinPal returns an // unverified payment by itself within 72 hours — for a blocked student, // one already enrolled, or an order whose coupon has since run out // (that order is cancelled). // // Idempotent: an order already paid is answered as it is — and its // enrollment is made if a failure half-way left it missing — so a page // that reloads, or a buyer who presses back, never pays or fails twice. // // NOT atomic: the order flips to paid, then the enrollment is written, // then the coupon counted. A failure after the first write is healed by // calling this again, except the coupon count, which can stay one short. function fail(status, code, message) { throw {status: status, code: code, message: message}; } function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } function couponProblem(c, courseId) { if (!c || c.active === false) return "کد تخفیف این سفارش دیگر معتبر نیست"; if (c.course_id && c.course_id !== courseId) return "کد تخفیف این سفارش برای این دوره نیست"; if (c.expires_at && new Date(c.expires_at).getTime() <= Date.now()) return "مهلت کد تخفیف این سفارش تمام شده است"; const limit = Number(c.usage_limit || 0); if (limit > 0 && Number(c.used_count || 0) >= limit) return "ظرفیت کد تخفیف این سفارش پر شده است"; return ""; } function ensureEnrollment(order) { const mine = {student_id: order.student_id, course_id: order.course_id}; const found = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (found.length > 0) return found[0]; let made = null; try { made = ctx.db.admin.create("enrollment", { student_id: order.student_id, course_id: order.course_id, course_title: order.course_title || "", source: "purchase", order_id: order.id, price_paid: Number(order.amount || 0), status: "active", enroll_key: order.student_id + ":" + order.course_id, }); } catch (e) { if (!e || e.status !== 409) throw e; } if (made) return made; const again = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (again.length === 0) fail(409, "enrollment_conflict", "ثبتنام همزمان انجام نشد؛ دوباره تلاش کنید"); return again[0]; } // The buyer's view: the Authority and the uniqueness key stay server-side. function answer(order, enrollment) { delete order.payment_authority; delete enrollment.enroll_key; order.enrollment = enrollment; return order; } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "تأیید پرداخت با توکن دانشجوی واردشده انجام میشود، نه با کلید API"); } const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const orderId = typeof input.order_id === "string" ? input.order_id.trim() : ""; const authority = typeof input.authority === "string" ? input.authority.trim() : ""; if (!orderId) fail(400, "order_required", "شناسهٔ سفارش را با order_id بفرستید"); const order = getOrNull(ctx.db.admin, "course_order", orderId); if (!order || order.student_id !== ctx.user.id) { fail(404, "order_not_found", "این سفارش پیدا نشد یا مال شما نیست"); } const mine = {student_id: order.student_id, course_id: order.course_id}; if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } if (order.status === "paid") { ctx.respond(answer(order, ensureEnrollment(order))); } if (order.status !== "pending") { fail(409, "order_not_payable", "این سفارش در وضعیتی نیست که پرداختش تأیید شود؛ اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمیگردد"); } if (input.status === "NOK") { fail(400, "payment_cancelled", "پرداخت انجام نشد یا لغو شد؛ میتوانید دوباره پرداخت کنید"); } if (!authority || !order.payment_authority || authority !== order.payment_authority) { fail(400, "authority_mismatch", "این تراکنش با سفارش جور نیست؛ پرداخت را از نو شروع کنید"); } // ── nothing is verified past these ──────────────────────────────────── const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (enrolled.length > 0) { if (enrolled[0].status === "revoked") { fail(403, "enrollment_revoked", "ثبتنام شما در این دوره لغو شده است؛ اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمیگردد"); } fail(409, "already_enrolled", "شما در این دوره ثبتنام کردهاید؛ این پرداخت تأیید نمیشود و اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمیگردد"); } let coupon = null; if (order.coupon_code) { const found = ctx.db.admin.list("coupon", {filter: {code: order.coupon_code}, limit: 1}); coupon = found.length > 0 ? found[0] : null; const problem = couponProblem(coupon, order.course_id); if (problem) { ctx.db.admin.update("course_order", order.id, {status: "cancelled"}); fail(409, "coupon_no_longer_valid", problem + "؛ این سفارش لغو شد و اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمیگردد"); } } const merchant = ctx.secrets.ZARINPAL_MERCHANT_ID; if (!merchant) { fail(400, "payment_not_configured", "درگاه پرداخت هنوز تنظیم نشده است: مرچنتکد زرینپال را با نام ZARINPAL_MERCHANT_ID در secrets پروژه بگذارید"); } const sandboxFlag = String(ctx.secrets.ZARINPAL_SANDBOX || "").trim(); const gateway = /^(1|true|yes)$/i.test(sandboxFlag) ? "sandbox.zarinpal.com" : "payment.zarinpal.com"; let res = null; try { res = ctx.http.post("https://" + gateway + "/pg/v4/payment/verify.json", { merchant_id: merchant, amount: Math.round(Number(order.amount) * 10), // toman → rial, as pay_start sent it authority: order.payment_authority, }, {headers: {Accept: "application/json"}}); } catch (e) { ctx.respond(502, {code: "gateway_unreachable", detail: "درگاه زرینپال در دسترس نبود؛ چند لحظهٔ دیگر دوباره تلاش کنید"}); } const data = res.json && res.json.data && !Array.isArray(res.json.data) ? res.json.data : null; // 100: verified now; 101: verified by an earlier call. if (!data || (data.code !== 100 && data.code !== 101)) { const errors = res.json && res.json.errors && !Array.isArray(res.json.errors) ? res.json.errors : {}; fail(402, "payment_not_verified", "زرینپال این پرداخت را تأیید نکرد (کد " + (errors.code || (data && data.code) || res.status) + ")؛ اگر مبلغی کم شده، طی ۷۲ ساعت به حساب برمیگردد"); } const paid = ctx.db.admin.update("course_order", order.id, { status: "paid", paid_at: new Date().toISOString(), payment_ref: String(data.ref_id || ""), }); const enrollment = ensureEnrollment(paid); if (coupon) { ctx.db.admin.update("coupon", coupon.id, {used_count: Number(coupon.used_count || 0) + 1}); } ctx.respond(answer(paid, enrollment));محتوای درس
POST /v1/fn/lesson_contentویدیو و متن یک درس را برمیگرداند: درس «پیشنمایش رایگان» یک دورهٔ منتشرشده را به هر کسی، حتی بدون ورود؛ بقیه را فقط به دانشجویی که در آن دوره ثبتنام فعال یا تکمیلشده دارد و دسترسیاش بسته نشده. ورودی: lesson_id (در بدنه یا در نشانی، مثل ?lesson_id=…).
عمومی: هر کسی صدایش میزند، حتی بدون ورود و با کلید عمومی داخل اپ.
کد فانکشن
// The only door to a lesson's video_url and body: both are admin-read, // so a direct GET /v1/lesson never carries them. This reads them with the // admin handle and decides who may have them. // // A free preview of a PUBLISHED course is open to anyone who can reach // the function, signed in or not; a draft course's preview is not out // yet. Anything else needs a signed-in student with an active or // completed enrollment in that very course and no access_block — // checked against the CALLER's id, so an admin's token opens only the // courses they joined. The project's own API key (a server of yours) // reads every lesson. function fail(status, code, message) { throw {status: status, code: code, message: message}; } function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const raw = input.lesson_id != null ? input.lesson_id : ctx.request.query.lesson_id; const lessonId = typeof raw === "string" ? raw.trim() : ""; if (!lessonId) fail(400, "lesson_required", "شناسهٔ درس را با lesson_id بفرستید"); const lesson = getOrNull(ctx.db.admin, "lesson", lessonId); if (!lesson) fail(404, "lesson_not_found", "این درس پیدا نشد"); if (ctx.auth !== "key") { const course = getOrNull(ctx.db.admin, "course", lesson.course_id); const open = lesson.is_free_preview === true && course !== null && course.status === "published"; if (!open) { if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "این درس فقط برای دانشجویان ثبتنامکرده باز است؛ اول وارد شوید"); } const mine = {student_id: ctx.user.id, course_id: lesson.course_id}; if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); const status = enrolled.length > 0 ? enrolled[0].status : ""; if (status !== "active" && status !== "completed") { fail(403, "not_enrolled", "این درس فقط برای دانشجویان ثبتنامکردهٔ همین دوره باز است"); } } } ctx.respond({ lesson_id: lesson.id, course_id: lesson.course_id, title: lesson.title, duration_minutes: lesson.duration_minutes || 0, is_free_preview: lesson.is_free_preview === true, video_url: lesson.video_url || "", body: lesson.body || "", });تمام کردن درس
POST /v1/fn/complete_lessonدرسی را برای دانشجوی ثبتنامکرده «تمامشده» ثبت میکند و شمار درسهای تمامشدهٔ ثبتنامش را بهروز میکند. صدا زدن دوبارهاش بیخطر است. ورودی: lesson_id.
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
کد فانکشن
// Progress is written here and nowhere else: lesson_progress has an // admin-only required lesson_id, so a direct POST cannot mark a lesson // done — and issue_certificate trusts these rows. // // Idempotent: a lesson already done answers with its row. The count on // the enrollment is recomputed from the rows every time, so a failure // between the two writes heals on the next call. const MAX_LESSONS = 500; // one list call; a course larger than this is not counted whole function fail(status, code, message) { throw {status: status, code: code, message: message}; } function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } function view(row) { delete row.progress_key; return row; } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "ثبت پیشرفت با توکن دانشجوی واردشده انجام میشود، نه با کلید API"); } const me = ctx.user.id; const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const lessonId = typeof input.lesson_id === "string" ? input.lesson_id.trim() : ""; if (!lessonId) fail(400, "lesson_required", "شناسهٔ درس را با lesson_id بفرستید"); const lesson = getOrNull(ctx.db.admin, "lesson", lessonId); if (!lesson) fail(404, "lesson_not_found", "این درس پیدا نشد"); const scope = {student_id: me, course_id: lesson.course_id}; if (ctx.db.admin.list("access_block", {filter: scope, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const enrolled = ctx.db.admin.list("enrollment", {filter: scope, limit: 1}); const enrollment = enrolled.length > 0 ? enrolled[0] : null; if (!enrollment || (enrollment.status !== "active" && enrollment.status !== "completed")) { fail(403, "not_enrolled", "فقط دانشجوی ثبتنامکردهٔ این دوره درسهایش را تمام میکند"); } const mine = {student_id: me, lesson_id: lesson.id}; const found = ctx.db.admin.list("lesson_progress", {filter: mine, limit: 1}); let progress = found.length > 0 ? found[0] : null; if (!progress) { let raced = false; try { progress = ctx.db.admin.create("lesson_progress", { student_id: me, enrollment_id: enrollment.id, course_id: lesson.course_id, lesson_id: lesson.id, lesson_title: lesson.title, progress_key: me + ":" + lesson.id, }); } catch (e) { if (!e || e.status !== 409) throw e; raced = true; } if (raced) { const again = ctx.db.admin.list("lesson_progress", {filter: mine, limit: 1}); if (again.length === 0) fail(409, "progress_conflict", "ثبت پیشرفت همزمان انجام نشد؛ دوباره تلاش کنید"); progress = again[0]; } } const done = ctx.db.admin.list("lesson_progress", {filter: scope, limit: MAX_LESSONS}); const lessonIds = {}; for (const p of done) lessonIds[p.lesson_id] = true; const count = Object.keys(lessonIds).length; if (Number(enrollment.completed_lessons || 0) !== count) { ctx.db.admin.update("enrollment", enrollment.id, {completed_lessons: count}); } const out = view(progress); out.completed_lessons = count; ctx.respond(out);ثبت پاسخهای آزمون
POST /v1/fn/submit_quizپاسخهای دانشجوی ثبتنامکرده را سمت سرور تصحیح میکند، یک «شرکت در آزمون» با نمره ذخیره میکند و فقط نمره و قبولی را برمیگرداند — نه پاسخ درست و نه درست یا غلط بودن هر سؤال. برگه باید به همهٔ سؤالها پاسخ بدهد و دفعات شرکت سقف دارد (max_attempts آزمون). ورودی: quiz_id و answers به شکل {"<question id>": شمارهٔ گزینه از ۰}.
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
کد فانکشن
// Grades on the server. correct_option is admin-read, so only this // handle sees it; the answer carries the score, never which questions // were right. // // What keeps the key from leaking is the attempt cap: with unlimited // tries, a student could change one answer at a time and read the key // off the score. So every quiz has a max_attempts (at least 1, default // 3), a sheet must answer EVERY question with a whole option number — a // partial sheet or an odd value is refused, not graded — and each // attempt carries a unique attempt_key «student:quiz:n», so two parallel // submissions cannot both take the last attempt. // // The cap counts the caller's own attempt rows and the highest n they // carry. A student who DELETEs their latest attempt gets that one back: // the role matrix lets a user delete their own rows, and the template // cannot change that. const MAX_QUESTIONS = 100; function fail(status, code, message) { throw {status: status, code: code, message: message}; } function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "شرکت در آزمون با توکن دانشجوی واردشده انجام میشود، نه با کلید API"); } const me = ctx.user.id; const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const quizId = typeof input.quiz_id === "string" ? input.quiz_id.trim() : ""; const answers = input.answers && typeof input.answers === "object" && !Array.isArray(input.answers) ? input.answers : null; if (!quizId) fail(400, "quiz_required", "شناسهٔ آزمون را با quiz_id بفرستید"); if (!answers) fail(400, "answers_required", "پاسخها را با answers به شکل {\"<question id>\": شمارهٔ گزینه} بفرستید"); const quiz = getOrNull(ctx.db.admin, "quiz", quizId); if (!quiz) fail(404, "quiz_not_found", "این آزمون پیدا نشد"); const scope = {student_id: me, course_id: quiz.course_id}; if (ctx.db.admin.list("access_block", {filter: scope, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const enrolled = ctx.db.admin.list("enrollment", {filter: scope, limit: 1}); const status = enrolled.length > 0 ? enrolled[0].status : ""; if (status !== "active" && status !== "completed") { fail(403, "not_enrolled", "فقط دانشجوی ثبتنامکردهٔ این دوره در آزمونش شرکت میکند"); } const maxAttempts = Math.max(1, Number(quiz.max_attempts || 3)); const tried = ctx.db.admin.list("quiz_attempt", {filter: {student_id: me, quiz_id: quiz.id}, limit: maxAttempts}); let n = tried.length; for (const a of tried) { const m = /:(\d+)$/.exec(String(a.attempt_key || "")); if (m && Number(m[1]) > n) n = Number(m[1]); } n += 1; if (tried.length >= maxAttempts || n > maxAttempts) { fail(409, "attempts_exhausted", "دفعات شرکت در این آزمون تمام شده است (" + maxAttempts + " بار)"); } // One more than the cap is fetched: a quiz larger than that is refused // whole, never graded against part of its key. const questions = ctx.db.admin.list("question", {filter: {quiz_id: quiz.id}, limit: MAX_QUESTIONS + 1}); if (questions.length > MAX_QUESTIONS) { fail(409, "quiz_too_large", "این آزمون بیش از ۱۰۰ سؤال دارد و تصحیح نمیشود؛ آن را به چند آزمون بشکنید"); } if (questions.length === 0) fail(409, "quiz_empty", "این آزمون هنوز سؤالی ندارد"); const byId = {}; for (const q of questions) byId[q.id] = q; for (const id of Object.keys(answers)) { const q = byId[id]; const choice = answers[id]; const options = q && Array.isArray(q.options) ? q.options.length : 0; if (!q || typeof choice !== "number" || !Number.isInteger(choice) || choice < 0 || (options > 0 && choice >= options)) { fail(400, "invalid_answer", "پاسخ هر سؤال این آزمون شمارهٔ یکی از گزینههای همان سؤال است، از صفر"); } } let correct = 0; for (const q of questions) { if (!Object.prototype.hasOwnProperty.call(answers, q.id)) { fail(400, "answers_incomplete", "به همهٔ " + questions.length + " سؤال این آزمون پاسخ بدهید؛ برگهٔ ناقص تصحیح نمیشود"); } if (answers[q.id] === Number(q.correct_option)) correct++; } const score = Math.round(correct * 100 / questions.length); const passScore = Number(quiz.pass_score == null ? 70 : quiz.pass_score); const passed = score >= passScore; let attempt = null; try { attempt = ctx.db.admin.create("quiz_attempt", { student_id: me, quiz_id: quiz.id, course_id: quiz.course_id, quiz_title: quiz.title, score: score, correct_count: correct, question_count: questions.length, passed: passed, answers: answers, attempt_key: me + ":" + quiz.id + ":" + n, }); } catch (e) { if (!e || e.status !== 409) throw e; } if (!attempt) { fail(409, "attempt_conflict", "پاسخ دیگری همزمان برای همین نوبت ثبت شد؛ نتیجه را از فهرست شرکتهایتان ببینید"); } ctx.respond({ attempt_id: attempt.id, quiz_id: quiz.id, score: score, pass_score: passScore, passed: passed, correct_count: correct, question_count: questions.length, });صدور گواهی
POST /v1/fn/issue_certificateوقتی دانشجو همهٔ درسهای دوره را تمام کرده و در همهٔ آزمونهایش قبول شده، گواهی با کد یکتا صادر میکند و ثبتنامش را «تکمیلشده» میکند؛ پیش از آن میگوید چه چیزی مانده. صدا زدن دوبارهاش همان گواهی قبلی را برمیگرداند، و گواهی باطلشده ۴۱۰ میگیرد. ورودی: course_id و holder_name (نامی که روی گواهی میآید).
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
کد فانکشن
// Issues the caller's certificate for one course, once. // // Completion is read from the real rows, a few lists with [in] filters // rather than one call per lesson: every lesson of the course must have // the caller's progress row, and every quiz of the course a passed // attempt. Both kinds of row are written by functions only. A list that // reaches its fetch cap is refused, never judged on part of the course. // // Idempotent: a certificate that exists comes back as it is (a new // holder_name is ignored) — and an enrollment a failure left «active» // is completed on the way. A revoked one answers 410. The unique // cert_key makes a racing second request answer with the first one's. // // The code is random — 8 characters from an alphabet without look-alikes // — and unique; a collision is retried once. const MAX_ROWS = 500; const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; function fail(status, code, message) { throw {status: status, code: code, message: message}; } function getOrNull(handle, entity, id) { try { return handle.get(entity, id); } catch (e) { if (e && (e.status === 404 || e.status === 400)) return null; throw e; } } function view(row) { delete row.cert_key; return row; } function newCode() { let s = ""; for (let i = 0; i < 8; i++) s += ALPHABET.charAt(Math.floor(Math.random() * ALPHABET.length)); return "AC-" + s.slice(0, 4) + "-" + s.slice(4); } function capped(rows, what) { if (rows.length > MAX_ROWS) { fail(409, "course_too_large", "این دوره بیش از " + MAX_ROWS + " " + what + " دارد و گواهیاش خودکار صادر نمیشود؛ با پشتیبانی آکادمی تماس بگیرید"); } return rows; } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "گواهی با توکن دانشجوی واردشده صادر میشود، نه با کلید API"); } const me = ctx.user.id; const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const courseId = typeof input.course_id === "string" ? input.course_id.trim() : ""; const holderName = typeof input.holder_name === "string" ? input.holder_name.trim().replace(/\s+/g, " ") : ""; if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید"); const mine = {student_id: me, course_id: courseId}; const issued = ctx.db.admin.list("certificate", {filter: mine, limit: 1}); if (issued.length > 0) { if (issued[0].status === "revoked") { fail(410, "certificate_revoked", "گواهی شما برای این دوره باطل شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const held = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); if (held.length > 0 && held[0].status === "active") { ctx.db.admin.update("enrollment", held[0].id, {status: "completed", completed_at: issued[0].createdAt}); } ctx.respond(view(issued[0])); } if (holderName.length < 2 || holderName.length > 80) { fail(400, "holder_name_required", "نامی را که باید روی گواهی بیاید با holder_name بفرستید (۲ تا ۸۰ نویسه)"); } const course = getOrNull(ctx.db.admin, "course", courseId); if (!course) fail(404, "course_not_found", "این دوره پیدا نشد"); if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); const enrollment = enrolled.length > 0 ? enrolled[0] : null; if (!enrollment || (enrollment.status !== "active" && enrollment.status !== "completed")) { fail(403, "not_enrolled", "فقط دانشجوی ثبتنامکردهٔ این دوره گواهیاش را میگیرد"); } // ── completion, from the rows ───────────────────────────────────────── const lessons = capped(ctx.db.list("lesson", {filter: {course_id: course.id}, limit: MAX_ROWS + 1}), "درس"); const quizzes = capped(ctx.db.list("quiz", {filter: {course_id: course.id}, limit: MAX_ROWS + 1}), "آزمون"); const done = {}; for (const p of capped(ctx.db.admin.list("lesson_progress", {filter: mine, limit: MAX_ROWS + 1}), "درس")) { done[p.lesson_id] = true; } const passed = {}; if (quizzes.length > 0) { const quizIds = quizzes.map(function (q) { return q.id; }); const attempts = capped(ctx.db.admin.list("quiz_attempt", {filter: {student_id: me, "quiz_id[in]": quizIds, passed: true}, limit: MAX_ROWS + 1}), "آزمون"); for (const a of attempts) passed[a.quiz_id] = true; } let lessonsLeft = 0; for (const l of lessons) if (!done[l.id]) lessonsLeft++; let quizzesLeft = 0; for (const q of quizzes) if (!passed[q.id]) quizzesLeft++; if (lessons.length === 0) { fail(409, "course_empty", "این دوره هنوز درسی ندارد"); } if (lessonsLeft > 0 || quizzesLeft > 0) { const parts = []; if (lessonsLeft > 0) parts.push(lessonsLeft + " درس"); if (quizzesLeft > 0) parts.push(quizzesLeft + " آزمون"); fail(409, "course_not_completed", "هنوز دوره تمام نشده است: " + parts.join(" و ") + " مانده"); } // ── issue ───────────────────────────────────────────────────────────── const row = { student_id: me, course_id: course.id, enrollment_id: enrollment.id, holder_name: holderName, course_title: course.title, status: "valid", cert_key: me + ":" + course.id, }; let cert = null; for (let attempt = 0; attempt < 2 && !cert; attempt++) { let conflict = false; try { cert = ctx.db.admin.create("certificate", Object.assign({code: newCode()}, row)); } catch (e) { if (!e || e.status !== 409) throw e; conflict = true; } if (conflict) { // Either a racing request issued it first, or the code collided. const again = ctx.db.admin.list("certificate", {filter: mine, limit: 1}); if (again.length > 0) ctx.respond(view(again[0])); } } if (!cert) fail(409, "certificate_conflict", "صدور گواهی همزمان انجام نشد؛ دوباره تلاش کنید"); if (enrollment.status !== "completed") { ctx.db.admin.update("enrollment", enrollment.id, {status: "completed", completed_at: new Date().toISOString()}); } ctx.respond(view(cert));تأیید اصالت گواهی
POST /v1/fn/verify_certificateعمومی و بدون ورود: با کد گواهی، فقط نام دارنده، عنوان دوره و تاریخ صدور را برمیگرداند. کد نادرست ۴۰۴ میگیرد و گواهی باطلشده ۴۱۰. ورودی: code (در بدنه یا در نشانی، مثل ?code=…).
عمومی: هر کسی صدایش میزند، حتی بدون ورود و با کلید عمومی داخل اپ.
کد فانکشن
// Anyone — an employer, a stranger with a link — checks a certificate by // its code. The answer is deliberately narrow: the holder's name, the // course and the date, never the student's id, email or anything else. // The date is the certificate row's createdAt: the moment it was issued. function fail(status, code, message) { throw {status: status, code: code, message: message}; } const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const raw = input.code != null ? input.code : ctx.request.query.code; const code = typeof raw === "string" ? raw.trim().toUpperCase() : ""; if (!code) fail(400, "code_required", "کد گواهی را با code بفرستید"); // The certificate code's own pattern; anything else matches nothing, and // is never handed to the filter as is. if (!/^[A-Z0-9-]{6,40}$/.test(code)) { fail(404, "certificate_not_found", "گواهی با این کد پیدا نشد"); } const found = ctx.db.admin.list("certificate", {filter: {code: code}, limit: 1}); if (found.length === 0) fail(404, "certificate_not_found", "گواهی با این کد پیدا نشد"); const cert = found[0]; if (cert.status === "revoked") { fail(410, "certificate_revoked", "این گواهی صادر شده بود ولی باطل شده است"); } ctx.respond({ code: cert.code, holder_name: cert.holder_name, course_title: cert.course_title || "", issued_at: cert.createdAt, valid: true, });ثبت نظر
POST /v1/fn/add_reviewدانشجوی ثبتنامکرده برای دوره امتیاز (عدد صحیح ۱ تا ۵) و نظر ثبت میکند؛ هر دوره یک بار. ویرایش بعدی با PATCH /v1/review/{id} است. ورودی: course_id، rating، و در صورت نیاز comment و author_name.
کاربران واردشده: کاربری که در اپ وارد شده صدایش میزند؛ سرور شما هم با کلید API.
کد فانکشن
// Only an enrolled student reviews, once per course. review has an // admin-only required course_id, so a direct POST cannot skip this; the // student edits their own review afterwards with a plain PATCH, where the // rating rules hold again. function fail(status, code, message) { throw {status: status, code: code, message: message}; } function view(row) { delete row.review_key; return row; } if (ctx.auth !== "user" || !ctx.user.id) { fail(403, "login_required", "نظر با توکن دانشجوی واردشده ثبت میشود، نه با کلید API"); } const me = ctx.user.id; const body = ctx.request.body; const input = body && typeof body === "object" && !Array.isArray(body) ? body : {}; const courseId = typeof input.course_id === "string" ? input.course_id.trim() : ""; const rating = input.rating; const comment = input.comment == null ? "" : String(input.comment).trim(); const authorName = input.author_name == null ? "" : String(input.author_name).trim(); if (!courseId) fail(400, "course_required", "شناسهٔ دوره را با course_id بفرستید"); // A JSON number only: true, "5" or [5] are not ratings. if (typeof rating !== "number" || !Number.isInteger(rating) || rating < 1 || rating > 5) { fail(422, "rating_out_of_range", "امتیاز باید عدد صحیحی بین ۱ و ۵ باشد"); } if (comment.length > 1000) fail(400, "comment_too_long", "نظر حداکثر ۱۰۰۰ نویسه است"); if (authorName.length > 60) fail(400, "author_name_too_long", "نام نمایشی حداکثر ۶۰ نویسه است"); const mine = {student_id: me, course_id: courseId}; if (ctx.db.admin.list("access_block", {filter: mine, limit: 1}).length > 0) { fail(403, "access_blocked", "دسترسی شما به این دوره بسته شده است؛ با پشتیبانی آکادمی تماس بگیرید"); } const enrolled = ctx.db.admin.list("enrollment", {filter: mine, limit: 1}); const status = enrolled.length > 0 ? enrolled[0].status : ""; if (status !== "active" && status !== "completed") { fail(403, "not_enrolled", "فقط دانشجوی ثبتنامکردهٔ این دوره برایش نظر مینویسد"); } const existing = ctx.db.admin.list("review", {filter: mine, limit: 1}); if (existing.length > 0) { fail(409, "review_exists", "شما برای این دوره نظر دادهاید؛ برای تغییرش PATCH /v1/review/" + existing[0].id + " را بفرستید"); } const row = {student_id: me, course_id: courseId, rating: rating, review_key: me + ":" + courseId}; if (comment) row.comment = comment; if (authorName) row.author_name = authorName; let review = null; try { review = ctx.db.admin.create("review", row); } catch (e) { if (e && e.status === 409) { fail(409, "review_exists", "شما برای این دوره نظر دادهاید"); } throw e; } ctx.respond(view(review));
اولین درخواست
نمونهکدی که فقط نشانی پروژه و کلید شما را کم دارد. جای خالیها را بعد از ساخت پروژه، خود پنل پر میکند.
از ویترین تا گواهی
ویترین دورهها عمومی است و با کلید عمومی و بدون ورود خوانده میشود. ثبتنام، خرید، محتوای درس، آزمون و گواهی فقط از راه فانکشنها انجام میشوند؛ قیمت، دسترسی به محتوا و نمرهٔ آزمون را سرور تعیین میکند، نه اپ.
npm install @fikaro/clientimport { createClient } from "@fikaro/client";
const client = createClient({
project: "{{slug}}",
key: "{{publishable_key}}",
});
// ۱. ویترین — عمومی، بدون ورود
const { data: courses } = await client.from("course").list({
filter: { status: "published" },
sort: "-createdAt",
});
const course = courses[0];
const { data: lessons } = await client.from("lesson").list({
filter: { course_id: course.id },
sort: "position",
});
// درس پیشنمایش را همه میبینند، حتی بدون ورود
const preview = lessons.find((l) => l.is_free_preview);
const sample = await client.request("POST", "/fn/lesson_content", { lesson_id: preview.id });
// ۲. دانشجو ثبتنام میکند
await client.auth.signup("student-1@example.com", "a-strong-password");
// ۳. دورهٔ رایگان: یک فراخوانی
// دورهٔ پولی: سفارش، درگاه زرینپال، و بعد تأیید در صفحهٔ بازگشت
if (course.price === 0) {
await client.request("POST", "/fn/enroll_free", { course_id: course.id });
} else {
const order = await client.request("POST", "/fn/buy_course", {
course_id: course.id,
coupon_code: "PAEEZ20", // اختیاری
});
const { payment_url } = await client.request("POST", "/fn/pay_start", {
order_id: order.id,
callback_url: "https://academy.example.com/pay/return",
});
window.location.href = payment_url;
// صفحهٔ بازگشت: /pay/return?order_id=…&Authority=…&Status=OK
// const q = new URLSearchParams(window.location.search);
// await client.request("POST", "/fn/pay_verify", {
// order_id: q.get("order_id"), authority: q.get("Authority"), status: q.get("Status"),
// });
}
// ۴. درسها: محتوا، و ثبت «تمام شد»
for (const lesson of lessons) {
const { video_url, body } = await client.request("POST", "/fn/lesson_content", { lesson_id: lesson.id });
await client.request("POST", "/fn/complete_lesson", { lesson_id: lesson.id });
}
// ۵. آزمون: سؤالها عمومیاند، پاسخ درست نه؛ تصحیح سمت سرور است.
// برگه باید به همهٔ سؤالها پاسخ بدهد و دفعات شرکت سقف دارد (max_attempts).
const { data: quizzes } = await client.from("quiz").list({ filter: { course_id: course.id } });
const { data: questions } = await client.from("question").list({
filter: { quiz_id: quizzes[0].id },
sort: "position",
});
const result = await client.request("POST", "/fn/submit_quiz", {
quiz_id: quizzes[0].id,
answers: Object.fromEntries(questions.map((q) => [q.id, 0])), // شمارهٔ گزینهٔ انتخابی، از ۰
});
// result.score، result.passed
// ۶. گواهی، و تأییدش با کد — بدون ورود، برای هر کسی
const cert = await client.request("POST", "/fn/issue_certificate", {
course_id: course.id,
holder_name: "مریم احمدی",
});
const check = await client.request("GET", "/fn/verify_certificate?code=" + cert.code);
کلید عمومی دوره، سرفصل، درس، آزمون، سؤال و نظرها را میخواند و امن است که داخل اپ یا APK باشد؛ ویدیو و متن درس و پاسخ درست سؤال هرگز در پاسخ مستقیم API نمیآیند. محتوای درس را فانکشن lesson_content فقط به دانشجوی ثبتنامکرده میدهد (درس پیشنمایش را به همه). ثبتنام، سفارش، پیشرفت، نمره و گواهی «فقط مال خود کاربر» هستند و مستقیم ساخته نمیشوند. پرداخت تا وقتی ZARINPAL_MERCHANT_ID را در secrets پروژه نگذارید کار نمیکند. توجه: کلید خودِ پروژه همهچیز را میبیند — اگر از پنل تست میکنید دادهای میبینید که اپ شما نمیبیند. پیش از راهاندازی واقعی، دادهٔ نمونه را حذف کنید: کاربرهای student@example.com و admin@example.com (مدیر)، کد تخفیف زندهٔ PAEEZ20، گواهی نمونهٔ AC-DEMO-7K2M (که اصیل نشان داده میشود)، سفارش AC-DEMO-0001 و سه دورهٔ نمونه با درسها و آزمونهایشان.
از همین قالب شروع کنید؛ بکاندش با من.
۱۵ روز اول رایگانبا پلنکاپوچینو
اعتبار هدیهٔ ثبتنام هزینهاش را میدهد؛ لازم نیست حتی یک تومان پرداخت کنید.