# قراردادها و قالب‌ها

> قاعده‌های ثابت API روشا؛ قالب تاریخ، واحد ریال، ins_code رشته‌ای، ترتیب ردیف‌ها، معنای limit، شناسایی نماد و صندوق و صفحه‌بندی با تاریخ.
> Source: https://poolick.ir/docs/conventions/

چند قاعده در همهٔ پاسخ‌های روشا ثابت است: JSON با UTF-8، مبالغ به ریال، تاریخ پاسخ میلادی ISO، زمان به وقت تهران، `ins_code` به شکل رشته و ردیف‌های سابقه از قدیم به جدید. با دانستن این‌ها بیشتر خطاهای رایج پیش نمی‌آید.

## خلاصهٔ قاعده‌ها

| موضوع | قاعده |
|---|---|
| قالب پاسخ | JSON با UTF-8. متن فارسی همان‌طور که هست برمی‌گردد. |
| تاریخ در درخواست | `2026-11-11`، `20261111` یا شمسی `1405-08-20` |
| تاریخ در پاسخ | میلادی ISO، مثل `2026-11-11`. ردیف‌های روزانهٔ سهام `jdate` (شمسی) هم دارند. |
| زمان | ISO 8601 به وقت تهران، مثل `2026-11-11T09:00:43+03:30` |
| واحد پول | ریال، نه تومان |
| بازده و سهم‌ها | درصد؛ `2.77` یعنی ۲٫۷۷ درصد |
| `ins_code` | رشته، نه عدد |
| ترتیب ردیف‌ها | از قدیم به جدید |
| `limit` | N ردیف **آخر** بازه |
| حروف فارسی | «ي» و «ك» عربی به «ی» و «ک» فارسی یکسان‌سازی می‌شود |

## تاریخ را به چه قالبی بفرستم؟

هر پارامتر تاریخ سه قالب را می‌پذیرد: میلادی ISO، میلادی فشرده و شمسی. لازم نیست تاریخ شمسی را خودتان تبدیل کنید.

| قالب | نمونه |
|---|---|
| میلادی ISO | `2026-11-11` |
| میلادی فشرده (`yyyymmdd`) | `20261111` |
| شمسی | `1405-08-20` |

هر مقدار دیگری خطای `422` می‌گیرد:

```json
{"detail": "bad date 'bad': use YYYY-MM-DD, YYYYMMDD or Jalali 1403-01-15"}
```

تاریخ‌های پاسخ همیشه میلادی ISO است. زمان‌ها (مثل `ts` در ریزمعاملات) ISO 8601 با اختلاف ساعت تهران است: `2026-11-11T09:00:43+03:30`.

## مبالغ به ریال است یا تومان؟

همهٔ مبالغ به ریال است، همان‌طور که TSETMC و فیپیران منتشر می‌کنند. قیمت، ارزش معاملات، NAV و خالص ارزش دارایی را برای نمایش به تومان باید خودتان بر ۱۰ تقسیم کنید.

بازده‌ها و سهم‌های ترکیب دارایی به درصد است: `"ret_1d": 2.77` یعنی ۲٫۷۷ درصد.

## چرا `ins_code` رشته است؟

`ins_code` (شناسهٔ نماد در TSETMC) عددی بلند است (در نمونهٔ زیر ۱۷ رقم) و از بازهٔ عدد صحیح امن جاوااسکریپت (۲ به توان ۵۳) بزرگ‌تر است. برای همین روشا آن را به شکل رشته برمی‌گرداند.

```json
{"ins_code": "46348559193224090", "ticker": "فولاد"}
```

آن را همیشه متن نگه دارید: در جاوااسکریپت با `Number()` تبدیلش نکنید، در pandas ستون را `str` بگذارید و در اکسل قالب خانه را Text کنید. نمونهٔ خطای تبدیل در [جاوااسکریپت](/docs/javascript/) آمده است.

## ردیف‌ها به چه ترتیبی برمی‌گردند و `limit` چه می‌کند؟

endpointهای سابقه ردیف‌ها را از قدیم به جدید برمی‌گردانند و `limit` تازه‌ترین N ردیف بازهٔ `[start, end]` را نگه می‌دارد. پس `?limit=1` یعنی آخرین روز.

