# پرسش‌های پرتکرار

> پاسخ کوتاه به پرسش‌های رایج دربارهٔ API روشا؛ تازگی داده، ریال و تومان، close و last، پرش قیمت خام، ins_code در جاوااسکریپت، quote شبانه و صندوق چتری.
> Source: https://poolick.ir/docs/faq/

پاسخ هر پرسش در یکی دو جملهٔ اول آمده است و پیوندِ پس از آن به صفحهٔ کامل می‌رود.

## داده و تازگی

### داده زنده است یا با تأخیر؟

بستگی به endpoint دارد. quote در ساعات بازار هر ۳۰ ثانیه تازه می‌شود (پس از ۱۳:۰۵ هر ۲ دقیقه) و به پلنی با `intraday` نیاز دارد. سابقهٔ روزانه، حقیقی و حقوقی، شاخص‌ها و ریزمعاملات یک بار در روز، ساعت ۱۸:۱۵ تهران، شنبه تا چهارشنبه، تازه می‌شوند. جدول کامل در [به‌روزرسانی داده‌ها](/docs/freshness/) است.

### داده از کجا می‌آید؟

دادهٔ معاملاتی بورس و فرابورس از TSETMC و دادهٔ صندوق‌های سرمایه‌گذاری از فیپیران (FIPIran) گردآوری می‌شود.

### چرا ارقام امروز پس از چند ساعت عوض شد؟

چون دادهٔ آخرین روز تا اجرای بعدیِ به‌روزرسانی قطعی نیست. TSETMC بعضی ارقام پایان روز را دیر منتشر می‌کند. اگر داده را ذخیره می‌کنید، چند روز آخر را در هر همگام‌سازی دوباره بگیرید: [همگام‌سازی روزانه](/docs/guides/daily-sync/).

### چرا ارقام چند روز گذشتهٔ یک صندوق تغییر کرده است؟

چون فیپیران ارقام گذشته را اصلاح می‌کند و روشا سابقهٔ کامل صندوق‌ها را هر جمعه ساعت ۰۲:۰۰ از نو می‌سازد. اگر سابقهٔ صندوق را ذخیره می‌کنید، هفته‌ای یک بار آن را کامل دوباره بخوانید.

### روشا چه داده‌هایی ندارد؟

روشا دادهٔ بنیادی و اطلاعیه‌های کدال را ندارد و قیمت ارز و طلا را هم پوشش نمی‌دهد. پوشش روشا دادهٔ معاملاتی بورس تهران و فرابورس ایران، شاخص‌ها و صندوق‌های سرمایه‌گذاری است. فهرست endpointها در [مرجع API](/docs/api/) است.

### ریزمعاملات همهٔ روزهای گذشته موجود است؟

نه. ریزمعاملات فقط برای روزهایی هست که در پایان همان روز دریافت یا بعداً بازیابی شده‌اند. پاسخ خالی `/trades` یا `/bars` یعنی ریزمعاملات آن روز ذخیره نشده است، نه اینکه نماد معامله نشده است. اگر بازهٔ مشخصی لازم دارید، پیش از شروع با [پشتیبانی](/contact/) هماهنگ کنید.

## قیمت‌ها و فیلدها

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

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

### فرق `close` و `last` چیست؟

`close` قیمت پایانی رسمی است و `last` قیمت آخرین معامله. این دو لزوماً برابر نیستند. شرح فیلدها در [سابقهٔ روزانه](/docs/api/daily/) است.

### چرا در سابقهٔ قیمت پرش یا افت ناگهانی می‌بینم؟

چون سابقهٔ پیش‌فرض تعدیل‌نشده است و در روز افزایش سرمایه یا تقسیم سود، قیمت خام می‌پرد. برای محاسبهٔ بازده و تحلیل تکنیکال `adjusted=true` بفرستید. قاعدهٔ تعدیل در [تعدیل قیمت](/docs/api/adjustments/) است.

