داده تاریخی

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

قیمت یک روز یا بازه حداکثر ۳۱ روز را با 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 پاسخ داده می شود. این محدودیت طول یک درخواست است و به معنی وجود حتمی ۳۱ روز داده یا محدود بودن کل آرشیو به ۳۱ روز نیست.

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

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

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

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

خطاهای مهم

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

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

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

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

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

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

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

قیمت یک‌روزه، OHLC روزانه و ورودی تاریخ شمسی

مسیر GET /api/v1/assets/{assetName}/{date} به کلید API در هدر X-API-Key یا Authorization: ApiKey نیاز دارد. هر درخواست احرازشده به مسیرهای assets یک واحد از سهمیه کم می‌کند. کلید را در محل امن سمت سرور نگه دارید؛ آن را در URL یا کد مرورگر قرار ندهید.

چهار حالت سازگار درخواست

درخواست میلادی موجود همچنان پیش‌فرض است. اگر هیچ‌یک از دو پارامتر را نفرستید، پاسخ قدیمی با همان هشت فیلد حفظ می‌شود: code، name، slug، labelEn، labelFa، quoteUnit، value و businessTime.

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

مقدار پیش‌فرض calendar برابر gregorian است و می‌توانید آن را صریحاً هم بفرستید. با افزودن include=ohlc افزونهٔ روزانهٔ پاسخ دریافت می‌شود:

curl -sS "https://servix.cc/api/v1/assets/USD_RLS/2026-04-13?calendar=gregorian&include=ohlc" \
  -H "X-API-Key: <your-api-key>"

برای ورودی هجری شمسی، همان قالب دقیق YYYY-MM-DD را به کار ببرید و calendar=persian را صریحاً انتخاب کنید. تاریخ شمسی 1405-01-24 و تاریخ میلادی 2026-04-13 به یک روز می‌رسند:

curl -sS "https://servix.cc/api/v1/assets/USD_RLS/1405-01-24?calendar=persian" \
  -H "X-API-Key: <your-api-key>"

curl -sS "https://servix.cc/api/v1/assets/USD_RLS/1405-01-24?calendar=persian&include=ohlc" \
  -H "X-API-Key: <your-api-key>"

این نمونه‌های cURL برای اجرا در سمت سرور هستند. مقدارهای داخل کروشهٔ زاویه‌دار جای‌نگهدارند. انتخاب تقویم فقط تفسیر تاریخ مسیر را عوض می‌کند و منطقهٔ زمانی را تعیین نمی‌کند.

تفاوت value قدیمی با OHLC روزانه

value همان مقداری است که جست‌وجوی قدیمی برای آن تاریخ انتخاب می‌کند؛ میانگین روزانه نیست. با include=ohlc، فیلدهای open، high، low و close مشاهده‌های قابل اتکای روز را پس از رفع اصلاح‌های هم‌زمان خلاصه می‌کنند. مقدار close ممکن است به‌دلیل قواعد متفاوت انتخاب تاریخچه و اصلاح رکورد با value یکسان نباشد. قیمت‌ها عدد JSON و برحسب quoteUnit نماد، مانند RLS، هستند؛ جای‌نگهدارهای متنی در نمونه‌ها شماتیک‌اند و پاسخ عددی معتبر محسوب نمی‌شوند.

فیلدهای پاسخ روزانه

فیلد	معنا
`day.date`	تاریخ میلادیِ تبدیل‌شده، حتی اگر ورودی مسیر شمسی باشد.
`day.timeZone`	منطقهٔ زمانی مؤثر نشست پایگاه داده که جست‌وجوی قدیمی تاریخ از آن استفاده می‌کند.
`day.start` و `day.end`	دو زمان UTC برای روز محلی: شروع شامل بازه است و پایان در نیمه‌شب محلی بعدی از بازه خارج است. طول واقعی بازه لزوماً ۲۴ ساعت نیست.
`ohlc`	کندل روزانه یا در نبود مشاهدهٔ قابل اتکا `null`؛ کندل صفر یا مقدارِ پرشده از روز قبل ساخته نمی‌شود.
`ohlc.start` و `ohlc.end`	همان مرزهای کامل روز در UTC، حتی اگر مشاهده‌ها فقط بخشی از روز را پوشش دهند.
`ohlc.open`، `high`، `low` و `close`	به‌ترتیب نخستین، بیشترین، کمترین و آخرین مقدار قابل اتکای روز.
`ohlc.observationCount`	تعداد timestampها پس از رفع اصلاح‌های تکراری.
`ohlc.complete`	فقط وقتی درست است که روز تمام شده و تاریخچهٔ قابل اتکا از شروع روز یا پیش از آن آغاز شده باشد؛ نبود فاصلهٔ جمع‌آوری را تضمین نمی‌کند.
`ohlcAvailableFrom`	نخستین زمان شناخته‌شدهٔ تاریخچهٔ قابل اتکا یا در صورت نامشخص بودن `null`.
`ohlcStatus`	یکی از `AVAILABLE`، `PARTIAL` یا `UNAVAILABLE`.

