پرش به محتوا
امروزینومجلهٔ فناوری و مهارت

مستندات API امروزینو

مرجع کامل نقاط پایانی REST نسخه‌ی ۱ — برای توسعه‌دهندگانی که می‌خواهند محتوای مجله را در ابزارهای خود به کار بگیرند. همه‌ی پاسخ‌ها JSON هستند و خطاها در پاکت استاندارد { error: { code, message } } برمی‌گردند.

۹۲نقطه پایانی مستندشده
۱۲بخش موضوعی
v1نسخه
JSONقالب پاسخ
دانلود OpenAPI 3.1مشاهدهٔ JSON

مقدمات۲ نقطه پایانی

پایه و آدرس‌ها، قالب پاسخ و خطاها

GET/api/v1/{endpoint}

همه‌ی درخواست‌ها به آدرس پایه api/v1 می‌رسند. پاسخ‌ها همیشه JSON هستند و خطاها در پاکت استاندارد error قرار می‌گیرند.

پاسخ{ data… } | { error: { code, message, details? } }
GET/api/v1/openapi

خروجی OpenAPI 3.1 از همین کاتالوگ؛ برای import در Postman و Insomnia یا تولید کلاینت. امنیت کوکی نشست (cookieAuth) برای مسیرهای مدیریتی تعریف شده است.

پاسخ{ openapi, info, servers, tags, components, paths }

احراز هویت۳ نقطه پایانی

ورود، خروج و نشست کاربران

POST/api/v1/auth/login

ورود کاربر با ایمیل و گذرواژه؛ کوکی نشست (HttpOnly) تنظیم می‌شود.

پارامترها

  • بدنهemail*ایمیل کاربر
  • بدنهpassword*گذرواژه
پاسخ{ user }
POST/api/v1/auth/logout

خروج و حذف نشست جاری.

پاسخ{ ok: true }
GET/api/v1/auth/me

اطلاعات کاربر جاری بر اساس کوکی نشست.

پاسخ{ user } | 401

مقالات۳ نقطه پایانی

فهرست، جزئیات و مطالب مرتبط

GET/api/v1/articles

فهرست مقالات منتشرشده با فیلتر، جست‌وجوی فارسی‌پسند و صفحه‌بندی.

پارامترها

  • کوئریcategoryاسلاگ دسته‌بندی (شامل زیرمجموعه‌ها)
  • کوئریsubcategoryاسلاگ زیردسته‌بندی
  • کوئریtagاسلاگ برچسب
  • کوئریauthorاسلاگ نویسنده
  • کوئریqجست‌وجو در عنوان و خلاصه (نرمال‌سازی ی/ک)
  • کوئریsortnewest | popular | oldest
  • کوئریfeaturedفقط شاخص‌ها (true)
  • کوئریeditorChoiceفقط منتخب سردبیر (true)
  • کوئریpageشماره صفحه (پیش‌فرض ۱)
  • کوئریlimitتعداد در صفحه (۱ تا ۲۴)
پاسخ{ items, total, page, pages }
GET/api/v1/articles/{slug}

جزئیات یک مقاله + شمارنده بازدید + مطالب مرتبط. اگر مقاله بخشی از مجموعه باشد، فهرست مرتب قسمت‌های مجموعه (seriesParts) هم برگردانده می‌شود. اگر کوکی ناشناس خواننده (emrozino-reader) موجود باشد، وضعیت پسندیدن (liked) هم برگردانده می‌شود.

پارامترها

  • مسیرslug*اسلاگ لاتین مقاله
پاسخ{ article, related, liked, seriesParts? }
POST/api/v1/articles/{slug}/like

پسندیدن/حذف پسند مقاله برای خواننده ناشناس. هر دستگاه (کوکی emrozino-reader) فقط یک پسند برای هر مقاله می‌تواند داشته باشد؛ فراخوانی مجدد پسند را برمی‌گرداند (toggle).

پارامترها

  • مسیرslug*اسلاگ لاتین مقاله
پاسخ{ liked, likeCount } | 404 | 429

دسته‌بندی، برچسب و نویسندگان۶ نقطه پایانی

اختلافات و پروفایل‌ها

GET/api/v1/categories

