معرفی وب سرویس

وب سرویس راکس کد ابزاری قدرتمند و حرفه‌ای است که امکان دسترسی لحظه‌ای به نرخ ارز، طلا و سکه را فراهم می‌کند. این API به شما این امکان را می‌دهد تا با استفاده از متد استاندارد GET، داده‌های مالی به‌روز را دریافت کرده و همچنین آرشیو تغییرات قیمتی را در بازه‌های زمانی مشخص یا به‌صورت روزانه مشاهده کنید. این سرویس به‌طور ویژه برای توسعه‌دهندگان اپلیکیشن‌ها و وب‌سایت‌هایی که به داده‌های مالی سریع و دقیق نیاز دارند، طراحی شده است.

  • سرعت و دقت: ارائه اطلاعات لحظه‌ای و دقیق برای اطمینان از به‌روز بودن داده‌ها.
  • سهولت استفاده: طراحی ساده و مستندات جامع برای شروع سریع و بدون پیچیدگی.
  • انعطاف‌پذیری: امکان دریافت آرشیو قیمتی و نرخ‌های لحظه‌ای بر اساس نیاز کاربر.
  • امنیت بالا: دسترسی ایمن با استفاده از کلید API (API Key) اختصاصی.

برای استفاده از این وب سرویس شما نیاز به تهییه لایسنس جهت استفاده دارید

خرید وب سرویس

دریافت نرخ لحظه ای ارز

وب سرویس راکس کد ارائه‌دهنده یک endpoint کارآمد برای دریافت نرخ‌های لحظه‌ای ارز، طلا و سکه است. این endpoint به شما اجازه می‌دهد تا اطلاعات به‌روز قیمت‌ها را در قالب JSON و به‌صورت لحظه‌ای دریافت کنید، که برای برنامه‌های مالی و تحلیل‌های بازار بسیار مناسب است.


اندپوینت

برای دریافت نرخ لحظه‌ای از اندپوینت زیر استفاده کنید:

https://ws.roxcode.net/api/currency/list
GET /list

برای استفاده از سندباکس از اندپوینت زیر بدون پارامتر استفاده کنید، کافیست تنها اندپوینت فراخوانی شود:

https://ws.roxcode.net/api/currency/list/sandbox
GET /list/sandbox
                        
<?php
// URL endpoint
$url = 'https://app.raxcod.net/api/currency/list';

// API key
$apiKey = 'YOUR_API_KEY';

// Initialize cURL
$ch = curl_init($url);

// Set cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey
]);

// Execute cURL request
$response = curl_exec($ch);

// Close cURL
curl_close($ch);

// Decode JSON response
$data = json_decode($response, true);

// Output data
print_r($data);
?>
                            

پارامترهای ورودی

فیلد نوع توضیحات
api_key رشته کلید API شما برای احراز هویت و دسترسی به سرویس.

وب سرویس دریافت آرشیو تغییرات یک روز

با استفاده از این وب سرویس، شما می‌توانید تغییرات قیمت یک ارز یا طلا را در یک روز خاص دریافت کنید. این سرویس شامل اطلاعات دقیقی از زمان و قیمت شروع معامله، تغییرات قیمتی در طول روز، و قیمت بسته شدن در پایان روز است. به عنوان مثال، می‌توانید اطلاعاتی راجع به دلار در تاریخ 18 مهر 1400 مشاهده کنید که شامل زمان و قیمت شروع، تغییرات قیمتی و زمان بسته شدن می‌باشد.

ساختار پاسخ

پاسخ این سرویس یک آرایه از اشیاء است که هر شیء نشان‌دهنده یک تغییر قیمت در زمان مشخص می‌باشد.

در این ساختار:

  • timestamp: زمان تغییر قیمت به صورت timestamp (ثانیه از 1970-01-01).
  • date: تاریخ تغییر قیمت به فرمت YYYY-MM-DD.
  • value: قیمت ارز یا طلا در زمان تغییر.
  • change: مقدار تغییر قیمت نسبت به قیمت قبلی (اگر تغییری وجود نداشته باشد، این فیلد خالی است).


