# نمادها

> جست‌وجوی نماد و شاخص و گرفتن مشخصات یک نماد در API روشا؛ پارامترها، نمونهٔ پاسخ واقعی و شرح فیلدهایی مثل ins_code، flow و is_index.
> Source: https://poolick.ir/docs/api/instruments/

دو endpoint نماد به شما می‌گویند یک نماد یا شاخص چه شناسه‌هایی دارد: `GET /v1/instruments` جست‌وجو می‌کند و `GET /v1/instruments/{ref}` مشخصات یک نماد را برمی‌گرداند. هر دو در همهٔ پلن‌ها مجازند.

## چطور یک نماد را جست‌وجو کنم؟

`GET /v1/instruments?q=<متن>` در نماد، نام، InstrumentID، ISIN و نماد لاتین جست‌وجوی جزئی (substring) می‌کند و فهرستی از نمادها برمی‌گرداند.

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `q` | رشته، الزامی | – | متن جست‌وجو، دست‌کم یک نویسه. «ي» و «ك» عربی یکسان‌سازی می‌شود. |
| `limit` | عدد صحیح | `20` | حداکثر تعداد نتیجه. سقف `100`. |

درخواست:

```bash
curl -G "https://poolick.ir/v1/instruments" \
  --data-urlencode "q=فولاد" -d "limit=2" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

پاسخ:

```json
[
  {
    "ins_code": "46348559193224090",
    "ticker": "فولاد",
    "name": "فولاد مبارکه اصفهان",
    "instrument_id": "IRO1FOLD0001",
    "isin": "IRO1FOLD0009",
    "ticker_latin": "FOLD1",
    "name_latin": "S*Mobarakeh Steel",
    "company_name": "فولاد مبارکه اصفهان",
    "flow": 1,
    "y_val": 300,
    "market_code": "NO",
    "group_code": "N1",
    "sector_code": 27,
    "sub_sector_code": 2710,
    "base_volume": 1,
    "shares_outstanding": 1935000000000.0,
    "is_index": false,
    "active": true,
    "first_trade_date": "2007-03-11",
    "last_trade_date": "2026-11-11"
  },
  {
    "ins_code": "56871139881800017",
    "ticker": "توسکا",
    "name": "صندوق س توسعه فولاد- ثابت",
    "instrument_id": "IRT1TSCA0001",
    "isin": "IRT1TSCA0002",
    "ticker_latin": "TSCA1",
    "name_latin": "TOSCA ETF",
    "company_name": "صندوق س توسعه فولاد- ثابت",
    "flow": 1,
    "y_val": 305,
    "market_code": "NO",
    "group_code": "H1",
    "sector_code": 68,
    "sub_sector_code": 6812,
    "base_volume": 1,
    "shares_outstanding": 6600000000.0,
    "is_index": false,
    "active": true,
    "first_trade_date": "2026-11-01",
    "last_trade_date": "2026-11-11"
  }
]
```

ترتیب نتیجه‌ها: ابتدا نمادی که دقیقاً برابر `q` است، سپس نمادهای فعال، سپس بازار اصلی، سپس بورس پیش از فرابورس. اگر چیزی پیدا نشود، پاسخ فهرست خالی `[]` با وضعیت `200` است.

## چطور مشخصات یک نماد را بگیرم؟

`GET /v1/instruments/{ref}` همان شیء جست‌وجو را برای یک نماد برمی‌گرداند و `sector_name` (نام گروه صنعت) را به آن اضافه می‌کند.

| پارامتر | نوع | پیش‌فرض | معنا |
|---|---|---|---|
| `ref` | رشته، در مسیر | – | `insCode`، InstrumentID یا ISIN، یا نماد فارسی دقیق. شرح در [قراردادها](/docs/conventions/). |

درخواست:

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

پاسخ:

```json
{
  "ins_code": "46348559193224090",
  "ticker": "فولاد",
  "name": "فولاد مبارکه اصفهان",
  "instrument_id": "IRO1FOLD0001",
  "isin": "IRO1FOLD0009",
  "ticker_latin": "FOLD1",
  "name_latin": "S*Mobarakeh Steel",
  "company_name": "فولاد مبارکه اصفهان",
  "flow": 1,
  "y_val": 300,
  "market_code": "NO",
  "group_code": "N1",
  "sector_code": 27,
  "sub_sector_code": 2710,
  "base_volume": 1,
  "shares_outstanding": 1935000000000.0,
  "is_index": false,
  "active": true,
  "first_trade_date": "2007-03-11",
  "last_trade_date": "2026-11-11",
  "sector_name": "فلزات اساسی"
}
```

اگر `ref` به نمادی نخورد، پاسخ `404` با `{"detail": "instrument not found: xyz123"}` است.

## فیلدهای نماد

| فیلد | نوع | معنا |
|---|---|---|
| `ins_code` | رشته | شناسهٔ نماد در TSETMC (`insCode`). همیشه متن نگهش دارید. |
| `ticker` | رشته | نماد فارسی، مثل `فولاد` |
| `name` | رشته | نام نماد |
| `instrument_id` | رشته یا `null` | کد ۱۲ نویسه‌ای InstrumentID، مثل `IRO1FOLD0001` |
| `isin` | رشته یا `null` | کد ISIN |
| `ticker_latin` | رشته یا `null` | نماد لاتین |
| `name_latin` | رشته یا `null` | نام لاتین |
| `company_name` | رشته یا `null` | نام شرکت |
| `flow` | عدد صحیح | بازار: `1` بورس، `2` فرابورس، `3` مشتقه، `4` بازار پایهٔ فرابورس، `6` بورس انرژی، `7` بورس کالا |
| `y_val` | عدد صحیح یا `null` | کد نوع ابزار در TSETMC. در نمونهٔ بالا `300` سهم و `305` صندوق قابل معامله است. |
| `market_code` | رشته یا `null` | کد بازار در TSETMC |
| `group_code` | رشته یا `null` | کد گروه در TSETMC |
| `sector_code` | عدد صحیح یا `null` | کد گروه صنعت |
| `sub_sector_code` | عدد صحیح یا `null` | کد زیرگروه صنعت |
| `base_volume` | عدد یا `null` | حجم مبنا |
| `shares_outstanding` | عدد یا `null` | تعداد سهام |
| `is_index` | بولی | `true` اگر این ردیف یک شاخص باشد |
| `active` | بولی | آیا نماد فعال است |
| `first_trade_date` | تاریخ یا `null` | اولین روز معاملاتی موجود |
| `last_trade_date` | تاریخ یا `null` | آخرین روز معاملاتی موجود |
| `sector_name` | رشته یا `null` | نام گروه صنعت. فقط در `GET /v1/instruments/{ref}` و فقط برای نمادی که `sector_code` دارد. |

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

- **فیلدهای خالی:** `isin`، نام‌های لاتین و `company_name` با همگام‌سازی هفتگی هویت نمادها (پنجشنبه ساعت ۰۳:۰۰ تهران) پر می‌شوند. برای نماد تازه‌وارد تا آن زمان ممکن است `null` باشند.
- **شاخص‌ها:** شاخص هم با همین endpoint پیدا می‌شود و `is_index: true` دارد. بیشتر فیلدهای دیگر آن `null` است. سابقهٔ شاخص را از [`/v1/indices/{ref}/daily`](/docs/api/indices/) بگیرید.

```bash
curl -G "https://poolick.ir/v1/instruments" \
  --data-urlencode "q=شاخص کل" -d "limit=3" \
  -H "Authorization: Bearer $ROSHA_KEY"
```

سه نتیجهٔ این جست‌وجو «شاخص کل» (`32097828799138957`)، «شاخص کل (هم وزن)» (`67130298613737946`) و «شاخص کل فرابورس» (`43685683301327984`) است. نتیجهٔ اول به‌طور کامل:

```json
{
  "ins_code": "32097828799138957",
  "ticker": "شاخص کل",
  "name": "شاخص کل",
  "instrument_id": null,
  "isin": null,
  "ticker_latin": null,
  "name_latin": null,
  "company_name": null,
  "flow": 1,
  "y_val": null,
  "market_code": null,
  "group_code": null,
  "sector_code": null,
  "sub_sector_code": null,
  "base_volume": null,
  "shares_outstanding": null,
  "is_index": true,
  "active": true,
  "first_trade_date": null,
  "last_trade_date": null
}
```

- **نماد مبهم:** `ref` فارسی اگر به چند ابزار بخورد، ابزاری با بالاترین رتبه برمی‌گردد. در سامانهٔ عملیاتی، `ins_code` را یک بار از جست‌وجو بگیرید و ذخیره کنید.
- **ابزار MCP معادل:** `search_instruments` و `get_instrument`.