درخت دسته‌بندی‌های فعال (۲ سطح).

پاسخ{ items }
GET/api/v1/categories/{slug}

جزئیات یک دسته‌بندی + فرزندانش.

پارامترها

  • مسیرslug*اسلاگ دسته
پاسخ{ category }
GET/api/v1/tags

همه‌ی برچسب‌ها به‌ترتیب تعداد استفاده.

پاسخ{ items }
GET/api/v1/tags/{slug}

جزئیات برچسب + مقالات آن.

پارامترها

  • مسیرslug*اسلاگ برچسب
پاسخ{ tag, articles }
GET/api/v1/authors

فهرست نویسندگان فعال.

پاسخ{ items }
GET/api/v1/authors/{slug}

پروفایل نویسنده + مقالاتش.

پارامترها

  • مسیرslug*اسلاگ نویسنده
پاسخ{ author, articles }

مجموعه مقالات۲ نقطه پایانی

مجموعه‌های چندقسمتی

GET/api/v1/series

همهٔ مجموعه‌های منتشرشده با آمار تجمیعی (تعداد قسمت‌های منتشرشده، مجموع زمان مطالعه، تاریخ اولین/آخرین قسمت) و نامک قسمت‌ها برای محاسبهٔ پیشرفت مطالعه.

پاسخ{ items }
GET/api/v1/series/{slug}

جزئیات یک مجموعه منتشرشده + قسمت‌های مرتب‌شده (قسمت ۱ اول) به‌صورت مقالهٔ کامل.

پارامترها

  • مسیرslug*اسلاگ لاتین مجموعه
پاسخ{ series, parts } | 404

آزمون‌های تعاملی۳ نقطه پایانی

آزمون‌های رایگان زبان — تعیین سطح، گرامر و واژگان انگلیسی/آلمانی/فرانسه، آیلتس/تافل

GET/api/v1/quizzes

همهٔ آزمون‌های منتشرشده با تعداد پرسش، زمان پیشنهادی، نمرهٔ قبولی و تعداد شرکت‌کننده‌ها.

پاسخ{ items }
GET/api/v1/quizzes/{slug}

جزئیات یک آزمون + پرسش‌ها و گزینه‌ها. توجه: پاسخ درست هرگز قبل از تصحیح به کلاینت فرستاده نمی‌شود.

پارامترها

  • مسیرslug*اسلاگ لاتین آزمون
پاسخ{ quiz } | 404
POST/api/v1/quizzes/{slug}/submit

تصحیح آزمون در سرور. بدنه: { answers: (number|null)[], durationSec? } به‌ترتیب پرسش‌ها. پاسخ شامل نمره، وضعیت قبولی و مرور کامل (پاسخ درست + توضیح فارسی) است.

پارامترها

  • مسیرslug*اسلاگ لاتین آزمون
پاسخ{ score, correct, total, passed, passScore, review } | 400 | 404 | 429

واژه‌نامه تخصصی۲ نقطه پایانی

تعریف واژه‌ها با جست‌وجو و فیلتر حروف

GET/api/v1/glossary

واژه‌های منتشرشده با جست‌وجوی فارسی‌پسند، فیلتر حرف الفبا و دسته‌بندی. مرتب‌سازی بر اساس الفبای فارسی.

پارامترها

  • کوئریqجست‌وجو در واژه، معادل انگلیسی و تعریف کوتاه
  • کوئریletterحرف اول فارسی (آ → ا نرمال می‌شود)
  • کوئریcategoryاسلاگ دسته (شامل فرزندان)
  • کوئریpageشماره صفحه (پیش‌فرض ۱)
  • کوئریlimitتعداد در صفحه (۱ تا ۶۰)
پاسخ{ items, total, page, pages, letters }
GET/api/v1/glossary/{slug}

تعریف کامل یک واژه + واژه‌های مرتبط + شمارنده بازدید.

پارامترها

  • مسیرslug*اسلاگ لاتین واژه
پاسخ{ term, related }

هاب کشورهای مهاجرتی۲ نقطه پایانی

مقاصد مهاجرت — همهٔ مطالب هر کشور یک‌جا

GET/api/v1/countries

