# صندوق‌ها

> پنج endpoint صندوق‌های سرمایه‌گذاری در API روشا؛ فهرست، انواع، شناسنامه، سابقهٔ روزانهٔ NAV و snapshot زیرصندوق‌ها، با شرح صندوق‌های چتری.
> Source: https://poolick.ir/docs/api/funds/

روشا دادهٔ همهٔ صندوق‌های سرمایه‌گذاری ثبت‌شده نزد سازمان بورس را از فیپیران (FIPIran) می‌گیرد، از جمله صندوق‌های صدور و ابطالی که در بورس معامله نمی‌شوند. در ۲۲ آبان ۱۴۰۵ این داده ۶۱۷ صندوق زیر ۵۹۵ شمارهٔ ثبت را پوشش می‌داد.

| endpoint | کاربرد | خانواده |
|---|---|---|
| `GET /v1/funds` | فهرست و جست‌وجوی صندوق‌ها با آخرین ارقام | همیشه مجاز |
| `GET /v1/funds/types` | کد و نام انواع صندوق | همیشه مجاز |
| `GET /v1/funds/{ref}` | شناسنامه، زیرصندوق‌ها، آخرین ارقام و سودهای تقسیمی | همیشه مجاز |
| `GET /v1/funds/{ref}/history` | سابقهٔ روزانه در سطح شمارهٔ ثبت | `history` |
| `GET /v1/funds/{ref}/snapshots` | ارقام روزانهٔ هر زیرصندوق | `history` |

## صندوق چطور شناسایی می‌شود؟

شناسهٔ صندوق شمارهٔ ثبت آن نزد سازمان بورس است (`reg_no`). در مسیرها به‌جای `{ref}` می‌توانید شمارهٔ ثبت (`10589`)، نماد صندوق (`عیار`)، نام دقیق صندوق، یا `insCode` صندوق قابل معامله در TSETMC را بفرستید.

## صندوق چتری چیست و چه فرقی دارد؟

صندوق چتری زیر یک شمارهٔ ثبت چند زیرصندوق دارد که هر کدام `group_id`، نماد و NAV خودش را دارد. تا آبان ۱۴۰۵، ۱۵ صندوق چتری در داده هست؛ نمونه‌اش شمارهٔ ثبت `12181` با سه زیرصندوق.

- `group_id` برای صندوق عادی `0` یا `1` است و برای زیرصندوق‌های چتری از `2` به بالا.
- **سابقهٔ `/history` در سطح شمارهٔ ثبت است و با NAV هیچ‌کدام از زیرصندوق‌ها یکی نیست.**
- ارقام هر زیرصندوق فقط در `/snapshots` است و از آبان ۱۴۰۵ (نوامبر ۲۰۲۶) به بعد گردآوری شده است.

نمونه برای `12181` در روز `2026-11-10`: `cancel_nav` در `/history` برابر `43448.0` است، ولی سه زیرصندوق در `/snapshots` مقدارهای `49778.0`، `49156.0` و `35756.0` دارند.

## فهرست صندوق‌ها را چطور بگیرم؟

`GET /v1/funds` صندوق‌ها را با آخرین ارقام منتشرشده برمی‌گرداند، به ترتیب بزرگ‌ترین خالص ارزش دارایی.

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `q` | رشته | – | جست‌وجو در نام، نماد، مدیر، شمارهٔ ثبت یا `insCode` |
| `fund_type` | عدد صحیح | – | کد نوع صندوق؛ فهرست کدها در `/v1/funds/types` |
| `active` | بولی | `true` | `true` فقط صندوق‌های فعال؛ `false` همه |
| `limit` | عدد صحیح | `50` | تعداد در هر صفحه، از `1` تا `500` |
| `offset` | عدد صحیح | `0` | تعداد ردیف‌هایی که از ابتدای فهرست رد می‌شود |

