دریافت تاریخچه قیمت و قیمت روز مشخص از API Servix

API تاریخی برای نمودار، گزارش، مقایسه تغییرات و بازسازی وضعیت گذشته طراحی شده است. تاریخ ها میلادی و با قالب YYYY-MM-DD هستند. وجود رکورد برای همه روزها تضمین نمی شود؛ تعطیلی بازار، زمان شروع آرشیو یا دسترس نبودن منبع می تواند بین روزها فاصله ایجاد کند.

قیمت یک روز مشخص

GET /api/v1/assets/{assetName}/{date}

curl -sS https://servix.cc/api/v1/assets/USD_RLS/2026-04-13 \
  -H "X-API-Key: pk_live_your_key_here"

date باید دقیقا مانند 2026-04-13 نوشته شود. اگر نماد معتبر باشد اما در آن روز رکوردی وجود نداشته باشد، پاسخ 404 با code برابر ASSET_NOT_FOUND برمی گردد.

بازه تاریخ با query parameter

GET /api/v1/assets/{assetName}/history?from=YYYY-MM-DD&to=YYYY-MM-DD

curl -sS "https://servix.cc/api/v1/assets/USD_RLS/history?from=2026-04-01&to=2026-04-13" \
  -H "X-API-Key: pk_live_your_key_here"

from و to هر دو اجباری هستند. خروجی یک آرایه از همان ساختار قیمت است و ممکن است خالی باشد. ترتیب یا تعداد رکورد را به تعداد روزهای تقویمی مساوی فرض نکنید.

بازه تاریخ با بدنه JSON

برای کلاینت هایی که ترجیح می دهند بازه را در body بفرستند، عملیات POST موجود است و قرارداد داده را تغییر نمی دهد:

curl -sS https://servix.cc/api/v1/assets/USD_RLS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_live_your_key_here" \
  -d '{"fromDate":"2026-04-01","toDate":"2026-04-13"}'

محدودیت ۳۱ روز

فاصله from تا to در هر درخواست نباید بیشتر از ۳۱ روز باشد و to نمی تواند پیش از from قرار گیرد. بازه نامعتبر با وضعیت 417 و code برابر INVALID_DATE_RANGE پاسخ داده می شود. این محدودیت طول یک درخواست است و به معنی وجود حتمی ۳۱ روز داده یا محدود بودن کل آرشیو به ۳۱ روز نیست.

الگوی درست برای بازه های بلندتر

1. بازه بزرگ را در بک اند خود به قطعه های حداکثر ۳۱ روز تقسیم کنید؛
2. هر قطعه را با فاصله منطقی و retry محدود فراخوانی کنید؛
3. نتیجه را بر اساس code و businessTime ادغام و تکراری ها را حذف کنید؛
4. داده دریافت شده را cache یا ذخیره کنید تا همان بازه بی دلیل دوباره فراخوانی نشود؛
5. برای 429 تا شروع دوره سهمیه بعدی صبر کنید و درخواست را بی وقفه تکرار نکنید.

زمان و کیفیت داده

businessTime زمان رکورد بازار است. برای تشخیص قدیمی بودن آخرین مقدار و پوشش منبع، کاتالوگ supported را نیز مصرف کنید. درباره واحد، اصلاح رکورد و محدودیت منبع، روش شناسی داده مرجع مکمل است.

خطاهای مهم

• 400 برای تاریخ با قالب نامعتبر یا پارامتر اجباری حذف شده؛
• 401 برای API Key نامعتبر؛
• 404 برای نماد یا رکورد موجود نبودن؛
• 417 برای ترتیب یا طول نامعتبر بازه؛
• 429 برای پایان سهمیه روزانه.

ساختار کامل خطا و روش retry در راهنمای خطاها و نمونه های قابل اجرا در مجموعه Postman قرار دارد.

نمونه های بازار و مرحله بعد

برای بررسی واحد و وضعیت عملیاتی نمادها، صفحه های عمومی نرخ ارز، قیمت طلا و قیمت سکه را ببینید. اگر می خواهید تاریخچه یا قیمت جاری را در پیام رسان منتشر کنید، راهنمای ساخت ربات قیمت تلگرام جریان کامل دریافت، کنترل تازگی و ارسال پیام را نشان می دهد.

از مستندات تا اولین درخواست موفق

ابتدا احراز هویت و نگهداری امن API Key را مرور کنید. سپس یک حساب بسازید، حساب تست را فعال کنید و نمونه همین صفحه را با کلید خود اجرا کنید. برای استفاده مداوم، سهمیه مورد نیاز را در صفحه پلن ها مقایسه کنید.

ساخت حساب و شروع آزمایش API سرویکس