کلید API/api/v1

صندوق‌ها

جداول خام صندوق‌ها — پرتفوی، معاملات، سپرده و دارایی روزانه (NAV).

دسترسی شریک به جداول خام صندوق‌ها از طریق کلید API. مسیر عمومی /api/v1/funds رایگان است و نباید با کلید شریک فراخوانی شود.

Auth: X-API-Key: cdl-724-… یا Authorization: Bearer cdl-724-…
هر کلید فعال API به این سرویس دسترسی دارد؛ مقدار scopes کلید محدودکننده نیست.

هزینه از کیف پول کاربر کسر می‌شود: base_irr + rows_returned × per_row_irr (پیش‌فرض محیط: پایه ۱۰۰۰، به‌ازای هر ردیف ۱۰ ریال). درخواست‌های ناموفق با cost_irr: 0 ثبت می‌شوند.

محدودیت نرخ به‌ازای هر کلید (پیش‌فرض): ۶۰ درخواست در دقیقه، ۲۰۰۰ در ساعت. هدرهای X-RateLimit-* و در صورت عبور از سقف، 429 با error_code: rate_limit_exceeded.

GET/api/v1/external/funds/data

page_size شریک با EXTERNAL_API_MAX_PAGE_SIZE محدود است (پیش‌فرض ۱۰۰).

جداول (`table_name`)

نام جدول case-insensitive است؛ نام‌های فشرده هم پذیرفته می‌شوند.

`table_name`	Aliases	Description (EN)	Description (FA)
`fund_portfolio`	`portfolio`	Fund portfolio holdings by period	ترکیب دارایی / پرتفوی صندوق به‌ازای دوره
`fund_transactions`	`transactions`	Fund buy/sell transactions	معاملات خرید و فروش صندوق
`fund_deposit`	`deposits`, `deposit`	Fund deposit / cash positions	سپرده و موقعیت‌های نقدی صندوق
`fund_daily_asset`	`daily_asset`, `daily_assets`	Daily asset mix, NAV prices, net assets	ترکیب دارایی روزانه، NAV صدور/ابطال، خالص ارزش دارایی

پارامترهای کوئری

Required

Parameter	Type	Description
`table_name`	string	یکی از جداول بالا

Filters

fund_symbols و tickers را می‌توان تکرار کرد یا با کاما جدا کرد (fund_symbols=الف,ب یا fund_symbols= تکراری). برای چند مقدار transaction_types، پارامتر را تکرار کنید.

برای fund_daily_asset: fund_symbols با ستون symbol (نه fund_symbol) تطبیق می‌شود. فیلدهای شریک (بدون id/timestamp): symbol, name, fund_type, date_jalali, as_of_date, ستون‌های ترکیب ارزش/درصد (top5_equity_*, bonds_*, cash_*, …)، issue_nav, cancel_nav, statistical_nav, net_asset.

Parameter	Type	Default	Description
`fund_symbols`	string[]	none	تطابق دقیق روی نماد صندوق
`tickers`	string[]	none	تطابق دقیق روی نماد پایه (`fund_portfolio`, `fund_transactions`) — برای `fund_daily_asset` اعمال نمی‌شود
`priod_start`	date (`YYYY-MM-DD`)	none	دوره گزارش ≥ شروع (املای پارامتر: `priod_`، نه `period_`). برای `fund_daily_asset` روی `as_of_date`
`priod_end`	date	none	دوره گزارش ≤ پایان (`priod_start` ≤ `priod_end` وقتی هر دو ست شوند). برای `fund_daily_asset` روی `as_of_date`
`last_periods`	int	none	فقط آخرین N دوره متمایز به‌ازای هر صندوق (۱–۴۸). برای `fund_daily_asset`: آخرین N روز `as_of_date`
`latest_only`	bool	`false`	اگر `true`، فقط آخرین دوره به‌ازای هر صندوق. برای `fund_daily_asset`: آخرین `as_of_date` به‌ازای هر صندوق
`transaction_types`	int[]	none	فقط `fund_transactions`: `1` = خرید، `2` = فروش (تکرارپذیر)

Pagination

Parameter	Type	Default	Description
`page`	int	`1`	شماره صفحه (≥ 1)
`page_size`	int	معمولاً ۲۰	تعداد آیتم در صفحه (≥ 1). سقف `EXTERNAL_API_MAX_PAGE_SIZE` (پیش‌فرض ۱۰۰)

Headers on success

Header	Meaning
`X-Request-Id`	Correlate with usage logs
`X-Credits-Charged`	IRR charged for this call
`X-Wallet-Balance`	Remaining wallet balance
`X-RateLimit-Limit-Minute`	Per-key minute limit for this service
`X-RateLimit-Remaining-Minute`	Remaining calls this minute
`X-RateLimit-Limit-Hour`	Per-key hour limit for this service
`X-RateLimit-Remaining-Hour`	Remaining calls this hour

Examples

پرتفوی آخرین دوره برای یک نماد پایه:

نمونه

curl -G "https://api.codal724.ir/api/v1/external/funds/data" \
  --data-urlencode "table_name=fund_portfolio" \
  --data-urlencode "tickers=فولاد" \
  --data-urlencode "latest_only=true" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=50" \
  -H "X-API-Key: cdl-724-…" \
  -H "Accept: application/json"

معاملات یک صندوق در بازه دوره:

نمونه

curl -G "https://api.codal724.ir/api/v1/external/funds/data" \
  --data-urlencode "table_name=fund_transactions" \
  --data-urlencode "fund_symbols=آگاس" \
  --data-urlencode "transaction_types=1" \
  --data-urlencode "transaction_types=2" \
  --data-urlencode "priod_start=2024-01-01" \
  --data-urlencode "priod_end=2024-12-31" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=50" \
  -H "X-API-Key: cdl-724-…" \
  -H "Accept: application/json"

دارایی روزانه (NAV) آخرین تاریخ برای یک صندوق:

نمونه

curl -G "https://api.codal724.ir/api/v1/external/funds/data" \
  --data-urlencode "table_name=fund_daily_asset" \
  --data-urlencode "fund_symbols=دوایکس" \
  --data-urlencode "latest_only=true" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=50" \
  -H "X-API-Key: cdl-724-…" \
  -H "Accept: application/json"

Errors

`error_code`	HTTP	When
`invalid_api_key`	401	Missing / unknown key
`revoked_api_key`	401	Key revoked
`insufficient_credits`	402	Wallet balance too low
`key_credit_limit_exceeded`	402	Key spend cap hit
`rate_limit_exceeded`	429	Per-key minute/hour limit
`rate_limit_unavailable`	503	Redis rate limiter down
`invalid_table`	400	Unknown `table_name`
`validation_error`	400	Bad query params

نمونه

{ "error_code": "insufficient_credits", "message": "…" }

(FastAPI may wrap as { "detail": { … } }.)

جداول (table_name)

پارامترهای کوئری

Required

Filters

Pagination

Headers on success

Examples

Errors

جداول (`table_name`)