AVAILABLE یعنی برای روزی که پایان یافته، کندل قابل اتکا وجود دارد و مرز شروع تاریخچه از شروع روز دیرتر نیست. PARTIAL یعنی مشاهده وجود دارد اما روز هنوز باز است یا تاریخچهٔ قابل اتکا در میانهٔ روز آغاز می‌شود. UNAVAILABLE یعنی ohlc برابر null است. حتی در این حالت ممکن است قیمت قدیمی value برگردد. نخستین روز پوشش و روز جاری می‌توانند ناقص باشند.

پنجرهٔ این مسیر از همان منطقهٔ زمانی مؤثر نشست پایگاه داده در جست‌وجوی قدیمی استفاده می‌کند. این قرارداد با کندل‌های UTC مسیر /api/v1/assets/{assetCode}/ohlc?interval=1d متفاوت است.

قالب تاریخ، محدوده و خطاها

سال باید چهار رقم، ماه و روز هرکدام دو رقم و جداکننده خط تیرهٔ لاتین باشد. رقم‌های لاتین، فارسی و عربی را می‌توان با هم ترکیب کرد. تاریخ شمسی نامعتبر یا ناممکن، از جمله روز کبیسهٔ نامعتبر، HTTP 400 با کد INVALID_PERSIAN_DATE می‌دهد. اگر تاریخ شمسی به قبل از 2000-01-01 یا بعد از 2050-12-31 میلادی تبدیل شود، کد PERSIAN_DATE_OUT_OF_RANGE برمی‌گردد؛ دو سر بازه پذیرفته می‌شوند. رفتار قبلی ورودی میلادی تغییر نکرده است. مقدار خالی، تکراری یا پشتیبانی‌نشدهٔ calendar با HTTP 400 و کد UNSUPPORTED_CALENDAR و مقدار خالی، تکراری، جداشده با ویرگول یا پشتیبانی‌نشدهٔ include با HTTP 400 و کد UNSUPPORTED_INCLUDE پاسخ داده می‌شود. تاریخ میلادی نامعتبر همان INVALID_REQUEST_PARAMETER قبلی را دارد. برای نماد معتبر بدون رکورد آن روز، HTTP 404 با کد ASSET_NOT_FOUND دریافت می‌کنید. خطاهای احراز هویت، دسترسی حساب و سهمیه به‌ترتیب HTTP 401، 403 و 429 هستند.

برای schema و نمونه‌های امن، مرجع اندپوینت‌ها، سند OpenAPI و مجموعه Postman را ببینید. قرارداد کندل OHLC بازه‌ای همچنان از bucketهای UTC استفاده می‌کند.

قیمت خرید و فروش همان مشاهده

قیمت سمت‌های مشاهدهٔ ذخیره‌شده: buyPrice قیمت خرید فروشنده از مشتری و sellPrice قیمت فروش به مشتری است. هر سمت متعلق به همان مشاهدهٔ value با همان quoteUnit و businessTime است و به صورت عدد دقیق JSON یا، در صورت ذخیره‌نشدن، صریحاً null برمی‌گردد. در مشاهده‌های قدیمی ممکن است یک یا هر دو سمت ناموجود باشند. قیمت میانی، قیمت قبلی یا قیمت فعلی جایگزین نمی‌شود. calendar=persian فقط تاریخ مسیر را به همان روز میلادی تبدیل می‌کند؛ include=ohlc کندل قیمت میانی را اضافه می‌کند و مشاهدهٔ انتخاب‌شده را تغییر نمی‌دهد. مسیر GET تاریخچه و بازهٔ POST معادل، آخرین مشاهدهٔ انتخاب‌شدهٔ هر روز موجود در نتیجهٔ جست‌وجوی قبلی را برمی‌گردانند؛ روز ناموجود پر نمی‌شود. این تغییر دادهٔ تاریخی تامین‌کننده را دریافت یا بازسازی نمی‌کند.

نمونهٔ مشاهدهٔ ذخیره‌شده (مقادیر محافظت‌شده):

{
  "code": "USD_RLS",
  "name": "USD_RLS",
  "slug": "usd_rls",
  "labelEn": "US Dollar / Iranian Rial",
  "labelFa": "دلار آمریکا / ریال ایران",
  "quoteUnit": "RLS",
  "value": "<protected-market-value>",
  "businessTime": "<source-timestamp>",
  "buyPrice": "<protected-market-value>",
  "sellPrice": "<protected-market-value>"
}

نمونهٔ جداگانهٔ سمت ناموجود (مقادیر محافظت‌شده):

{
  "buyPrice": "<protected-market-value>",
  "sellPrice": null
}