```bash
curl -G "https://poolick.ir/v1/funds" \
  --data-urlencode "q=عیار" -d "limit=1" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

```json
{
  "total": 7,
  "items": [
    {
      "reg_no": "11586",
      "group_id": 0,
      "name": "عیار مفید",
      "symbol": "عیار",
      "fund_type": 5,
      "fund_type_name": "در اوراق بهادار مبتنی بر سپرده کالایی",
      "type_of_invest": "Negotiable",
      "ins_code": "34144395039913458",
      "is_market_maker": false,
      "manager": "سبدگردان مفید",
      "active": true,
      "last_date": "2026-11-10",
      "latest": {
        "d": "2026-11-10",
        "issue_nav": 681204.0,
        "cancel_nav": 678122.0,
        "statistical_nav": 678122.0,
        "net_asset": 3639858989400398.0,
        "invested_units": 5367559896.0,
        "ret_1d": 0.46,
        "ret_1w": -0.62,
        "ret_1m": -5.53,
        "ret_3m": 31.41,
        "ret_6m": 25.65,
        "ret_1y": 130.77,
        "ret_inception": 6681.22,
        "top_five": 0.0,
        "equity": 0.0,
        "bond": 0.46,
        "cash": 0.0,
        "deposit": 0.0,
        "other": 0.0
      }
    }
  ]
}
```

`total` تعداد همهٔ صندوق‌های منطبق است، نه تعداد اعضای `items`. برای صفحهٔ بعد `offset` را به اندازهٔ `limit` زیاد کنید. هر زیرصندوقِ صندوق چتری یک عضو جدا در `items` است.

### فیلدهای مشخصات صندوق

| فیلد | نوع | معنا |
|---|---|---|
| `reg_no` | رشته | شمارهٔ ثبت نزد سازمان بورس |
| `group_id` | عدد صحیح | `0` یا `1` برای صندوق عادی؛ `2` به بالا برای زیرصندوق چتری |
| `name` | رشته | نام صندوق |
| `symbol` | رشته یا `null` | نماد صندوق؛ صندوق‌های صدور و ابطالی معمولاً نماد ندارند |
| `fund_type` | عدد صحیح | کد نوع صندوق |
| `fund_type_name` | رشته | نام نوع صندوق |
| `type_of_invest` | رشته | `Negotiable` یعنی قابل معامله در بورس؛ `IssuanceAndCancellation` یعنی صدور و ابطالی |
| `ins_code` | رشته یا `null` | شناسهٔ TSETMC برای صندوق قابل معامله |
| `is_market_maker` | بولی | آیا صندوق بازارگردانی است |
| `manager` | رشته | مدیر صندوق |
| `active` | بولی | آیا صندوق فعال است |
| `last_date` | تاریخ یا `null` | تاریخ آخرین ارقام منتشرشده |
| `latest` | شیء یا `null` | آخرین ارقام؛ جدول بعد |

### فیلدهای `latest` و ردیف‌های snapshot

| فیلد | واحد | معنا |
|---|---|---|
| `d` | میلادی ISO | روز ارقام |
| `issue_nav` | ریال | NAV صدور هر واحد |
| `cancel_nav` | ریال | NAV ابطال هر واحد |
| `statistical_nav` | ریال | NAV آماری هر واحد |
| `net_asset` | ریال | خالص ارزش دارایی صندوق |
| `invested_units` | واحد | تعداد واحدهای سرمایه‌گذاری |
| `ret_1d`، `ret_1w`، `ret_1m`، `ret_3m`، `ret_6m`، `ret_1y` | درصد | بازده یک‌روزه، هفتگی، یک‌ماهه، سه‌ماهه، شش‌ماهه و یک‌ساله |
| `ret_inception` | درصد | بازده از آغاز فعالیت |
| `top_five` | درصد | سهم پنج سهم بزرگ از دارایی |
| `equity` | درصد | سهم کل سهام از دارایی، **شامل** `top_five` |
| `bond` | درصد | سهم اوراق |
| `cash` | درصد | سهم وجه نقد |
| `deposit` | درصد | سهم سپرده |
| `other` | درصد | سهم سایر دارایی‌ها |

فیپیران `equity` را در گزارش‌های مختلف به دو شکل منتشر می‌کند؛ روشا آن را یکدست کرده است تا همیشه پنج سهم بزرگ را در بر داشته باشد.

## انواع صندوق چه کدهایی دارند؟

`GET /v1/funds/types` بدون پارامتر، کد و نام فارسی همهٔ انواع صندوق را برمی‌گرداند.

```bash
curl "https://poolick.ir/v1/funds/types" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