فهرست کشورهای مقصد (ثبت ایستا) به‌همراه تعداد مقالات منتشرشدهٔ مرتبط در ریشهٔ مهاجرت (عنوان یا چکیده حاوی کلیدواژه‌های کشور)؛ مرتب‌شده بر اساس تعداد مطلب.

پاسخ{ items: [{ slug, name, flag, tagline, articleCount }] }
GET/api/v1/countries/{slug}

هاب یک کشور: مقالات منتشرشدهٔ مرتبط، گروه‌بندی‌شده بر اساس زیردسته‌های مهاجرت (تحصیل، کار، راهنمای کشورها، زندگی در خارج، آمادگی و مدارک — هر گروه حداکثر ۱۲ مطلب، جدیدترین اول) + گروه «از دیگر بخش‌های امروزینو» برای مطالب دیگر ریشه‌ها + واژه‌های مرتبط واژه‌نامه (حداکثر ۸ مورد).

پارامترها

  • مسیرslug*اسلاگ لاتین کشور (germany، canada، …)
پاسخ{ country, groups, glossaryTerms } | 404

صفحات ثابت و مسیرها۲ نقطه پایانی

صفحات درباره/تماس و مسیرهای یادگیری

GET/api/v1/pages/{slug}

محتوای یک صفحه ثابت (about, contact, …).

پارامترها

  • مسیرslug*اسلاگ صفحه
پاسخ{ page }
GET/api/v1/learning-paths

مسیرهای یادگیری منتشرشده با گام‌ها.

پاسخ{ items }

تعامل و بازاریابی۹ نقطه پایانی

تماس و تبلیغات

POST/api/v1/contact

ارسال پیام تماس (نرخ محدود: ۵ در ساعت).

پارامترها

  • بدنهname*نام فرستنده
  • بدنهemail*ایمیل فرستنده
  • بدنهsubject*موضوع
  • بدنهmessage*متن پیام
پاسخ{ ok: true }
GET/api/v1/ads

بنرهای تبلیغاتی فعال برای یک جایگاه (جایگاه FLOATING برای بنر شناور).

پارامترها

  • کوئریplacementHOME_TOP | HOME_MIDDLE | HOME_BOTTOM | CATEGORY | ARTICLE_IN | ARTICLE_END | SIDEBAR | FOOTER | FLOATING
  • کوئریcountViews0 = بدون شمارش نمایش (برای بنر شناور پس از نمایش واقعی)
پاسخ{ items }
POST/api/v1/ads/click

ثبت کلیک روی تبلیغ.

پارامترها

  • بدنهid*شناسه تبلیغ
پاسخ{ ok: true }
GET/api/v1/footer-links

لینک‌های فعال فوتر (قابل مدیریت از پنل).

پاسخ{ items, columns }
GET/api/v1/social-links

شبکه‌های اجتماعی فعال سایت.

پارامترها

  • کوئریplacementfooter | header
پاسخ{ items }
GET/api/v1/partner-links

لینک‌های همکاری و حمایت‌شده فعال (با rel صحیح).

پاسخ{ items }
GET/api/v1/contact-channels

کانال‌های فعال دکمه شناور تماس با ما.

پاسخ{ items }
GET/api/v1/settings

تنظیمات عمومی سایت (فقط کلیدهای عمومی).

پاسخ{ items }
GET/api/v1/home

داده‌های صفحه اصلی در یک درخواست (شاخص، تازه‌ها، منتخب، دسته‌ها، مسیرها).

پاسخ{ featured, latest, editorChoice, categories, paths, topViewed, … }

مدیریت (CMS)۵۶ نقطه پایانی

نقطه‌های پایانی پنل مدیریت — نیازمند نشست واردشده

دسترسی: نشست واردشده لازم است — DASHBOARD_VIEW (خواندن) · سطح دسترسی متناسب هر بخش (نوشتن)
GET/api/v1/admin/dashboard

آمار کلی، نمودار ۱۴ روزه، پربازدیدها و آخرین رخدادها.

پاسخ{ stats, chart, topViewed, recentArticles, activity }
GET/api/v1/admin/articles

فهرست همه مقالات (همه وضعیت‌ها) با فیلتر وضعیت/دسته/نویسنده/جست‌وجو.

