شروع کار با API سرویکس

این راهنما کوتاه‌ترین مسیر از ساخت حساب تا دریافت نخستین پاسخ احرازشده سرویکس است. هر حساب، شروع رایگان دائمی با روزانه ۵۰ درخواست، یک کلید API فعال و دسترسی به همهٔ اندپوینت‌های مستند دارد. نه فعال‌سازی آزمایشی لازم است و نه اطلاعات پرداخت.

۱. حساب بسازید

ثبت‌نام کنید یا وارد حساب شوید. شروع رایگان همان لحظه در دسترس است و تاریخ انقضا ندارد.

۲. کلید API بسازید

در بخش Profile > API Keys یک کلید فعال بسازید. کلید را در سامانهٔ مدیریت اسرار یا متغیر محیطیِ سرور نگه دارید؛ آن را در کد مرورگر، URL، مخزن عمومی یا پیام پشتیبانی قرار ندهید.

۳. نخستین درخواست را بفرستید

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

قرارداد دقیق پاسخ، فیلد quoteUnit را دارد. واحد را از همین فیلد نمایش دهید و از روی نام نماد حدس نزنید.

{
  "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>",
  "midPrice": "<protected-market-value>"
}

۴. اتصال را کامل کنید

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

ادامهٔ مسیر با Vue 3 و Pinia

اگر برنامهٔ مرورگری می‌سازید، راهنمای تست‌شدهٔ Vue 3، Pinia و Composition API را دنبال کنید. در این نمونه، کلید API سرویکس پشت پراکسی هم‌مبدأ در بک‌اند می‌ماند و وضعیت تایپ‌شدهٔ رابط کاربری به قرارداد اصلی سرویس وصل می‌شود.

کار تعاملی در پنل: برای انتخاب چند دارایی، دیدن جدول بعد از تأیید سهمیه و دریافت Excel یا JSON، معرفی کاوشگر داده بازار را بخوانید.

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

قیمت سمت‌های مشاهدهٔ ذخیره‌شده: 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
}