مهاجرت از اسکرپینگ TSETMC

اگر امروز دادهٔ بورس را با اسکرپر خودتان از TSETMC یا با کتابخانه‌ای متن‌باز مثل pytse-client یا finpy-tse می‌گیرید، می‌توانید همان داده را با یک درخواست HTTP از روشا بگیرید. این صفحه می‌گوید هر کار رایج به کدام endpoint می‌رسد، چه چیزهایی در داده فرق دارد و چه چیزهایی همچنان کار خود شماست.

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

هر کار به کدام endpoint می‌رسد؟

کاری که پیش‌تر می‌کردید	در روشا
پیدا کردن شناسهٔ نماد (insCode) از روی نماد فارسی	GET /v1/instruments?q=…
گرفتن مشخصات نماد: نام، ISIN، بازار، گروه صنعت، تعداد سهام	GET /v1/instruments/{ref}
دانلود سابقهٔ روزانهٔ قیمت و حجم	GET /v1/instruments/{ref}/daily
تعدیل قیمت بابت افزایش سرمایه و سود نقدی	همان endpoint با adjusted=true
گرفتن فهرست رویدادهای تعدیل	GET /v1/instruments/{ref}/adjustments
سابقهٔ خرید و فروش حقیقی و حقوقی	GET /v1/instruments/{ref}/client-type
سابقهٔ شاخص کل و شاخص‌های دیگر	GET /v1/indices/{ref}/daily
قیمت لحظه‌ای و عمق بازار در ساعات معامله	GET /v1/instruments/{ref}/quote (خانوادهٔ intraday)
ریزمعاملات یک روز	GET /v1/instruments/{ref}/trades (خانوادهٔ intraday)
ساختن کندل درون‌روز از ریزمعاملات	GET /v1/instruments/{ref}/bars (خانوادهٔ intraday)
تشخیص روزهای معاملاتی و تعطیلی‌ها	GET /v1/calendar
NAV، خالص دارایی و بازده صندوق‌ها	GET /v1/funds و GET /v1/funds/{ref}/history (منبع: فیپیران)
پرسیدن از داده به زبان طبیعی	سرور MCP

نمونه: سابقهٔ تعدیل‌شده در DataFrame

رایج‌ترین کار، گرفتن سابقهٔ تعدیل‌شدهٔ یک نماد در DataFrame است. با روشا برنامهٔ کامل آن این است:

import os
import time

import pandas as pd
import requests

BASE = "https://poolick.ir"
HEADERS = {"Authorization": f"Bearer {os.environ['ROSHA_KEY']}"}


def get(path, **kwargs):
    """GET with one retry on 429, waiting as long as Retry-After says."""
    for _ in range(2):
        r = requests.get(BASE + path, headers=HEADERS, timeout=30, **kwargs)
        if r.status_code != 429:
            break
        time.sleep(int(r.headers.get("Retry-After", "1")))
    r.raise_for_status()
    return r.json()


data = get(
    "/v1/instruments/فولاد/daily",
    params={"adjusted": "true", "limit": 5000},
)
df = pd.DataFrame(data["rows"]).set_index("d")
df.index = pd.to_datetime(df.index)
print(df[["open", "high", "low", "close", "volume"]].tail())

نمونه‌های بیشتر در پایتون و pandas است.

چه چیزهایی در داده فرق دارد؟

پیش از جایگزینی، این هفت مورد را با خروجی فعلی خود مقایسه کنید. بیشتر اختلاف‌های عددی از همین‌جا می‌آید.

موضوع	در روشا	چه چیزی را بررسی کنید
واحد پول	ریال	اگر کد شما با تومان کار می‌کند، بر ۱۰ تقسیم کنید
شناسهٔ نماد	ins_code به شکل رشته	ستون‌ها و کلیدهای خود را متنی کنید؛ عدد ۶۴ بیتی اعشاری رقم‌های آخر را عوض می‌کند
تعدیل	پرچم adjusted در همان endpoint؛ پیش‌فرض false	پیش‌فرض، قیمت خام است. برای بازده adjusted=true بفرستید
دامنهٔ تعدیل	افزایش سرمایه و سود نقدی با هم، بر اساس رویدادهای TSETMC؛ حجم تعدیل نمی‌شود	اگر پیش‌تر فقط یکی را تعدیل می‌کردید، اعداد فرق خواهد کرد
close و last	close قیمت پایانی رسمی؛ last قیمت آخرین معامله	نام ستون‌های خود را با این دو تطبیق دهید
تاریخ	پاسخ میلادی ISO، به‌همراه jdate شمسی در ردیف‌های روزانه؛ درخواست هر سه قالب را می‌پذیرد	ایندکس تاریخ خود را با d یا jdate بسازید
ترتیب	از قدیم به جدید؛ limit یعنی N ردیف آخر	اگر کد شما ترتیب نزولی فرض می‌کند، آن را برگردانید