پارامترها

  • کوئریstatusDRAFT | REVIEW | READY | SCHEDULED | PUBLISHED | ARCHIVED
  • کوئریqجست‌وجو
  • کوئریcategoryIdشناسه دسته
  • کوئریauthorIdشناسه نویسنده
  • کوئریmineفقط مقالات خودم (true)
  • کوئریsortnewest | oldest | popular
  • کوئریpageشماره صفحه
  • کوئریlimitتعداد در صفحه
پاسخ{ items, total, page, pages }
POST/api/v1/admin/articles

ایجاد مقاله جدید (پیش‌نویس یا انتشار).

پاسخ{ article }
GET/api/v1/admin/articles/{id}

جزئیات کامل مقاله شامل بازبینی‌ها و کلیدواژه‌ها.

پارامترها

  • مسیرid*شناسه مقاله
پاسخ{ article }
PATCH/api/v1/admin/articles/{id}

ویرایش مقاله (نسخه قدیمی به‌صورت خودکار بایگانی می‌شود).

پارامترها

  • مسیرid*شناسه مقاله
پاسخ{ article }
DELETE/api/v1/admin/articles/{id}

حذف مقاله.

پارامترها

  • مسیرid*شناسه مقاله
پاسخ{ ok: true }
POST/api/v1/admin/articles/bulk

عملیات گروهی روی مقاله‌ها (انتشار، آمازه، بایگانی، حذف).

پارامترها

  • بدنهids*آرایه شناسه‌ها
  • بدنهaction*publish | ready | archive | delete
پاسخ{ count }
GET/api/v1/admin/glossary

فهرست همه واژه‌ها (منتشر + پیش‌نویس) با فیلتر و صفحه‌بندی.

پارامترها

  • کوئریqجست‌وجو
  • کوئریstatusPUBLISHED | DRAFT
  • کوئریcategoryIdشناسه دسته
  • کوئریpageشماره صفحه
  • کوئریlimitتعداد در صفحه
پاسخ{ items, total, page, pages }
POST/api/v1/admin/glossary

ایجاد واژه جدید؛ اسلاگ تکراری → 409 SLUG_IN_USE.

پاسخ{ term }
GET/api/v1/admin/glossary/{id}

جزئیات کامل واژه برای ویرایش.

پارامترها

  • مسیرid*شناسه واژه
پاسخ{ term }
PATCH/api/v1/admin/glossary/{id}

ویرایش واژه.

پارامترها

  • مسیرid*شناسه واژه
پاسخ{ term }
DELETE/api/v1/admin/glossary/{id}

حذف واژه.

پارامترها

  • مسیرid*شناسه واژه
پاسخ{ ok: true }
GET/api/v1/admin/glossary/term-of-day

نامک واژهٔ پین‌شده برای «واژهٔ امروز» صفحهٔ اصلی (null = چرخش روزانه خودکار).

پاسخ{ slug }
POST/api/v1/admin/glossary/term-of-day

تعیین یا پاک‌کردن واژهٔ روز صفحهٔ اصلی؛ واژه باید منتشرشده باشد.

پارامترها

  • بدنهslug*نامک واژه یا null برای پاک‌کردن
پاسخ{ slug }
GET/api/v1/admin/series

همهٔ مجموعه‌ها (شامل پیش‌نویس‌ها) + قسمت‌های هر مجموعه با وضعیت انتشار.

پاسخ{ items }
POST/api/v1/admin/series

ایجاد مجموعه؛ orderedArticleIds قسمت‌ها را به‌ترتیب مشخص تخصیص می‌دهد (شماره‌گذاری ۱-مبنا).

پاسخ{ series }
GET/api/v1/admin/series/{id}

جزئیات مجموعه برای ویرایش.

پارامترها

  • مسیرid*شناسه مجموعه
پاسخ{ series }
PATCH/api/v1/admin/series/{id}

ویرایش مجموعه؛ orderedArticleIds کل ترتیب را بازنویسی می‌کند (مقالات حذف‌شده از فهرست، از مجموعه جدا می‌شوند).

پارامترها

  • مسیرid*شناسه مجموعه
پاسخ{ series }
DELETE/api/v1/admin/series/{id}

