کدال
صورت‌های مالی و افشاهای کدال (سود و زیان، ترازنامه، جریان نقد، تولید و فروش و …) با کلید API.
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.
/api/v1/external/codal/dataهمان فیلترهای خواندن همگام‌سازی کدال عمومی؛ page_size شریک علاوه بر آن با EXTERNAL_API_MAX_PAGE_SIZE محدود است (پیش‌فرض ۱۰۰).
جداول (table_name)
نام جدول به‌صورت case-insensitive است؛ خط تیره و نام‌های فشرده مثل IncomeStatement هم پذیرفته می‌شوند.
table_name | Description (EN) | Description (FA) |
|---|---|---|
income_statement | Income statement line items (profit and loss) | صورت سود و زیان — اقلام سود و زیان |
balance | Balance sheet line items | ترازنامه — اقلام دارایی، بدهی و حقوق صاحبان سهام |
cashflow | Cash flow statement line items | صورت جریان وجوه نقد |
buy_raw_material | Raw material purchase disclosures | خرید مواد اولیه |
energy | Energy consumption disclosures | مصرف انرژی |
source_uses_currency | Foreign-currency sources and uses | منابع و مصارف ارزی |
production_and_sales | Production and sales disclosures | تولید و فروش |
announcements | Qualitative Codal disclosures | افشاهای کیفی کدال |
پارامترهای کوئری
Required
| Parameter | Type | Description |
|---|---|---|
table_name | string | جدول هدف (جدول بالا) |
Mode
| Parameter | Type | Default | Description |
|---|---|---|---|
mode | rows | symbols | rows | rows = ردیف‌های داده‌ای صفحه‌بندی‌شده. symbols = فهرست متمایز نمادها (بدون صفحه‌بندی؛ page / page_size نادیده گرفته می‌شود) |
Symbol filters
پارامترهای تکرارپذیر؛ مقدار جداشده با کاما در یک پارامتر هم پشتیبانی می‌شود (symbols=فولاد,شپنا&symbols=فملی).
| Parameter | Type | Description |
|---|---|---|
symbols | string[] | تطابق دقیق روی symbol افشا (در صورت وجود ستون) |
main_symbols | string[] | تطابق دقیق روی main_symbol والد (در صورت وجود) |
Date and time filters
فقط وقتی جدول هدف ستون متناظر را داشته باشد اعمال می‌شوند؛ وگرنه نادیده گرفته می‌شوند. اگر هر دو ابتدا و انتها ست شوند، start باید ≤ end باشد.
| Parameter | Type | Column | Description |
|---|---|---|---|
period_start | date (YYYY-MM-DD) | period | دوره گزارش ≥ شروع |
period_end | date | period | دوره گزارش ≤ پایان |
finance_year_start | date | finance_year | شروع سال مالی ≥ |
finance_year_end | date | finance_year | پایان سال مالی ≤ |
publish_date_start | datetime (ISO 8601) | publish_date | زمان انتشار کدال ≥ |
publish_date_end | datetime | publish_date | زمان انتشار کدال ≤ |
updated_at_start | datetime | updated_at | آخرین همگام‌سازی ردیف ≥ |
updated_at_end | datetime | updated_at | آخرین همگام‌سازی ردیف ≤ |
Numeric and enum filters
| Parameter | Type | Applies to | Description |
|---|---|---|---|
reporting_type | integer | Fact tables (production_and_sales, buy_raw_material, energy, source_uses_currency) | تطابق دقیق کد دسته گزارش‌دهی شرکت |
report_type | string | announcements | تطابق دقیق برچسب نوع افشا |
Text filters (case-insensitive substring, ILIKE %value%)
فقط وقتی ستون روی جدول هدف وجود داشته باشد.
| Parameter | Tables |
|---|---|
item | income_statement, balance, cashflow, source_uses_currency |
product_name | production_and_sales |
material_name | buy_raw_material |
energy_type | energy |
industry | energy |
classification | energy |
currency_type | source_uses_currency |
category | source_uses_currency |
Sorting
| Parameter | Type | Default | Allowed values |
|---|---|---|---|
order_by | string | period | period, publish_date, updated_at, id, id_legacy, symbol |
order_dir | string | desc | asc, desc |
Pagination (mode=rows only)
| Parameter | Type | Default | Description |
|---|---|---|---|
page | int | 1 | شماره صفحه (≥ 1) |
page_size | int | معمولاً ۲۰ | تعداد آیتم در صفحه (≥ 1). سقف مؤثر min(MAX_PAGE_SIZE, EXTERNAL_API_MAX_PAGE_SIZE) (پیش‌فرض شریک ۱۰۰) |
Headers on success
| Header | Meaning |
|---|---|
X-Request-Id | همبستگی با usage logs |
X-Credits-Charged | ریال کسرشده برای این فراخوانی |
X-Wallet-Balance | موجودی باقی‌مانده کیف پول |
X-RateLimit-Limit-Minute | سقف درخواست در دقیقه برای این سرویس |
X-RateLimit-Remaining-Minute | باقی‌مانده در این دقیقه |
X-RateLimit-Limit-Hour | سقف درخواست در ساعت برای این سرویس |
X-RateLimit-Remaining-Hour | باقی‌مانده در این ساعت |
Examples
صورت سود و زیان برای یک نماد:
curl -G "https://api.codal724.ir/api/v1/external/codal/data" \
--data-urlencode "table_name=income_statement" \
--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/codal/data" \
--data-urlencode "table_name=cashflow" \
--data-urlencode "symbols=فولاد" \
--data-urlencode "period_start=2024-01-01" \
--data-urlencode "period_end=2024-12-31" \
--data-urlencode "order_by=period" \
--data-urlencode "order_dir=desc" \
-H "X-API-Key: cdl-724-…" \
-H "Accept: application/json"خرید مواد اولیه با فیلتر متنی:
curl -G "https://api.codal724.ir/api/v1/external/codal/data" \
--data-urlencode "table_name=buy_raw_material" \
--data-urlencode "symbols=فولاد" \
--data-urlencode "material_name=سنگ" \
--data-urlencode "mode=rows" \
--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": { … } }.)