تعدیل قیمت

GET /v1/instruments/{ref}/adjustments همهٔ رویدادهای تعدیل قیمت یک نماد را، از قدیم به جدید، برمی‌گرداند. هر رویداد یک افزایش سرمایه یا تقسیم سود است که TSETMC ثبت کرده است. همین رویدادها مبنای adjusted=true در سابقهٔ روزانه هستند. این endpoint در خانوادهٔ history است.

پارامترها

پارامتر	نوع	پیش‌فرض	معنا
ref	رشته، در مسیر	–	insCode، InstrumentID یا ISIN، یا نماد فارسی دقیق

این endpoint پارامتر start، end و limit ندارد و همیشه همهٔ رویدادها را برمی‌گرداند.

چطور رویدادهای تعدیل یک نماد را بگیرم؟

curl "https://poolick.ir/v1/instruments/46348559193224090/adjustments" \
  -H "Authorization: Bearer $ROSHA_KEY"

پاسخ برای فولاد ۲۳ رویداد دارد (تا آبان ۱۴۰۵). سه رویداد اول و سه رویداد آخر آن:

[
  {"d": "2009-06-23", "close_adjusted": 1522.0, "close_unadjusted": 2122.0},
  {"d": "2010-07-07", "close_adjusted": 1916.0, "close_unadjusted": 2416.0},
  {"d": "2011-02-14", "close_adjusted": 2291.0, "close_unadjusted": 3241.0}
]

[
  {"d": "2024-07-21", "close_adjusted": 4800.0, "close_unadjusted": 5200.0},
  {"d": "2025-08-04", "close_adjusted": 2580.0, "close_unadjusted": 2860.0},
  {"d": "2026-08-03", "close_adjusted": 2549.0, "close_unadjusted": 2604.0}
]

فیلدهای پاسخ

فیلد	نوع	واحد	معنا
d	تاریخ	میلادی ISO	روز رویداد
close_adjusted	عدد	ریال	قیمت پایانی تعدیل‌شده به اعلام TSETMC
close_unadjusted	عدد	ریال	قیمت پایانی تعدیل‌نشدهٔ همان رویداد

ضریب تعدیل چطور حساب می‌شود؟

ضریب هر رویداد برابر close_adjusted ÷ close_unadjusted است و روی هر روزی اعمال می‌شود که هنوز بر مبنای قیمت قدیم است. ضریب‌ها روی هم ضرب می‌شوند.

یک رویداد با تاریخ d این روزها را تغییر می‌دهد:

• همهٔ روزهای پیش از d؛
• خودِ روز d، فقط اگر نماد در آن روز متوقف بوده و هنوز قیمت قدیم را نشان می‌دهد.

برای روز d این‌طور تشخیص دهید: prev_close خام همان روز را از سابقهٔ روزانه بگیرید. اگر با close_adjusted رویداد برابر باشد (با اختلاف حداکثر ۰٫۵ ریال)، روز d از قیمت جدید شروع شده و این رویداد آن را تغییر نمی‌دهد. وگرنه روز d هم در ضریب ضرب می‌شود. در داده‌های TSETMC تا سال ۲۰۱۹ حالت اول و از ۲۰۲۰ حالت دوم رایج است.

applies(event, day) =
    day < event.d
    or (day == event.d and |raw_prev_close(day) − event.close_adjusted| > 0.5)

adjusted_price(day) = raw_price(day) × Π (close_adjusted / close_unadjusted)   for events where applies(event, day)

دو نمونه از فولاد، یکی برای هر حالت:

رویداد	ضریب	prev_close خام روز رویداد	روز رویداد تعدیل می‌شود؟
2019-02-19	2820 ÷ 4888 ≈ 0.577	2820.0، برابر close_adjusted	نه؛ این روز از قیمت جدید شروع شده است
2024-07-21	4800 ÷ 5200 ≈ 0.923	5200.0، برابر قیمت قدیم	بله؛ نماد متوقف بوده و قیمت جدید از ردیف بعد (2024-07-22) شروع می‌شود

در هر دو نمونه، سری تعدیل‌شده در روز رویداد پرش ندارد: قیمت پایانی تعدیل‌شدهٔ 2019-02-18 و 2019-02-19 هر دو 1569.54 ریال است، و قیمت پایانی تعدیل‌شدهٔ 2024-07-20 و 2024-07-21 هر دو 4238.61 ریال.

نمونهٔ کامل: قیمت پایانی خام فولاد در 2014-12-30 برابر 2191 ریال است. هر ۱۴ رویدادِ پس از آن روز این روز را تغییر می‌دهند و حاصل‌ضرب ضریب آن‌ها 0.18278 است، پس قیمت پایانی تعدیل‌شده 2191 × 0.18278 ≈ 400.47 ریال می‌شود؛ همان عددی که adjusted=true برمی‌گرداند.

لازم نیست این محاسبه را خودتان انجام دهید: GET /v1/instruments/{ref}/daily?adjusted=true همین کار را می‌کند.

چه زمانی این endpoint به کارم می‌آید؟

• علامت‌زدن رویدادها روی نمودار: تاریخ هر افزایش سرمایه یا تقسیم سود را روی نمودار قیمت نشان دهید.
• تشخیص تغییر سابقهٔ تعدیل‌شده: اگر تعداد رویدادها بیشتر شد، قیمت‌های تعدیل‌شدهٔ ذخیره‌شدهٔ شما کهنه شده است و باید دوباره گرفته شود. کد در همگام‌سازی روزانه.
• تعدیل با قاعدهٔ خودتان: سابقهٔ خام و رویدادها را بگیرید و ضریب را خودتان اعمال کنید. برای رسیدن به همان اعداد adjusted=true، شرط روز رویداد را هم رعایت کنید.

نکته‌ها و حالت‌های مرزی

• نماد بدون رویداد: پاسخ فهرست خالی [] است و adjusted=true برای آن نماد همان قیمت خام را می‌دهد.
• حجم: تعدیل فقط روی قیمت است. حجم و ارزش معاملات تعدیل نمی‌شود.
• زمان تازه‌شدن: رویدادها با دادهٔ پایان روز، ساعت ۱۸:۱۵ تهران، شنبه تا چهارشنبه، تازه می‌شوند.
• MCP: ابزار جدایی برای رویدادهای تعدیل نیست. get_daily_history با adjusted=true قیمت تعدیل‌شده می‌دهد.