| درخواست | نتیجه |
|---|---|
| `?limit=1` | فقط آخرین روز موجود |
| `?limit=30` | ۳۰ روز معاملاتی آخر، از قدیم به جدید |
| `?start=1405-07-01` | از اول مهر ۱۴۰۵ تا امروز (حداکثر `limit` ردیف آخر) |
| `?end=2014-12-31&limit=2` | دو روز معاملاتی آخرِ منتهی به ۲۰۱۴-۱۲-۳۱ |

`start` و `end` هر دو اختیاری‌اند و خودِ آن روزها را هم شامل می‌شوند. پیش‌فرض `limit` در endpointهای سابقه ۱٬۰۰۰ و سقف آن ۵٬۰۰۰ است. مقدار بیشتر از سقف خطای `422` می‌گیرد.

## نماد را چطور مشخص کنم؟ (`ref`)

در مسیرهای `/v1/instruments/{ref}/…` و `/v1/indices/{ref}/…` به‌جای `{ref}` یکی از این سه را بفرستید:

| نوع | نمونه | توضیح |
|---|---|---|
| `insCode` در TSETMC | `46348559193224090` | فقط رقم، بیش از ۸ رقم |
| InstrumentID یا ISIN | `IRO1FOLD0001` | ۱۲ نویسه |
| نماد فارسی دقیق | `فولاد` | در نشانی باید URL-encode شود |

نکته‌ها:

- **ی و ک:** ورودی شما پیش از جست‌وجو یکسان‌سازی می‌شود. «ي» و «ك» عربی همان نتیجهٔ «ی» و «ک» فارسی را می‌دهد.
- **نماد مبهم:** اگر یک نماد فارسی به چند ابزار بخورد (نماد قدیم و جدید، یا یک نام در دو بازار)، ابزاری با بالاترین رتبه انتخاب می‌شود: ابتدا ابزار فعال، سپس بازار اصلی، سپس بورس پیش از فرابورس. وقتی جواب مهم است، یک بار با [جست‌وجو](/docs/api/instruments/) `ins_code` را پیدا کنید و از آن پس با همان کار کنید.
- **شاخص‌ها:** شاخص هم یک نماد است (`is_index: true`). آن را با جست‌وجو پیدا کنید، مثل `/v1/instruments?q=شاخص کل`.
- **پیدا نشد:** پاسخ `404` با `{"detail": "instrument not found: xyz123"}` است.

## صندوق را چطور مشخص کنم؟

در مسیرهای `/v1/funds/{ref}/…` چهار شکل پذیرفته است:

| نوع | نمونه |
|---|---|
| شمارهٔ ثبت نزد سازمان بورس (`reg_no`) | `10589` |
| نماد صندوق | `عیار` |
| نام دقیق صندوق | `عیار مفید` |
| `insCode` صندوق قابل معامله در TSETMC | `34144395039913458` |

شناسهٔ پایدار صندوق شمارهٔ ثبت است. اگر صندوق پیدا نشود پاسخ `404` با `{"detail": "fund 'nope' not found"}` برمی‌گردد. دربارهٔ صندوق‌های چتری که چند زیرصندوق زیر یک شمارهٔ ثبت دارند، [صندوق‌ها](/docs/api/funds/) را ببینید.

## بازهٔ بلندتر از ۵٬۰۰۰ ردیف را چطور بگیرم؟

بازه را با تاریخ صفحه‌بندی کنید: هر بار `end` را روزِ قبل از قدیمی‌ترین ردیفی بگذارید که گرفته‌اید. وقتی تعداد ردیف‌های پاسخ از `limit` کمتر شد، به ابتدای سابقه رسیده‌اید.

1. درخواست اول: `?limit=5000`. تازه‌ترین ۵٬۰۰۰ ردیف می‌آید.
2. قدیمی‌ترین ردیف، عضو اول `rows` است. اگر `d` آن `2006-05-14` باشد، درخواست بعد: `?limit=5000&end=2006-05-13`.
3. تا وقتی پاسخ دقیقاً ۵٬۰۰۰ ردیف دارد ادامه دهید.

کد کامل این حلقه در [پایتون و pandas](/docs/python/) و [جاوااسکریپت](/docs/javascript/) آمده است. روشا پارامتر `offset` یا cursor برای سابقه ندارد؛ فقط فهرست صندوق‌ها (`/v1/funds`) با `offset` صفحه‌بندی می‌شود.