قراردادها و قالب‌ها
چند قاعده در همهٔ پاسخ‌های روشا ثابت است: JSON با UTF-8، مبالغ به ریال، تاریخ پاسخ میلادی ISO، زمان به وقت تهران، ins_code به شکل رشته و ردیف‌های سابقه از قدیم به جدید. با دانستن این‌ها بیشتر خطاهای رایج پیش نمی‌آید.
خلاصهٔ قاعده‌ها
Section titled “خلاصهٔ قاعده‌ها”| موضوع | قاعده |
|---|---|
| قالب پاسخ | 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 ردیف آخر بازه |
| حروف فارسی | «ي» و «ك» عربی به «ی» و «ک» فارسی یکسان‌سازی می‌شود |
تاریخ را به چه قالبی بفرستم؟
Section titled “تاریخ را به چه قالبی بفرستم؟”هر پارامتر تاریخ سه قالب را می‌پذیرد: میلادی ISO، میلادی فشرده و شمسی. لازم نیست تاریخ شمسی را خودتان تبدیل کنید.
| قالب | نمونه |
|---|---|
| میلادی ISO | 2026-11-11 |
میلادی فشرده (yyyymmdd) |
20261111 |
| شمسی | 1405-08-20 |
هر مقدار دیگری خطای 422 می‌گیرد:
{"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.
مبالغ به ریال است یا تومان؟
Section titled “مبالغ به ریال است یا تومان؟”همهٔ مبالغ به ریال است، همان‌طور که TSETMC و فیپیران منتشر می‌کنند. قیمت، ارزش معاملات، NAV و خالص ارزش دارایی را برای نمایش به تومان باید خودتان بر ۱۰ تقسیم کنید.
بازده‌ها و سهم‌های ترکیب دارایی به درصد است: "ret_1d": 2.77 یعنی ۲٫۷۷ درصد.
چرا ins_code رشته است؟
Section titled “چرا ins_code رشته است؟”ins_code (شناسهٔ نماد در TSETMC) عددی بلند است (در نمونهٔ زیر ۱۷ رقم) و از بازهٔ عدد صحیح امن جاوااسکریپت (۲ به توان ۵۳) بزرگ‌تر است. برای همین روشا آن را به شکل رشته برمی‌گرداند.
{"ins_code": "46348559193224090", "ticker": "فولاد"}آن را همیشه متن نگه دارید: در جاوااسکریپت با Number() تبدیلش نکنید، در pandas ستون را str بگذارید و در اکسل قالب خانه را Text کنید. نمونهٔ خطای تبدیل در جاوااسکریپت آمده است.
ردیف‌ها به چه ترتیبی برمی‌گردند و limit چه می‌کند؟
Section titled “ردیف‌ها به چه ترتیبی برمی‌گردند و 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)
Section titled “نماد را چطور مشخص کنم؟ (ref)”در مسیرهای /v1/instruments/{ref}/… و /v1/indices/{ref}/… به‌جای {ref} یکی از این سه را بفرستید:
| نوع | نمونه | توضیح |
|---|---|---|
insCode در TSETMC |
46348559193224090 |
فقط رقم، بیش از ۸ رقم |
| InstrumentID یا ISIN | IRO1FOLD0001 |
۱۲ نویسه |
| نماد فارسی دقیق | فولاد |
در نشانی باید URL-encode شود |
نکته‌ها:
- ی و ک: ورودی شما پیش از جست‌وجو یکسان‌سازی می‌شود. «ي» و «ك» عربی همان نتیجهٔ «ی» و «ک» فارسی را می‌دهد.
- نماد مبهم: اگر یک نماد فارسی به چند ابزار بخورد (نماد قدیم و جدید، یا یک نام در دو بازار)، ابزاری با بالاترین رتبه انتخاب می‌شود: ابتدا ابزار فعال، سپس بازار اصلی، سپس بورس پیش از فرابورس. وقتی جواب مهم است، یک بار با جست‌وجو
ins_codeرا پیدا کنید و از آن پس با همان کار کنید. - شاخص‌ها: شاخص هم یک نماد است (
is_index: true). آن را با جست‌وجو پیدا کنید، مثل/v1/instruments?q=شاخص کل. - پیدا نشد: پاسخ
404با{"detail": "instrument not found: xyz123"}است.
صندوق را چطور مشخص کنم؟
Section titled “صندوق را چطور مشخص کنم؟”در مسیرهای /v1/funds/{ref}/… چهار شکل پذیرفته است:
| نوع | نمونه |
|---|---|
شمارهٔ ثبت نزد سازمان بورس (reg_no) |
10589 |
| نماد صندوق | عیار |
| نام دقیق صندوق | عیار مفید |
insCode صندوق قابل معامله در TSETMC |
34144395039913458 |
شناسهٔ پایدار صندوق شمارهٔ ثبت است. اگر صندوق پیدا نشود پاسخ 404 با {"detail": "fund 'nope' not found"} برمی‌گردد. دربارهٔ صندوق‌های چتری که چند زیرصندوق زیر یک شمارهٔ ثبت دارند، صندوق‌ها را ببینید.
بازهٔ بلندتر از ۵٬۰۰۰ ردیف را چطور بگیرم؟
Section titled “بازهٔ بلندتر از ۵٬۰۰۰ ردیف را چطور بگیرم؟”بازه را با تاریخ صفحه‌بندی کنید: هر بار end را روزِ قبل از قدیمی‌ترین ردیفی بگذارید که گرفته‌اید. وقتی تعداد ردیف‌های پاسخ از limit کمتر شد، به ابتدای سابقه رسیده‌اید.
- درخواست اول:
?limit=5000. تازه‌ترین ۵٬۰۰۰ ردیف می‌آید. - قدیمی‌ترین ردیف، عضو اول
rowsاست. اگرdآن2006-05-14باشد، درخواست بعد:?limit=5000&end=2006-05-13. - تا وقتی پاسخ دقیقاً ۵٬۰۰۰ ردیف دارد ادامه دهید.
کد کامل این حلقه در پایتون و pandas و جاوااسکریپت آمده است. روشا پارامتر offset یا cursor برای سابقه ندارد؛ فقط فهرست صندوق‌ها (/v1/funds) با offset صفحه‌بندی می‌شود.
صفحهٔ اصلی · قیمت‌ها · وضعیت · پنل · پشتیبانی
داده‌ها توصیهٔ سرمایه‌گذاری نیست. سلب مسئولیت