حذف مجموعه؛ مقاله‌های مجموعه حذف نمی‌شوند و فقط جدا می‌شوند.

پارامترها

  • مسیرid*شناسه مجموعه
پاسخ{ ok: true }
GET/api/v1/admin/categories

درخت کامل دسته‌ها + آمار مقالات هر دسته.

پاسخ{ items }
POST/api/v1/admin/categories

ایجاد دسته/زیردسته؛ حذفِ وابسته‌ها → 409 HAS_DEPENDENCIES.

پاسخ{ category }
GET/api/v1/admin/tags

فهرست برچسب‌ها.

پاسخ{ items }
POST/api/v1/admin/tags

ایجاد برچسب جدید.

پاسخ{ tag }
GET/api/v1/admin/authors

فهرست پروفایل نویسندگان.

پاسخ{ items }
POST/api/v1/admin/authors

ایجاد پروفایل نویسنده.

پاسخ{ author }
GET/api/v1/admin/media

کتابخانه رسانه (تصاویر) با آمار مصرف.

پاسخ{ items }
POST/api/v1/admin/media

بارگذاری رسانه (multipart/form-data).

پاسخ{ asset }
GET/api/v1/admin/pages

فهرست صفحات ثابت.

پاسخ{ items }
POST/api/v1/admin/pages

ایجاد صفحه ثابت.

پاسخ{ page }
GET/api/v1/admin/users

فهرست کاربران تیم (SUPER_ADMIN فقط).

پاسخ{ items }
POST/api/v1/admin/users

ایجاد کاربر جدید با نقش.

پاسخ{ user }
GET/api/v1/admin/settings

همه تنظیمات (شامل مقادیر فعلی؛ رازها قابل‌نوشتن فقط).

پاسخ{ items }
PATCH/api/v1/admin/settings

به‌روزرسانی دسته‌ای تنظیمات؛ مقدار خالی = بدون تغییر.

پاسخ{ items }
GET/api/v1/admin/ads

فهرست تبلیغ‌ها + جایگاه‌ها + نرخ کلیک.

پاسخ{ items, placements }
POST/api/v1/admin/ads

ایجاد تبلیغ.

پاسخ{ ad }
POST/api/v1/admin/ai-generate

مولد مقاله با هوش مصنوعی (سمت سرور). action=generate → پیش‌نویس کامل فارسی (عنوان، چکیده، سئو، متن ۶۰۰-۹۰۰ کلمه‌ای) بدون ذخیره؛ action=save → ذخیره پیش‌نویس قبلی به‌عنوان مقاله DRAFT با یادداشت «نیازمند بازبینی انسانی». هیچ انتشار خودکار وجود ندارد. نیازمند ARTICLE_CREATE.

پارامترها

  • بدنهaction*generate یا save
  • بدنهtopic*موضوع مقاله (۵ تا ۲۰۰ نویسه)
  • بدنهcategorySlug*اسلاگ دستهٔ اصلی
  • بدنهsubcategorySlugاسلاگ زیردسته (اختیاری)
  • بدنهaudienceمخاطب هدف (اختیاری)
  • بدنهtoneلحن: آموزشی / صمیمی / رسمی / تحلیلی
  • بدنهkeywordsکلمات کلیدی (اختیاری)
  • بدنهdraftفقط برای action=save: شیء پیش‌نویس دریافتی از generate
پاسخgenerate → { ok, draft } · save → { ok, savedId, slug }
GET/api/v1/admin/telegram

پیکربندی ربات تلگرام (توکن ماسک‌شده)، وضعیت ۱۲ رویداد اعلان و ۳۰ گزارش آخر. نیازمند SETTINGS_MANAGE.

پاسخ{ config, events, logs }
PUT/api/v1/admin/telegram

ذخیره پیکربندی ربات؛ توکن به‌صورت رمزنگاری‌شده نگهداری می‌شود (botToken=null → حذف؛ خالی = حفظ توکن فعلی). حداکثر ۵ شناسه گیرنده.

پارامترها

  • بدنهisActiveفعال بودن اعلان‌ها
  • بدنهbotTokenتوکن جدید یا null برای حذف
  • بدنهchatIdsآرایه شناسه گیرنده‌ها (حداکثر ۵)
