# تقویم معاملاتی

> فهرست روزهای معاملاتی بورس تهران در یک بازهٔ تاریخی با GET /v1/calendar در API روشا؛ پارامترهای start و end، نمونهٔ پاسخ و حالت‌های مرزی.
> Source: https://poolick.ir/docs/api/calendar/

`GET /v1/calendar` روزهای معاملاتی یک بازه را به شکل آرایه‌ای از تاریخ‌های میلادی برمی‌گرداند. با آن می‌فهمید یک روز مشخص بازار باز بوده است یا نه. این endpoint در همهٔ پلن‌ها مجاز است.

## پارامترها

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `start` | تاریخ، الزامی | – | اولین روز بازه (خود آن روز هم بررسی می‌شود) |
| `end` | تاریخ، الزامی | – | آخرین روز بازه (خود آن روز هم بررسی می‌شود) |

هر دو پارامتر الزامی‌اند و سه قالب تاریخ را می‌پذیرند: `2026-11-11`، `20261111` و شمسی `1405-08-20`.

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

این درخواست روزهای معاملاتی ۱۰ تا ۲۰ آبان ۱۴۰۵ را با تاریخ شمسی می‌گیرد:

```bash
curl "https://poolick.ir/v1/calendar?start=1405-08-10&end=1405-08-20" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

پاسخ:

```json
["2026-11-01", "2026-11-02", "2026-11-03", "2026-11-04", "2026-11-07", "2026-11-08", "2026-11-09", "2026-11-10", "2026-11-11"]
```

پاسخ آرایه‌ای از رشته‌های تاریخ میلادی ISO است، از قدیم به جدید. در این نمونه `2026-11-05` و `2026-11-06` (پنجشنبه و جمعه) نیستند.

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

- **منبع تقویم:** روزهای معاملاتی از روی روزهایی به دست می‌آیند که دادهٔ بازار دارند. پس تقویم فقط گذشته را پوشش می‌دهد و روزهای آینده در آن نیست.
- **پارامتر جاافتاده:** بدون `start` یا `end` پاسخ `422` با فهرست پارامترهای جاافتاده است.
- **تاریخ نامعتبر:** `422` با `{"detail": "bad date 'bad': use YYYY-MM-DD, YYYYMMDD or Jalali 1403-01-15"}`.
- **بازهٔ بدون روز معاملاتی:** پاسخ `[]` با وضعیت `200`.
- **ابزار MCP معادل:** `get_trading_days`. در MCP هر دو پارامتر اختیاری‌اند و پیش‌فرض، ۳۰ روز اخیر است.