اندپوینت

برای دریافت تاریخچه روزانه نرخ ارزها، از اندپوینت زیر استفاده کنید:

https://ws.roxcode.net/api/currency/day
GET /day

برای استفاده از سندباکس از اندپوینت زیر بدون پارامتر استفاده کنید، کافیست تنها اندپوینت فراخوانی شود:

https://ws.roxcode.net/api/currency/day/sandbox
GET /day/sandbox
                        
// Set parameters for the API request
$date = '2024-12-01';
$currency = 'USD';
$licenseKey = 'your-license-key-here';

// Set the API URL
$url = 'https://api.example.com/day';

// Initialize cURL request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'date' => $date,
    'currency' => $currency,
    'licenseKey' => $licenseKey
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Send the request and get the response
$response = curl_exec($ch);

// Check for errors
if (curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo 'API Response: ' . $response;
}

// Close the cURL session
curl_close($ch);

                        
تاریخ مدنظر باید از نوع Timestamp یا میلادی به فرمت Y-m-d باشد
پاسخ شامل آرایه های زمان، قیمت، تغییر می باشد که به صورت مقابل ساختار بندی شده اند

پارامترهای ورودی

فیلد نوع توضیحات
license_key رشته اجباری کلید API شما برای احراز هویت و دسترسی به سرویس.
currency رشته بله طلا/ارز مورد درخواست
date تاریخ بله تاریح مورد درخواست

وب سرویس آرشیو روزانه

این وب سرویس امکان دریافت آرشیو نرخ‌های روزانه برای ارز یا دارایی‌های مختلف را فراهم می‌کند. کاربران می‌توانند نرخ‌های آغاز روز (Open)، بیشینه روز (High)، کمینه روز (Low) و پایان روز (Close) را در بازه‌های زمانی مورد نظر بازیابی کنند. این داده‌ها برای تحلیل‌های مالی، بررسی روندها و گزارش‌دهی بسیار کاربردی هستند.

نحوه استفاده از وب سرویس

برای استفاده از این وب سرویس، لازم است درخواست خود را به اندپوینت مربوطه ارسال کنید و پارامترهای مورد نیاز شامل بازه زمانی (تاریخ شروع و پایان)، نوع ارز و کلید لایسنس (licenseKey) را در درخواست خود مشخص نمایید.

ساختار خروجی

داده‌های خروجی به فرمت JSON ارائه می‌شوند و شامل اطلاعات زیر هستند:

  • timestamp: زمان درخواست به صورت یونیکس تایم
  • date: تاریخ به فرمت شمسی
  • open: نرخ آغاز روز
  • high: بیشینه نرخ در روز
  • low: کمینه نرخ در روز
  • close: نرخ پایان روز


اندپوینت

برای دریافت تاریخچه نرخ ارزها، از اندپوینت زیر استفاده کنید:

https://ws.roxcode.net/api/currency/between
GET /between

برای استفاده از سندباکس از اندپوینت زیر بدون پارامتر استفاده کنید، کافیست تنها اندپوینت فراخوانی شود:

https://ws.roxcode.net/api/currency/between/sandbox
GET /between/sandbox

    // Set parameters for the API request
    $date = '2024-12-01';
    $currency = 'USD';
    $licenseKey = 'your-license-key-here';

    // Set the API URL
    $url = 'https://api.example.com/day/archive';

    // Initialize cURL request
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
        'date' => $date,
        'currency' => $currency,
        'licenseKey' => $licenseKey
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Send the request and get the response
    $response = curl_exec($ch);

    // Check for errors
    if (curl_errno($ch)) {
        echo 'Error: ' . curl_error($ch);
    } else {
        echo 'API Response: ' . $response;
    }

    // Close the cURL session
    curl_close($ch);
?>