```json
[
  {"fund_type": 0, "name": "نامشخص"},
  {"fund_type": 4, "name": "در اوراق بهادار با درآمد ثابت"},
  {"fund_type": 5, "name": "در اوراق بهادار مبتنی بر سپرده کالایی"},
  {"fund_type": 6, "name": "در سهام"},
  {"fund_type": 7, "name": "مختلط"},
  {"fund_type": 11, "name": "اختصاصی بازارگردانی"},
  {"fund_type": 12, "name": "جسورانه"},
  {"fund_type": 13, "name": "پروژه‌ای"},
  {"fund_type": 14, "name": "زمین و ساختمان"},
  {"fund_type": 16, "name": "خصوصی"},
  {"fund_type": 17, "name": "صندوق در صندوق"},
  {"fund_type": 18, "name": "املاک و مستغلات"},
  {"fund_type": 19, "name": "لغو مجوز تاسیس و فعالیت"},
  {"fund_type": 21, "name": "در سهام-بخشی"},
  {"fund_type": 22, "name": "در سهام-سهامی اهرمی"},
  {"fund_type": 23, "name": "در سهام-شاخصی"},
  {"fund_type": 24, "name": "با تضمین اصل مبلغ سرمایه گذاری"},
  {"fund_type": 25, "name": "بازنشستگی تکمیلی"}
]
```

کدهای پرکاربرد: `4` درآمد ثابت، `5` سپردهٔ کالایی، `6` سهامی، `7` مختلط، `11` بازارگردانی، `21` بخشی، `22` اهرمی، `23` شاخصی. نام‌ها همان‌طور که فیپیران منتشر می‌کند برمی‌گردند.

## شناسنامهٔ یک صندوق را چطور بگیرم؟

`GET /v1/funds/{ref}` شناسنامهٔ صندوق، آخرین ارقام هر (زیر)صندوق، بازهٔ سابقهٔ موجود و سودهای تقسیمی را برمی‌گرداند.

```bash
curl "https://poolick.ir/v1/funds/10589" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

```json
{
  "reg_no": "10589",
  "groups": [
    {
      "reg_no": "10589",
      "group_id": 1,
      "name": "مشترک پویا",
      "symbol": null,
      "fund_type": 6,
      "fund_type_name": "در سهام",
      "type_of_invest": "IssuanceAndCancellation",
      "ins_code": null,
      "is_market_maker": false,
      "manager": "سبد گردان امید نهایت نگر",
      "active": true,
      "last_date": "2026-11-01",
      "auditor": "موسسه حسابرسی رازدار",
      "custodian": "مشاور سرمایه گذاری سهم آشنا",
      "guarantor": null,
      "investment_manager": "فاطمه فیاض بخش، سمانه دهقان منکابادی، مهدی کارنامه حقیقی",
      "websites": ["iran-funds.com"],
      "initiation_date": "2008-03-24",
      "national_id": "10320819954",
      "registration_number": "29966",
      "legal_pct": 2.0,
      "natural_pct": 98.0,
      "licenses": [
        {
          "id": 5646939,
          "regNo": "10589",
          "isExpired": false,
          "licenseNo": "122/147830",
          "startDate": "2008-03-24T00:00:00",
          "expireDate": "2027-03-24T00:00:00",
          "licenseTypeId": 23,
          "licenseStatusId": 1
        }
      ],
      "latest": {
        "d": "2026-11-01",
        "issue_nav": 9440322.0,
        "cancel_nav": 9337283.0,
        "statistical_nav": 9337283.0,
        "net_asset": 3877223107220.0,
        "invested_units": 415241.0,
        "ret_1d": -1.8,
        "ret_1w": -3.73,
        "ret_1m": 2.35,
        "ret_3m": 40.61,
        "ret_6m": 124.1,
        "ret_1y": 151.25,
        "ret_inception": 93192.51,
        "top_five": 30.65,
        "equity": 94.31,
        "bond": 0.0,
        "cash": 0.05,
        "deposit": 4.08,
        "other": 1.45
      }
    }
  ],
  "history": {"from": "2013-09-29", "to": "2026-11-10", "days": 4791},
  "dividends": [{"d": "2022-12-17", "value": 191406105.0}]
}
```

| فیلد | معنا |
|---|---|
| `reg_no` | شمارهٔ ثبتی که `ref` به آن رسید |
| `groups` | یک عضو برای هر صندوق یا زیرصندوق، به ترتیب `group_id`. صندوق عادی یک عضو دارد. |
| `groups[].auditor` | حسابرس |
| `groups[].custodian` | متولی |
| `groups[].guarantor` | ضامن؛ اگر نباشد `null` |
| `groups[].investment_manager` | مدیران سرمایه‌گذاری |
| `groups[].websites` | تارنماهای صندوق |
| `groups[].initiation_date` | تاریخ آغاز فعالیت |
| `groups[].national_id` | شناسهٔ ملی |
| `groups[].registration_number` | شمارهٔ ثبت دیگری که فیپیران برای صندوق منتشر می‌کند. شناسهٔ صندوق در روشا نیست؛ شناسه `reg_no` است. |
| `groups[].legal_pct`، `groups[].natural_pct` | سهم سرمایه‌گذاران حقوقی و حقیقی، به درصد |
| `groups[].licenses` | مجوزهای سازمان بورس، همان‌طور که فیپیران منتشر می‌کند |
| `groups[].latest` | آخرین ارقام همان (زیر)صندوق، با فیلدهای جدول بالا |
| `history` | بازهٔ سابقهٔ ذخیره‌شده: اولین روز، آخرین روز و تعداد روزها |
| `dividends` | سودهای تقسیمی، از جدید به قدیم؛ `value` به ریال برای هر واحد |

:::note
`latest` از گزارش مقایسه‌ای فیپیران می‌آید و برای صندوق‌هایی که دیر منتشر می‌کنند ممکن است چند روز از سابقه عقب باشد. در نمونهٔ بالا `latest.d` برابر `2026-11-01` است ولی `history.to` برابر `2026-11-10`. برای تازه‌ترین رقم از `/history?limit=1` استفاده کنید.
:::

## سابقهٔ روزانهٔ NAV یک صندوق را چطور بگیرم؟

`GET /v1/funds/{ref}/history` برای هر روز یک ردیف در سطح شمارهٔ ثبت برمی‌گرداند: NAV، خالص دارایی، واحدهای صادر و ابطال‌شده، بازده‌ها، ترکیب دارایی، ترکیب مالکیت و آلفا و بتا.

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `ref` | رشته، در مسیر | – | شمارهٔ ثبت، نماد، نام دقیق یا `insCode` صندوق قابل معامله |
| `start` | تاریخ | بدون حد | اولین روز بازه (خود آن روز هم می‌آید) |
| `end` | تاریخ | بدون حد | آخرین روز بازه (خود آن روز هم می‌آید) |
| `limit` | عدد صحیح | `1000` | N ردیف آخر بازه را نگه می‌دارد. سقف `5000`. |

```bash
curl "https://poolick.ir/v1/funds/10589/history?limit=1" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