### چرا `open`، `high` و `low` در بعضی روزها `null` است؟

چون نماد در آن روز معامله نشده است. `close` و `prev_close` در آن ردیف مقدار دارند.

### چرا `ins_code` در جاوااسکریپت رقم‌های آخرش عوض می‌شود؟

چون `ins_code` از بازهٔ عدد صحیح امن جاوااسکریپت بزرگ‌تر است و تبدیل آن با `Number()` رقم‌های آخر را عوض می‌کند. روشا آن را عمداً به شکل رشته برمی‌گرداند؛ همان رشته را نگه دارید. نمونه: `Number("32097828799138957")` برابر `32097828799138956` می‌شود. شرح در [جاوااسکریپت](/docs/javascript/).

### تاریخ شمسی را باید خودم تبدیل کنم؟

نه. پارامترهای تاریخ، شمسی را مستقیم می‌پذیرند (`1405-08-20`) و ردیف‌های روزانهٔ سهام فیلد `jdate` دارند. تاریخ‌های دیگر پاسخ میلادی ISO است. [قراردادها و قالب‌ها](/docs/conventions/).

### چرا با `limit=10` ده ردیف اول سابقه را نمی‌گیرم؟

چون `limit` تازه‌ترین N ردیف بازه را نگه می‌دارد، نه قدیمی‌ترین را. ردیف‌ها همیشه از قدیم به جدید مرتب‌اند. برای ده روز اول یک بازه، `start` و `end` را مشخص کنید.

### یک نماد فارسی به چند نماد می‌خورد. کدام برمی‌گردد؟

ابزاری با بالاترین رتبه: نماد فعال، بازار اصلی، و بورس پیش از فرابورس. وقتی جواب مهم است، یک بار با `GET /v1/instruments?q=…` جست‌وجو کنید و از آن پس با `ins_code` کار کنید. [نمادها](/docs/api/instruments/).

## quote و دادهٔ لحظه‌ای

### چرا quote شب‌ها تغییر نمی‌کند؟

چون خارج از ساعات بازار، `/quote` آخرین ردیف روزانه را با `"source": "daily"` برمی‌گرداند، یعنی قیمت پایانی آخرین روز معاملاتی. snapshot زنده پس از پایان جلسه منقضی می‌شود. همیشه `source` را بررسی کنید. [دادهٔ لحظه‌ای](/docs/api/intraday/).

### چرا `/quote` خطای `403 plan_forbids` می‌دهد؟

چون `/quote`، `/trades` و `/bars` در خانوادهٔ `intraday` هستند و پلن شما آن را ندارد. تا آبان ۱۴۰۵ پلن‌های حرفه‌ای و سازمانی `intraday` دارند. [محدودیت‌ها و پلن‌ها](/docs/limits/).

### روشا WebSocket یا webhook دارد؟

نه. همهٔ داده با درخواست `GET` گرفته می‌شود. برای quote زنده، هر ۳۰ ثانیه یک بار درخواست بفرستید؛ داده زودتر از آن تازه نمی‌شود.

## صندوق‌ها

### چرا NAV صندوق چتری با NAV زیرصندوق نمی‌خواند؟

چون `/v1/funds/{ref}/history` در سطح شمارهٔ ثبت است و با NAV هیچ‌کدام از زیرصندوق‌ها یکی نیست. ارقام هر زیرصندوق در `/v1/funds/{ref}/snapshots` با `group_id` همان زیرصندوق است و از آبان ۱۴۰۵ به بعد موجود است. [صندوق‌ها](/docs/api/funds/).

### چرا `latest` یک صندوق از سابقهٔ آن عقب‌تر است؟

چون `latest` از گزارش مقایسه‌ای فیپیران می‌آید که برای صندوق‌های دیرمنتشر ممکن است چند روز عقب باشد. برای تازه‌ترین رقم `/v1/funds/{ref}/history?limit=1` را بگیرید.

### چرا آلفا و بتا در ردیف‌های اخیر `null` است؟