دو تفاوت کوچک‌تر:

• ی و ک: نام‌ها و نمادها با «ی» و «ک» فارسی ذخیره شده‌اند و ورودی جست‌وجو هم یکسان‌سازی می‌شود. اگر در کد خود نمادها را با حروف عربی مقایسه می‌کنید، مقایسه را یکسان‌سازی کنید.
• روز بدون معامله: open، high و low در آن روز null است، نه صفر.

چه چیزهایی دیگر لازم نیست؟

این کارها را روشا پیش از رسیدن داده به شما انجام داده است:

• نگه‌داری اسکرپر در برابر تغییر صفحه‌ها و پاسخ‌های منبع؛
• تبدیل نماد فارسی به insCode و انتخاب بین نماد قدیم و جدید (با ref یا جست‌وجو)؛
• یکسان‌سازی حروف عربی و فارسی؛
• محاسبهٔ ضریب تعدیل و اعمال آن؛
• ساختن کندل از ریزمعاملات؛
• تبدیل تاریخ شمسی به میلادی در ورودی.

چه چیزهایی کار خودتان می‌ماند؟

روشا دادهٔ خام و تعدیل‌شده می‌دهد؛ این بخش‌ها همچنان با شماست:

• ذخیره‌سازی: اگر به نسخهٔ محلی نیاز دارید، خودتان نگهش می‌دارید. روش در همگام‌سازی روزانه با پایگاه داده.
• اندیکاتورها و مدل‌ها: میانگین متحرک، RSI، بازده و هر محاسبهٔ دیگر را خودتان انجام می‌دهید.
• رعایت سقف‌ها: rate limit و سهمیهٔ روزانهٔ پلن را باید رعایت کنید و برای 429 به اندازهٔ Retry-After صبر کنید. محدودیت‌ها و پلن‌ها.
• نگهداری کلید: کلید را در متغیر محیطی نگه دارید و در مرورگر نگذارید. احراز هویت و کلیدها.
• بررسی source در quote: خارج از ساعات بازار، quote آخرین ردیف روزانه است.
• داده‌هایی که روشا ندارد: دادهٔ بنیادی و اطلاعیه‌های کدال، و قیمت ارز و طلا در روشا نیست. اگر به آن‌ها نیاز دارید، منبع فعلی خود را برای همان بخش نگه دارید.

چه چیزهایی محدودیت دارد؟

پیش از تصمیم، این محدودیت‌ها را بدانید:

• دادهٔ روزانه یک بار در روز تازه می‌شود: ساعت ۱۸:۱۵ تهران، شنبه تا چهارشنبه. ارقام آخرین روز ممکن است تا اجرای بعدی اصلاح شود. به‌روزرسانی داده‌ها.
• quote زنده هر ۳۰ ثانیه تازه می‌شود (پس از ۱۳:۰۵ هر ۲ دقیقه) و جریان tick به tick نیست.
• ریزمعاملات برای همهٔ روزهای گذشته موجود نیست. پاسخ خالی یعنی ریزمعاملات آن روز ذخیره نشده است. اگر به بازهٔ مشخصی نیاز دارید، پیش از شروع با پشتیبانی هماهنگ کنید.
• هر پاسخ حداکثر ۵٬۰۰۰ ردیف دارد. برای سابقهٔ بلندتر با تاریخ صفحه‌بندی کنید.
• دادهٔ لحظه‌ای به پلنی با intraday نیاز دارد (تا آبان ۱۴۰۵: حرفه‌ای و سازمانی). قیمت‌ها.

گام‌های پیشنهادی مهاجرت

1. کلید رایگان بگیرید و شروع سریع را اجرا کنید.
2. برای نمادهایی که دنبال می‌کنید، ins_code را یک بار با جست‌وجو بگیرید و ذخیره کنید.
3. برای چند نماد و چند روز، خروجی روشا را با خروجی فعلی خود مقایسه کنید. به واحد (ریال)، close در برابر last و حالت تعدیل دقت کنید.
4. لایهٔ دریافت داده را در کد خود با تابع get جایگزین کنید و بقیهٔ کد را دست نزنید.
5. کار زمان‌بندی‌شدهٔ خود را به پس از ۱۸:۱۵ تهران ببرید.