```json
{
  "reg_no": "10589",
  "rows": [
    {
      "d": "2026-11-10",
      "issue_nav": 10473184.0,
      "cancel_nav": 10355477.0,
      "statistical_nav": 10355477.0,
      "net_asset": 4299967114450.0,
      "units_subscribed": 0.0,
      "units_redeemed": 0.0,
      "ret_1d": 2.77,
      "ret_1w": 7.93,
      "ret_1m": 8.59,
      "ret_3m": 42.52,
      "ret_6m": 148.76,
      "ret_1y": 191.8,
      "top_five": 29.97,
      "equity": 98.5,
      "bond": 0.0,
      "cash": 0.06,
      "deposit": 0.48,
      "other": 0.86,
      "fund_unit": 0.0,
      "commodity": 0.11,
      "institutional_pct": 19.0,
      "retail_pct": 81.0,
      "alpha": null,
      "beta": null,
      "source": "chart"
    }
  ]
}
```

ردیف‌های سابقه فیلدهای NAV، خالص دارایی، بازده و ترکیب دارایی جدول بالا را دارند (بدون `invested_units` و `ret_inception`) و این فیلدها را اضافه می‌کنند:

| فیلد | واحد | معنا |
|---|---|---|
| `units_subscribed` | واحد | واحدهای صادرشده در آن روز |
| `units_redeemed` | واحد | واحدهای ابطال‌شده در آن روز |
| `fund_unit` | درصد | سهم واحدهای صندوق‌های دیگر از دارایی |
| `commodity` | درصد | سهم کالا از دارایی |
| `institutional_pct` | درصد | سهم سرمایه‌گذاران حقوقی |
| `retail_pct` | درصد | سهم سرمایه‌گذاران حقیقی |
| `alpha` | – | آلفا؛ در ردیف‌های اخیر `null` |
| `beta` | – | بتا؛ در ردیف‌های اخیر `null` |
| `source` | – | `chart` یا `snapshot`؛ توضیح در پایین |

حالت‌های مرزی سابقه:

