قراردادها
آدرس پایه، احراز هویت تحلیلگر و شریک (X-API-Key)، زبان خروجی و فرمت خطا (code و error_code).
راهنمای مشترک برای فراخوانی تحلیلگر نماد و تحلیلگر پرتفوی، به‌علاوه قرارداد محصولات دادهٔ شریک (کدال، صندوق‌ها، کالاها و گزارش‌ها).
Base URL
https://api.codal724.ir/api/v1در محیط توسعه:
http://localhost:8000/api/v1Authentication
| API | Auth |
|---|---|
| تحلیلگر نماد | عمومی — بدون توکن |
| تحلیلگر پرتفوی | الزامی — Authorization: Bearer <access_token> |
توکن دسترسی از طریق OTP موبایل صادر می‌شود (POST /auth/otp/send → POST /auth/otp/verify).
Localization
پارامتر locale در query:
| Value | Output |
|---|---|
fa | فارسی (پیش‌فرض) |
en | English |
Error format
{
"code": "not_found",
"message": "Resource not found"
}| HTTP | Typical code |
|---|---|
| 401 | unauthorized |
| 404 | not_found |
| 422 | bad_request |
| 429 | rate_limited |
Rate limits
محدودیت نرخ تحلیلگر بر اساس پلن اشتراک اعمال می‌شود. برای افزایش سقف با api@codal724.ir تماس بگیرید.
Partner data APIs
محصولات دادهٔ شریک جدا از تحلیلگر نماد/پرتفوی هستند. مسیرهای عمومی /api/v1/codal و /api/v1/funds رایگان می‌مانند — کلید شریک را برای صورتحساب به آن‌ها نفرستید.
جزئیات ساخت کلید، کیف پول و مصرف در «دسترسی من» (/api-docs/my-access) است: POST/GET /external/keys، POST /external/keys/{id}/revoke، GET /external/wallet، POST/GET /external/payments، GET /external/usage-logs، GET /external/health.
Partner authentication
| API | Auth |
|---|---|
GET /external/codal/data | X-API-Key: cdl-724-… یا Authorization: Bearer cdl-724-… |
GET /external/funds/data | همان کلید API |
GET /external/timeseries/data | همان کلید API |
GET /external/reports/data | همان کلید API |
| کلیدها، کیف پول، مصرف، وب‌هوک، سلامت | JWT کاربر Authorization: Bearer <access_token> (OTP)، همان حساب اپ |
هر کلید فعال به همهٔ جداول پشتیبانی‌شدهٔ کدال، صندوق‌ها، سری زمانی و گزارش‌ها دسترسی دارد. مقدار ذخیره‌شدهٔ scopes فقط اطلاعات قدیمی است و دسترسی را محدود نمی‌کند.
Partner error format
مسیرهای شریک از error_code استفاده می‌کنند (نه code). FastAPI اغلب به شکل { "detail": { … } } می‌پیچد.
{ "error_code": "insufficient_credits", "message": "…" }error_code | HTTP | When |
|---|---|---|
invalid_api_key | 401 | Missing / unknown key |
revoked_api_key | 401 | Key revoked |
insufficient_credits | 402 | Wallet 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 limiter down |
invalid_table | 400 | Unknown table_name |
validation_error | 400 | Bad query params |
Partner rate limits
محدودیت به‌ازای هر کلید + سرویس اعمال می‌شود (نه محدودکنندهٔ اشتراک تحلیلگر). روی 429: هدر Retry-After و error_code: rate_limit_exceeded.
پیش‌فرض محیط: ۶۰ درخواست در دقیقه و ۲۰۰۰ در ساعت برای codal، funds، reports و timeseries.
صورتحساب: base_irr + rows_returned × per_row_irr (پیش‌فرض محیط: پایه ۱۰۰۰، به‌ازای هر ردیف ۱۰ ریال). درخواست‌های ناموفق با cost_irr: 0 ثبت می‌شوند.
هدرهای موفقیت (هر چهار محصول داده):
| Header | Meaning |
|---|---|
X-Request-Id | Correlate with usage logs |
X-Credits-Charged | IRR charged |
X-Wallet-Balance | Remaining wallet |
X-RateLimit-Limit-Minute | Per-key minute limit for this service |
X-RateLimit-Remaining-Minute | Remaining this minute |
X-RateLimit-Limit-Hour | Per-key hour limit |
X-RateLimit-Remaining-Hour | Remaining this hour |