پاسخ{ success }
PATCH/api/v1/admin/telegram

فعال/غیرفعال‌کردن یک رویداد اعلان.

پارامترها

  • بدنهkey*کلید رویداد (مثل ARTICLE_PUBLISHED)
  • بدنهisEnabled*وضعیت رویداد
پاسخ{ event }
POST/api/v1/admin/telegram

action=test-connection → اعتبارسنجی توکن با getMe تلگرام (توکن تست‌شدهٔ موفق خودکار ذخیره می‌شود)؛ action=send-test → ارسال پیام آزمایشی به گیرنده‌ها.

پارامترها

  • بدنهaction*test-connection | send-test
  • بدنهbotTokenتوکن ذخیره‌نشده برای تست (اختیاری)
پاسخ{ ok, botUsername?, error? }
GET/api/v1/admin/footer-links

همهٔ لینک‌های فوتر + فهرست ستون‌ها (pages/explore/company/legal).

پاسخ{ items, columns }
POST/api/v1/admin/footer-links

ایجاد لینک فوتر؛ آدرس باید داخلی (#/… یا /…) یا خارجی امن http(s) باشد — isExternal در سرور تشخیص داده می‌شود.

پاسخ201 { link }
GET/api/v1/admin/social-links

همهٔ لینک‌های شبکه‌های اجتماعی + پلتفرم‌های مجاز.

پاسخ{ items, platforms }
POST/api/v1/admin/social-links

ثبت شبکه اجتماعی؛ پلتفرم یکتا است (تکرار → badRequest) و آدرس فقط https.

پارامترها

  • بدنهplatform*telegram | instagram | twitter | …
پاسخ201 { link }
GET/api/v1/admin/partner-links

لینک‌های همکاری و حمایت (با نوع همکاری، rel و بازه نمایش).

پاسخ{ items }
POST/api/v1/admin/partner-links

ثبت لینک همکاری؛ دامنه از آدرس استخراج می‌شود و rel برای لینک‌های پولی باید sponsored باشد.

پارامترها

  • بدنهcooperationTypeSPONSORED | EXCHANGE | AFFILIATE | FRIENDLY
  • بدنهrelsponsored | nofollow | nofollow sponsored (پیش‌فرض sponsored)
پاسخ201 { link }
GET/api/v1/admin/contact-channels

کانال‌های دکمه شناور تماس + انواع مجاز کانال.

پاسخ{ items, kinds }
POST/api/v1/admin/contact-channels

ایجاد کانال تماس؛ اعتبارسنجی مقدار بر اساس نوع (صفحه داخلی / ایمیل / آدرس وب).

پارامترها

  • بدنهkind*PAGE | EMAIL | TELEGRAM | WHATSAPP | PHONE | WEBSITE
پاسخ201 { channel }
GET/api/v1/admin/redirects

فهرست تغییر مسیرها.

پاسخ{ items }
POST/api/v1/admin/redirects

ایجاد تغییر مسیر (ایمن در برابر حلقه).

پاسخ{ redirect }
GET/api/v1/admin/messages

صندوق پیام‌های تماس + شمارش ناخوانده.

پاسخ{ items, total, unread, page, pages }
GET/api/v1/admin/learning-paths

فهرست مسیرهای یادگیری.

پاسخ{ items }
POST/api/v1/admin/learning-paths

ایجاد مسیر یادگیری.

پاسخ{ path }
GET/api/v1/admin/audit-logs

گزارش رخدادهای مدیریتی با فیلتر.

پاسخ{ items, total, page, pages }
PATCH/api/v1/admin/{resource}/{id}

الگوی مشترک ویرایش برای دسته‌ها، برچسب‌ها، نویسندگان، صفحات، تبلیغ‌ها، تغییر مسیرها، مسیرها، کاربران و پیام‌ها — بدنه فیلدهای همان منبع.

پارامترها

  • مسیرid*شناسه منبع
پاسخ{ resource }
DELETE/api/v1/admin/{resource}/{id}

الگوی مشترک حذف برای همه منابع مدیریتی.

پارامترها

  • مسیرid*شناسه منبع
پاسخ{ ok: true }