کلید API/api/v1

گزارش‌ها

گزارش نماد (AI) و گزارش روزانه بازار — فقط ردیف‌های ذخیره‌شده، بدون تولید زنده LLM.

دسترسی شریک به گزارش‌های ذخیره‌شده نماد و گزارش روزانه بازار از طریق کلید API. این مسیر محتوا را با LLM تولید نمی‌کند؛ فقط ردیف‌های آماده را برمی‌گرداند.

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

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

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

GET/api/v1/external/reports/data

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

جداول (`table_name`)

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

`table_name`	Aliases	Description (EN)	Description (FA)
`symbol_reports`	`symbol_report`	Latest ready AI symbol report per ticker	آخرین گزارش آمادهٔ نماد (markdown + sections + embeds)
`market_daily_reports`	`market_daily_report`, `market`	Market-wide daily wrap	گزارش روزانهٔ بازار

خارج از این API: گزارش روزانه به‌ازای نماد (symbol_daily_reports) ارائه نمی‌شود.

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

Parameter	Type	Tables	Description
`table_name`	string	هر دو	الزامی
`symbols`	string[]	`symbol_reports`	تطابق دقیق روی نماد؛ تکرارپذیر یا جداشده با کاما
`published_at_start` / `published_at_end`	datetime ISO 8601	`symbol_reports`	فیلتر `published_at` آخرین گزارش آماده
`trade_date`	date `YYYY-MM-DD`	`market_daily_reports`	تاریخ معامله دقیق
`trade_date_start` / `trade_date_end`	date	`market_daily_reports`	بازهٔ شامل ابتدا و انتها
`updated_at_start`	datetime	`market_daily_reports`	دریافت افزایشی بعد از وب‌هوک
`page`	int	هر دو	پیش‌فرض `1`
`page_size`	int	هر دو	معمولاً ۲۰؛ سقف ۱۰۰

شکل پاسخ

همان پوشش کدال/صندوق‌ها: items, total, page, page_size, pages, has_next, has_prev, meta.table_name.

آیتم symbol_reports

نمونه

{
  "report_id": "…",
  "symbol": "فولاد",
  "version": 3,
  "published_at": "2026-09-06T12:00:00+00:00",
  "rendered_markdown": "# …",
  "sections": {},
  "embeds": []
}

آیتم market_daily_reports

نمونه

{
  "trade_date": "2026-09-06",
  "j_date": "1405/06/15",
  "markdown": "…",
  "slots": {},
  "metrics": {}
}

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/reports/data" \
  --data-urlencode "table_name=symbol_reports" \
  --data-urlencode "symbols=فولاد" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  -H "X-API-Key: cdl-724-…" \
  -H "Accept: application/json"

گزارش روزانه بازار برای یک تاریخ معامله:

نمونه

curl -G "https://api.codal724.ir/api/v1/external/reports/data" \
  --data-urlencode "table_name=market_daily_reports" \
  --data-urlencode "trade_date=2026-09-06" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  -H "X-API-Key: cdl-724-…" \
  -H "Accept: application/json"

بعد از وب‌هوک reports.table.updated:

نماد: table_name=symbol_reports&published_at_start=<last_updated_at> (اختیاری symbols=)
بازار: table_name=market_daily_reports&updated_at_start=<last_updated_at> یا trade_date=

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)

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

شکل پاسخ

Headers on success

Examples

Errors

جداول (`table_name`)