# تعدیل قیمت

> فهرست رویدادهای تعدیل قیمت هر نماد (افزایش سرمایه و سود نقدی) در API روشا و روش محاسبهٔ ضریب تعدیل از روی close_adjusted و close_unadjusted.
> Source: https://poolick.ir/docs/api/adjustments/

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

## پارامترها

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

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

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

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

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

```json
[
  {"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}
]
```

```json
[
  {"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` خام همان روز را از [سابقهٔ روزانه](/docs/api/daily/) بگیرید. اگر با `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 به کارم می‌آید؟

- **علامت‌زدن رویدادها روی نمودار:** تاریخ هر افزایش سرمایه یا تقسیم سود را روی نمودار قیمت نشان دهید.
- **تشخیص تغییر سابقهٔ تعدیل‌شده:** اگر تعداد رویدادها بیشتر شد، قیمت‌های تعدیل‌شدهٔ ذخیره‌شدهٔ شما کهنه شده است و باید دوباره گرفته شود. کد در [همگام‌سازی روزانه](/docs/guides/daily-sync/).
- **تعدیل با قاعدهٔ خودتان:** سابقهٔ خام و رویدادها را بگیرید و ضریب را خودتان اعمال کنید. برای رسیدن به همان اعداد `adjusted=true`، شرط روز رویداد را هم رعایت کنید.

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

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