تاریخ مدنظر باید از نوع Timestamp یا میلادی به فرمت Y-m-d باشد
پاسخ شامل آرایه های زمان، آغاز روز، بیشینه، کمینه، پایان روز می باشد که به صورت مقابل ساختار بندی شده اند

پارامترهای ورودی

فیلد نوع اجباری توضیحات
licenseKey رشته کلید API شما برای احراز هویت و دسترسی به سرویس.
start تاریخ بله تاریخ شروع مورد درخواست
end تاریخ بله تاریخ پایان مورد درخواست
currency رشته بله طلا/ارز مورد درخواست

کدهای خطا و توضیحات

در صورتی که درخواست شما با مشکلی مواجه شود، سرور یکی از کدهای خطا را همراه با توضیحات مناسب برمی‌گرداند. این کدها در قالب یک شیء JSON با ساختار زیر بازگشت داده می‌شوند:

لیست خطاها:

کد خطا عنوان خطا توضیحات دقیق
503 سرویس در دسترس نیست این خطا نشان‌دهنده آن است که سرویس در حال حاضر در دسترس نیست و درخواست شما نمی‌تواند پردازش شود. ممکن است سرویس تحت تعمیرات یا مشکلات شبکه باشد. لطفاً بعد از مدتی دوباره تلاش کنید.
404 لینک اشتباه است این خطا به این معناست که مسیر درخواست شده در سرور موجود نیست. لطفاً آدرس URL را بررسی کرده و از صحت آن اطمینان حاصل کنید. این ممکن است ناشی از اشتباه در تایپ URL یا حذف منابع باشد.
10 خطای مربوط به وب سرویس این خطا نشان‌دهنده وجود مشکلی در پردازش درخواست توسط وب سرویس است. معمولاً این خطا ناشی از مشکلات داخلی سرور می‌باشد. در صورت دریافت این خطا، کاربر باید آن را به تیم پشتیبانی گزارش دهد تا بررسی و رفع مشکل صورت گیرد.
20 لایسنس معتبر نیست این خطا نشان‌دهنده آن است که لایسنس استفاده شده برای درخواست، معتبر نمی‌باشد. ممکن است لایسنس منقضی شده باشد یا به درستی فعال نشده باشد. برای رفع این مشکل، لازم است که لایسنس معتبر دریافت و وارد شود.
21 محدودیت تعداد درخواست به سرویس در هر ساعت این خطا زمانی رخ می‌دهد که تعداد درخواست‌های مجاز برای استفاده از سرویس در یک ساعت خاص به پایان رسیده باشد. کاربر تا یک ساعت بعد از آخرین درخواست، نمی‌تواند درخواست جدیدی ارسال کند. برای رفع مشکل، لازم است که کاربر صبر کند و بعد از گذشت یک ساعت دوباره تلاش کند.
22 محدودیت تعداد درخواست روزانه این خطا نشان‌دهنده آن است که تعداد درخواست‌های مجاز برای یک روز به پایان رسیده است. کاربر تا روز بعد نمی‌تواند درخواست جدیدی ارسال کند. برای رفع این مشکل، کاربر باید صبر کند تا به روز بعد منتقل شود.
23 اعتبار ماهانه لایسنس به پایان رسیده این خطا به این معناست که اعتبار ماهانه لایسنس به پایان رسیده است. برای استفاده از سرویس باید لایسنس جدید خریداری و فعال شود تا امکان ارسال درخواست‌ها فراهم گردد. کاربر باید منتظر شروع ماه بعد شود تا بتواند درخواست جدید ارسال کند.
30 تاریخ ارسال شده نامعتبر است این خطا نشان‌دهنده آن است که تاریخ وارد شده در درخواست به فرمت صحیح نمی‌باشد یا خارج از محدوده مجاز است. لطفاً تاریخ ارسال شده را به فرمت صحیح (YYYY-MM-DD) وارد کرده و دوباره درخواست را ارسال کنید.

ساختار خطاهای بازگشتی از سرور:

                    {
    "err_code": <کد خطا>,
    "message": "<توضیحات خطا>"
}