چون این دو در فیپیران با حدود هفت هفته تأخیر منتشر می‌شوند.

### `equity` شامل پنج سهم بزرگ هم هست؟

بله. `equity` سهم کل سهام از دارایی صندوق است و `top_five` را هم در بر دارد.

## کلید، پلن و سقف‌ها

### کلید رایگان چه چیزهایی دارد؟

تا آبان ۱۴۰۵: ۳۰ درخواست در دقیقه، ۱٬۰۰۰ درخواست در روز، خانواده‌های `history` و `mcp` و یک کلید. دادهٔ لحظه‌ای (`intraday`) در آن نیست. فهرست به‌روز پلن‌ها در [قیمت‌ها](/pricing/) است.

### کلیدم را گم کرده‌ام. چه کنم؟

کلید قابل بازیابی نیست، چون روشا فقط SHA-256 آن را نگه می‌دارد. در [پنل](/panel/) کلید را بچرخانید تا کلید تازه بگیرید؛ کلید قبلی حداکثر ظرف ۶۰ ثانیه از کار می‌افتد. [احراز هویت و کلیدها](/docs/authentication/).

### می‌توانم کلید را در نشانی بفرستم؟

نه. کلید فقط در سرآیند `Authorization: Bearer` یا `X-API-Key` پذیرفته می‌شود، چون نشانی‌ها در لاگ سرورها و پراکسی‌ها می‌مانند.

### خطای `429` گرفتم. چه کنم؟

`code` را بخوانید. برای `rate_limited` به اندازهٔ سرآیند `Retry-After` صبر کنید و دوباره بفرستید. برای `quota_exceeded` سهمیهٔ روزانه تمام شده است و نیمه‌شب به وقت تهران صفر می‌شود. [خطاها](/docs/errors/).

### بیش از ۵٬۰۰۰ ردیف را چطور بگیرم؟

با تاریخ صفحه‌بندی کنید: هر بار `end` را روزِ قبل از قدیمی‌ترین ردیف گرفته‌شده بگذارید. کد در [پایتون و pandas](/docs/python/) و [جاوااسکریپت](/docs/javascript/) است.

### درخواست‌های MCP هم از سهمیه کم می‌کنند؟

بله. هر درخواست HTTP به `/mcp` یک درخواست از سقف دقیقه‌ای و سهمیهٔ روزانهٔ همان کلید کم می‌کند و یک گفت‌وگوی دستیار چند درخواست می‌فرستد. [MCP](/docs/mcp/).

## دستیارهای هوش مصنوعی

### کدام دستیارها به سرور MCP روشا وصل می‌شوند؟

Claude Code، Claude Desktop، Cursor، Codex CLI، Gemini CLI، OpenAI API و Gemini API. برنامهٔ ChatGPT و برنامهٔ Gemini تا آبان ۱۴۰۵ وصل نمی‌شوند. تنظیم هر کدام در [راه‌اندازی در هر دستیار](/docs/mcp/clients/) است.

### همهٔ داده‌های REST در MCP هم هست؟

تقریباً. ریزمعاملات (`/trades`)، رویدادهای تعدیل (`/adjustments`) و snapshot زیرصندوق‌ها (`/snapshots`) فقط در REST هستند و هر ابزار MCP حداکثر ۵۰۰ ردیف برمی‌گرداند. [ابزارهای MCP](/docs/mcp/tools/).

## پشتیبانی

### اگر فکر می‌کنم یک عدد غلط است چه کنم؟

برای [پشتیبانی](/contact/) این‌ها را بفرستید: نماد یا صندوق، تاریخ، عدد روشا، عدد مرجع، نشانی کامل درخواست و پیشوند کلید (مثل `rosha_xxxxxxxx`، هرگز کلید کامل).

### روشا توصیهٔ سرمایه‌گذاری می‌دهد؟

نه. روشا داده می‌دهد. تصمیم سرمایه‌گذاری و مسئولیت آن با استفاده‌کننده است.