کلید API/api/v1

کالاها

سری زمانی کالاها، ارز، طلا، رمزارز، فلزات و انرژی با کلید API.

دسترسی شریک به تاریخچه شاخص‌های بازار TGJU شامل ارز، طلای داخلی، رمزارز، فلزات و انرژی از طریق کلید API.

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

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

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

GET/api/v1/external/timeseries/data

تنها جدول مجاز timeseries است. نام‌های time_series و شکل‌های خط‌تیره‌دار یا فشرده آن نیز به‌عنوان alias پذیرفته می‌شوند. تاریخ‌ها میلادی هستند.

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

Parameter	Type	Default	Description
`table_name`	string	required	باید `timeseries` یا یکی از aliasهای آن باشد
`indicators`	string[]	همه شاخص‌ها	ستون‌های خروجی؛ پارامتر تکراری یا فهرست جداشده با کاما. slugهای خط‌تیره‌دار TGJU به نام ستون underscore تبدیل می‌شوند
`date_start`	date (`YYYY-MM-DD`)	none	تاریخ شروع میلادی، شامل همان روز
`date_end`	date (`YYYY-MM-DD`)	none	تاریخ پایان میلادی، شامل همان روز؛ باید مساوی یا بعد از `date_start` باشد
`order_dir`	`asc` \| `desc`	`desc`	ترتیب بر اساس تاریخ. برای نمودار از `asc` استفاده کنید
`page`	int	`1`	شماره صفحه (≥ 1)
`page_size`	int	پیش‌فرض سرور	تعداد ردیف؛ سقف `EXTERNAL_API_MAX_PAGE_SIZE` (پیش‌فرض ۱۰۰)

اگر indicators ارسال نشود، همه ستون‌های عمومی بازگردانده می‌شوند. در صورت ارسال، پاسخ فقط شامل date و شاخص‌های درخواستی است. نام ناشناخته با 400 validation_error رد می‌شود. مقادیر عددی به‌صورت JSON number و داده‌های ناموجود به‌صورت null برمی‌گردند؛ ستون‌های داخلی منتشر نمی‌شوند.

شاخص‌های پشتیبانی‌شده

گروه	Indicator names
طلای داخلی و سکه	`geram18`, `geram24`, `mesghal`, `gold_mini_size`, `gold_futures`, `sekeb`, `sekee`, `nim`, `rob`, `gerami`, `silver_999`
رمزارز (USD)	`crypto_bitcoin`, `crypto_ethereum`, `crypto_dogecoin`, `crypto_ripple`, `crypto_tron`, `crypto_dash`, `crypto_stellar`, `crypto_cardano`, `crypto_litecoin`, `crypto_solana`, `crypto_avalanche`, `crypto_verge`, `crypto_monero`
ارز (IRR)	`price_dollar_rl`, `nima_sell_usd`, `nima_buy_usd`, `sana_sell_usd`, `sana_buy_usd`, `price_eur`, `nima_buy_eur`, `nima_sell_eur`, `sana_sell_eur`, `sana_buy_eur`, `bank_eur`, `nima_buy_gbp`, `nima_sell_gbp`, `sana_sell_gbp`, `sana_buy_gbp`, `bank_gbp`, `price_aed`, `price_gbp`, `price_sek`, `price_jpy`, `price_sar`, `price_cny`, `price_rub`, `price_try`
فلزات گران‌بها	`ons`, `silver`, `platinum`, `palladium`
فلزات پایه	`basemetal_aluminum`, `base_global_lead`, `basemetal_nickel`, `base_global_zinc`, `base_global_tin`, `base_global_copper`
انرژی	`energy_crude_oil`, `energy_brent_oil`, `oil_opec`, `energy_heating_oil`, `louisiana_light`, `energy_london_gas_oil`, `energy_gasoline_rbob`, `energy_natural_gas`, `energy_carbon_emissions`, `energy_ethanol_futures_contracts`, `lng_japan_korea_marker`

نمونه درخواست

نمونه

curl -G "https://api.codal724.ir/api/v1/external/timeseries/data" \
  --data-urlencode "table_name=timeseries" \
  --data-urlencode "indicators=price_dollar_rl,geram18" \
  --data-urlencode "date_start=2026-09-01" \
  --data-urlencode "date_end=2026-09-14" \
  --data-urlencode "order_dir=asc" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  -H "X-API-Key: cdl-724-…" \
  -H "Accept: application/json"

پاسخ `200`

نمونه

{
  "items": [
    {
      "date": "2026-09-01",
      "price_dollar_rl": 1025000.0,
      "geram18": 87500000.0
    }
  ],
  "total": 14,
  "page": 1,
  "page_size": 20,
  "pages": 1,
  "has_next": false,
  "has_prev": false,
  "meta": { "table_name": "timeseries", "mode": null }
}

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

ترتیب پیش‌فرض desc است؛ بنابراین اولین ردیف الزاماً قدیمی‌ترین داده نیست. برای نمایش نمودار یا پردازش زمانی، شاخص‌های لازم را انتخاب و order_dir=asc ارسال کنید.

در این نسخه برای به‌روزرسانی Timeseries وب‌هوک ارسال نمی‌شود؛ برای تشخیص به‌روزرسانی، /api/v1/external/health یا همین endpoint را poll کنید.

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 dates, order, indicator names, or pagination

نمونه

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

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

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

شاخص‌های پشتیبانی‌شده

نمونه درخواست

پاسخ 200

Headers on success

Errors

پاسخ `200`