تاریخ شمسی (جلالی) چیست؟

در API روشا: jdate

تقویم رسمی ایران هجری شمسی است که در برنامه‌نویسی به آن «جلالی» هم می‌گویند. سال با نوروز شروع می‌شود. شش ماه اول ۳۱ روز، پنج ماه بعد ۳۰ روز و اسفند ۲۹ یا ۳۰ روز دارد. سال مالی بیشتر شرکت‌ها، گزارش‌ها و گفت‌وگوی روزمرهٔ بازار همه با این تقویم است.

چرا در کد دردسر دارد؟

بیشتر زبان‌ها و پایگاه‌های داده فقط تقویم میلادی را می‌شناسند. اگر تاریخ شمسی را به‌صورت متن ذخیره کنید، محاسبهٔ فاصلهٔ دو روز، روز هفته و مرتب‌سازی درست، همه کار دستی می‌خواهد. تبدیل دستی هم در سال‌های کبیسه جای خطاست. روش رایج این است: میلادی ذخیره کنید، شمسی نمایش بدهید.

روشا چه می‌کند؟

• ورودی آزاد. پارامترهای تاریخ سه قالب را می‌پذیرند: 2026-11-11، 20261111 و شمسی 1405-08-20. قالب دیگر پاسخ 422 می‌گیرد.
• خروجی میلادی ISO. همهٔ تاریخ‌های پاسخ در فیلد d میلادی هستند.
• jdate در ردیف‌های روزانهٔ سهام. لازم نیست خودتان تبدیل کنید.
• زمان‌ها به وقت تهران. برچسب‌های زمانی ISO 8601 با اختلاف +03:30 هستند.

درخواست با تاریخ شمسی:

curl "https://poolick.ir/v1/instruments/46348559193224090/daily?start=1405-08-18&end=1405-08-20" \
  -H "Authorization: Bearer $ROSHA_KEY"

هر ردیف پاسخ هر دو تاریخ را دارد:

{"d":"2026-11-11","close":4950.0,"jdate":"1405-08-20"}

jdate فقط در سابقهٔ روزانهٔ نمادها هست. شاخص‌ها، صندوق‌ها و حقیقی و حقوقی فقط d دارند. برای آن‌ها تبدیل را در کد خود انجام بدهید؛ در پایتون کتابخانه‌هایی مثل jdatetime این کار را می‌کنند. فایل‌های CSV رایگان سایت ستون jalali_date دارند.

یک نکته برای تشخیص خودکار: سال کوچک‌تر از ۱۷۰۰ شمسی فرض می‌شود. قالب هشت‌رقمی بدون خط تیره فقط میلادی است؛ تاریخ شمسی را با خط تیره بفرستید. جزئیات در قراردادها و تقویم معاملاتی هر سال در صفحهٔ تقویم است.