- **فیلدهای خالی:** همهٔ فیلدها برای همهٔ روزها پر نیست، چون هر سری داده در فیپیران از تاریخ متفاوتی شروع می‌شود. مثلاً ترکیب دارایی فقط سال‌های اخیر را دارد.
- **`source`:** روزهایی که همگام‌سازی ساعتی اضافه کرده `"source": "snapshot"` دارند و فقط NAV، خالص دارایی، بازده‌ها و ترکیب دارایی را دارند. بازسازی هفتگی آن‌ها را با ردیف `"source": "chart"` جایگزین می‌کند که واحدهای صادر و ابطال‌شده، ترکیب مالکیت و آلفا و بتا را هم دارد.
- **آلفا و بتا:** حدود هفت هفته از فیپیران عقب است؛ پس در ردیف‌های اخیر `null` است.
- **صندوق چتری:** این سابقه در سطح شمارهٔ ثبت است و NAV هیچ زیرصندوقی نیست.

## ارقام هر زیرصندوق را چطور بگیرم؟

`GET /v1/funds/{ref}/snapshots` ارقام هر (زیر)صندوق را همان‌طور که هر روز منتشر شده برمی‌گرداند. برای صندوق‌های چتری این تنها سری مختص هر زیرصندوق است.

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `ref` | رشته، در مسیر | – | شمارهٔ ثبت، نماد، نام دقیق یا `insCode` صندوق قابل معامله |
| `group_id` | عدد صحیح | همهٔ زیرصندوق‌ها | فقط ردیف‌های یک زیرصندوق |
| `start` | تاریخ | بدون حد | اولین روز بازه |
| `end` | تاریخ | بدون حد | آخرین روز بازه |
| `limit` | عدد صحیح | `1000` | N ردیف آخر بازه را نگه می‌دارد. سقف `5000`. |

```bash
curl "https://poolick.ir/v1/funds/12181/snapshots?group_id=2&limit=1" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

```json
{
  "reg_no": "12181",
  "rows": [
    {
      "group_id": 2,
      "d": "2026-11-10",
      "issue_nav": 50309.0,
      "cancel_nav": 49778.0,
      "statistical_nav": 49778.0,
      "net_asset": 5483245271425.0,
      "invested_units": 110154999.0,
      "ret_1d": 2.462,
      "ret_1w": 5.728,
      "ret_1m": -0.754,
      "ret_3m": 57.49,
      "ret_6m": 148.468,
      "ret_1y": 254.999,
      "ret_inception": 397.78,
      "top_five": 33.45,
      "equity": 66.9,
      "bond": 0.0,
      "cash": 0.0,
      "deposit": 6.48,
      "other": 0.0
    }
  ]
}
```

هر ردیف `group_id` و فیلدهای جدول `latest` را دارد. ردیف‌ها بر اساس روز از قدیم به جدید مرتب‌اند. بدون `group_id`، هر روز برای هر زیرصندوق یک ردیف دارد و `limit` روی مجموع ردیف‌ها اعمال می‌شود؛ پس برای سری یک زیرصندوق `group_id` را بدهید. `group_id` هر زیرصندوق را از `groups` در `GET /v1/funds/{ref}` بخوانید.

snapshotها از آبان ۱۴۰۵ به بعد گردآوری شده‌اند؛ پیش از آن ردیفی وجود ندارد.

## دادهٔ صندوق‌ها چه زمانی به‌روز می‌شود؟

ارقام روز هر ساعت از ۱۴:۳۰ تا ۲۲:۳۰ تهران تازه می‌شود و سابقهٔ کامل هر هفته بامداد جمعه از نو ساخته می‌شود.

| داده | زمان (وقت تهران) |
|---|---|
| آخرین ارقام (`latest`، `/snapshots` و ردیف تازهٔ `/history`) | هر ساعت از ۱۴:۳۰ تا ۲۲:۳۰، همهٔ روزها |
| سابقهٔ کامل، شناسنامه و سودهای تقسیمی | جمعه ساعت ۰۲:۰۰ |

- فیپیران ارقام را پس از حدود ۱۴:۳۰ منتشر می‌کند و بسیاری از صندوق‌ها دیر منتشر می‌کنند.
- فیپیران ارقام گذشته را اصلاح می‌کند؛ برای همین سابقهٔ کامل هر هفته بازسازی می‌شود. اگر سابقه را در پایگاه دادهٔ خود نگه می‌دارید، هفته‌ای یک بار آن را دوباره بخوانید.

## ابزارهای MCP معادل

`search_funds`، `get_fund_types`، `get_fund` و `get_fund_history`. برای `/snapshots` ابزار MCP وجود ندارد.