معرفی وب سرویس
وب سرویس راکس کد ابزاری قدرتمند و حرفهای است که امکان دسترسی لحظهای به نرخ ارز، طلا و سکه را فراهم میکند. این 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);
?>
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
// URL endpoint
string url = "https://app.raxcod.net/api/currency/list";
// API key
string apiKey = "YOUR_API_KEY";
using (HttpClient client = new HttpClient())
{
// Add API key to header
client.DefaultRequestHeaders.Add("Authorization", "Bearer " + apiKey);
// Send GET request
HttpResponseMessage response = await client.GetAsync(url);
response.EnsureSuccessStatusCode();
// Read response content
string responseBody = await response.Content.ReadAsStringAsync();
// Output response
Console.WriteLine(responseBody);
}
}
}
const fetchData = async () => {
// URL endpoint
const url = 'https://app.raxcod.net/api/currency/list';
// API key
const apiKey = 'YOUR_API_KEY';
try {
// Fetch data
const response = await fetch(url, {
headers: {
'Authorization': `Bearer ${apiKey}`
}
});
// Check if response is ok
if (!response.ok) {
throw new Error('Network response was not ok');
}
// Parse JSON response
const data = await response.json();
// Output data
console.log(data);
} catch (error) {
console.error('There has been a problem with your fetch operation:', error);
}
};
// Call function
fetchData();
{
"harat_naghdi_buy": {
"value": "68470",
"change": 0,
"timestamp": 1731598097,
"date": "1403-08-24 18:58:17"
},
"harat_naghdi_sell": {
"value": "69810",
"change": 320,
"timestamp": 1732811362,
"date": "1403-09-08 19:59:22"
},
"sekkeh": {
"value": "51760",
"change": 340,
"timestamp": 1732815768,
"date": "1403-09-08 21:12:48"
}
}
پارامترهای ورودی
فیلد | نوع | توضیحات |
---|---|---|
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);
// Set parameters for the API request
const date = '2024-12-01';
const currency = 'USD';
const licenseKey = 'your-license-key-here';
// Set the API URL
const url = 'https://api.example.com/day';
// Prepare the data to send
const data = new URLSearchParams({
date: date,
currency: currency,
licenseKey: licenseKey
});
// Send POST request and handle the response
fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
},
body: data
})
.then(response => {
if (!response.ok) {
throw new Error('HTTP error! status: ' + response.status);
}
return response.text();
})
.then(data => {
console.log('API Response:', data);
})
.catch(error => {
console.error('Error:', error);
});
پارامترهای ورودی
فیلد | نوع | توضیحات | |
---|---|---|---|
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);
?>
پارامترهای ورودی
فیلد | نوع | اجباری | توضیحات |
---|---|---|---|
licenseKey | رشته | کلید API شما برای احراز هویت و دسترسی به سرویس. | |
start | تاریخ | بله | تاریخ شروع مورد درخواست |
end | تاریخ | بله | تاریخ پایان مورد درخواست |
currency | رشته | بله | طلا/ارز مورد درخواست |
کدهای خطا و توضیحات
در صورتی که درخواست شما با مشکلی مواجه شود، سرور یکی از کدهای خطا را همراه با توضیحات مناسب برمیگرداند. این کدها در قالب یک شیء JSON با ساختار زیر بازگشت داده میشوند:
لیست خطاها:
کد خطا | عنوان خطا | توضیحات دقیق |
---|---|---|
503 | سرویس در دسترس نیست | این خطا نشاندهنده آن است که سرویس در حال حاضر در دسترس نیست و درخواست شما نمیتواند پردازش شود. ممکن است سرویس تحت تعمیرات یا مشکلات شبکه باشد. لطفاً بعد از مدتی دوباره تلاش کنید. |
404 | لینک اشتباه است | این خطا به این معناست که مسیر درخواست شده در سرور موجود نیست. لطفاً آدرس URL را بررسی کرده و از صحت آن اطمینان حاصل کنید. این ممکن است ناشی از اشتباه در تایپ URL یا حذف منابع باشد. |
10 | خطای مربوط به وب سرویس | این خطا نشاندهنده وجود مشکلی در پردازش درخواست توسط وب سرویس است. معمولاً این خطا ناشی از مشکلات داخلی سرور میباشد. در صورت دریافت این خطا، کاربر باید آن را به تیم پشتیبانی گزارش دهد تا بررسی و رفع مشکل صورت گیرد. |
20 | لایسنس معتبر نیست | این خطا نشاندهنده آن است که لایسنس استفاده شده برای درخواست، معتبر نمیباشد. ممکن است لایسنس منقضی شده باشد یا به درستی فعال نشده باشد. برای رفع این مشکل، لازم است که لایسنس معتبر دریافت و وارد شود. |
21 | محدودیت تعداد درخواست به سرویس در هر ساعت | این خطا زمانی رخ میدهد که تعداد درخواستهای مجاز برای استفاده از سرویس در یک ساعت خاص به پایان رسیده باشد. کاربر تا یک ساعت بعد از آخرین درخواست، نمیتواند درخواست جدیدی ارسال کند. برای رفع مشکل، لازم است که کاربر صبر کند و بعد از گذشت یک ساعت دوباره تلاش کند. |
22 | محدودیت تعداد درخواست روزانه | این خطا نشاندهنده آن است که تعداد درخواستهای مجاز برای یک روز به پایان رسیده است. کاربر تا روز بعد نمیتواند درخواست جدیدی ارسال کند. برای رفع این مشکل، کاربر باید صبر کند تا به روز بعد منتقل شود. |
23 | اعتبار ماهانه لایسنس به پایان رسیده | این خطا به این معناست که اعتبار ماهانه لایسنس به پایان رسیده است. برای استفاده از سرویس باید لایسنس جدید خریداری و فعال شود تا امکان ارسال درخواستها فراهم گردد. کاربر باید منتظر شروع ماه بعد شود تا بتواند درخواست جدید ارسال کند. |
30 | تاریخ ارسال شده نامعتبر است | این خطا نشاندهنده آن است که تاریخ وارد شده در درخواست به فرمت صحیح نمیباشد یا خارج از محدوده مجاز است. لطفاً تاریخ ارسال شده را به فرمت صحیح (YYYY-MM-DD) وارد کرده و دوباره درخواست را ارسال کنید. |
ساختار خطاهای بازگشتی از سرور:
{
"err_code": <کد خطا>,
"message": "<توضیحات خطا>"
}