لوگو

مستندات REST API و وب‌سرویس

مرکز آموزش‌های تخصصی جهاد دانشگاهی صنعتی شریف
پرتال فراگیران پنل مدیریت
RESTful API v1.0

راهنمای وب‌سرویس ثبت‌نام و اتصال سیستم‌های سازمانی (Third-Party Integration)

این رابط برنامه‌نویسی (API) به سازمان‌ها، شرکت‌ها، پورتال‌های منابع انسانی (HR) و سیستم‌های آموزشی خارجی اجازه می‌دهد فراگیران خود را به صورت خودکار در دوره‌ها ثبت‌نام نموده و وضعیت آزمون و نمرات آنان را پیگیری کنند.

BASE URL
http://localhost:3000/api/v1

۱. احراز هویت و هدرهای الزامی (Headers & Authentication)

تمام درخواست‌های ارسالی باید هدر Content-Type: application/json داشته باشند. در صورت تمایل به اعمال کلید اختصاصی می‌توانید از هدر x-api-key استفاده کنید.

Content-Type: application/json
x-api-key: ACECR_LMS_SECURE_API_KEY_2026

۲. ثبت‌نام تکی فراگیر و تخصیص دوره (Single User Registration)

با این متد، یک کاربر جدید با کد ملی به عنوان نام کاربری و کلمه عبور در سامانه ایجاد شده و در صورت ارسال courseId، بلافاصله در آن دوره ثبت‌نام می‌گردد.

POST /api/v1/users/register

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

نام فیلد نوع الزامی؟ توضیحات و نمونه
nationalCode String بله کد ملی ۱۰ رقمی فراگیر (نام کاربری و رمز ورود) — مثال: "0012345678"
fullName String بله نام و نام خانوادگی کامل — مثال: "محمد رضایی"
phone String بله شماره موبایل — مثال: "09123456789" یا "+989123456789"
email String اختیاری پست الکترونیکی فراگیر — مثال: "m.rezaei@company.ir"
company String اختیاری نام سازمان یا شرکت متقاضی — مثال: "شرکت ملی گاز"
position String اختیاری سمت سازمانی — مثال: "کارشناس ارشد آموزش"
courseId String اختیاری شناسه دوره جهت ثبت‌نام مستقیم — مثال: "course-1"

نمونه کدهای پیاده‌سازی:

curl -X POST http://localhost:3000/api/v1/users/register \ -H "Content-Type: application/json" \ -d '{ "nationalCode": "0012345678", "fullName": "محمد رضایی", "phone": "09123456789", "email": "m.rezaei@company.ir", "company": "پتروشیمی خلیج فارس", "position": "کارشناس ارشد آموزش", "courseId": "course-1" }'
تست آنلاین این وب‌سرویس (Live Sandbox Tester):

۳. ثبت‌نام گروهی فراگیران (Batch Registration API)

مناسب برای پورتال‌های منابع انسانی جهت ارسال یک‌جای فهرست کارکنان (مثلاً ۵۰ یا ۱۰۰ نفر) در یک درخواست.

POST /api/v1/users/batch-register
{ "users": [ { "nationalCode": "0011111111", "fullName": "حمید حسینی", "phone": "09121111111", "company": "شرکت آلفا", "position": "مدیر پروژه", "email": "h.hosseini@alpha.ir", "courseId": "course-1" }, { "nationalCode": "0022222222", "fullName": "زهرا محمدی", "phone": "09122222222", "company": "شرکت آلفا", "position": "کارشناس بازرگانی", "email": "z.mohammadi@alpha.ir", "courseId": "course-1" } ] }

۴. استعلام وضعیت، نمره آزمون و شناسه گواهینامه (User Status & Exam Scores)

سیستم‌های خارجی می‌توانند با وارد کردن کد ملی، وضعیت ثبت‌نام، درصد پیشرفت، نمره کسب‌شده در آزمون (مثلاً ۱۰ از ۱۰) و کد اعتبارسنجی گواهینامه را استعلام کنند.

GET /api/v1/users/{nationalCode}/status
curl -X GET http://localhost:3000/api/v1/users/0012345678/status
نمونه پاسخ موفق (HTTP 200 OK):
{ "success": true, "user": { "nationalCode": "0012345678", "fullName": "محمد رضایی", "phone": "09123456789", "company": "پتروشیمی خلیج فارس" }, "enrollments": [ { "courseId": "course-1", "courseTitle": "نیاز سنجی آموزشی", "progress": 100, "examScore": 9, "totalQuestions": 10, "scorePercent": 90, "passed": true, "verifyId": "LMN-482910", "enrolledAt": "۲۸ مرداد ۱۴۰۵" } ] }