آموزش API قیمت ارز و طلا؛ راهنمای کامل وب‌سرویس نرخ لحظه‌ای برای توسعه‌دهندگان

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

این مقاله صفحهٔ مرجع مجموعه‌ای از آموزش‌های فنی است. هر جا به جزئیات یک زبان یا ابزار رسیدیم، به آموزش اختصاصی همان موضوع لینک داده‌ایم تا این صفحه خوانا بماند. مشخصات رسمی و پلن‌ها هم همیشه در صفحهٔ API قیمت ارز به‌روز است.

وب‌سرویس قیمت ارز دقیقاً چه چیزی به شما می‌دهد؟

API قیمت ارز یک آدرس اینترنتی است که برنامهٔ شما به آن درخواست می‌فرستد و در جواب، نرخ‌ها را در قالبی ماشین‌خوان (JSON) می‌گیرد. تفاوت مهم وب‌سرویس‌ها نه در شکل JSON، بلکه در منشأ عددها است. نرخ EZRate از معاملات واقعی بازار آزاد جمع می‌شود: پیام‌های خرید و فروش کانال‌ها و گروه‌های معاملاتی، صرافی‌ها و بازارهای رمزارز هر دقیقه خوانده می‌شوند، نرخ‌های پرت کنار گذاشته می‌شوند و میانهٔ بقیه منتشر می‌شود. روش کامل در روش‌شناسی نرخ‌ها آمده است.

فهرست کامل نمادها را همیشه از خود API بگیرید (GET /assets) و در کد ثابت ننویسید؛ دارایی‌های جدید بدون تغییر کد شما اضافه می‌شوند.

قدم اول: ساخت کلید API

1. در سایت EZRate ثبت‌نام کنید و ایمیل خود را تأیید کنید.
2. در پنل کاربری به بخش «کلیدهای API» بروید و «کلید جدید» بزنید. برای هر پروژه یک کلید جدا بسازید تا اگر یکی لو رفت، فقط همان را باطل کنید.
3. اگر کلید فقط از سرور شما استفاده می‌شود، محدودیت IP را روی آدرس سرور بگذارید. این تنظیم ساده جلوی سوءاستفاده از کلید دزدیده‌شده را می‌گیرد.
4. کلید را در متغیر محیطی (مثلاً EZRATE_KEY) ذخیره کنید، نه داخل کد و نه داخل مخزن گیت.

اولین درخواست: قیمت دلار، طلا، سکه و تتر

ساده‌ترین راه آزمایش، دستور curl در ترمینال است. کلید خود را جایگزین کنید:

curl -H "X-API-Key: $EZRATE_KEY" \
  "https://api.ezrate.me/v1/rates?symbols=usd,g18,emami,usdt&lang=fa"

پاسخ چیزی شبیه این است (عددها نمونه‌اند؛ مقدار واقعی را در پاسخ خودتان می‌بینید):

{
  "data": [
    { "symbol": "usd", "code": "USD", "name": "دلار آمریکا", "category": "fiat",
      "market": "tehran", "buy": 0, "sell": 0, "change_pct": 0.12,
      "sources": 13, "low_sources": false, "updated_at": "…", "quote": "IRT" },
    { "symbol": "g18", "code": "G18", "name": "طلای ۱۸ عیار", "category": "gold", "…": "…" }
  ],
  "meta": { "as_of": "…", "freshness_sec": 60, "quote": "IRT" }
}

معنی فیلدهای مهم

مسیرهای اصلی API

جزئیات ساختار پاسخ هر مسیر و همهٔ کدهای خطا در مرجع JSON و مسیرهای API (انگلیسی) آمده است.

تبدیل ارز و قیمت بر حسب دلار یا تتر

پارامتر quote واحد همهٔ قیمت‌های پاسخ را تعیین می‌کند: IRT (تومان)، IRR (ریال) یا نماد هر دارایی دیگری که تمایل دارید بر حسب آن قیمت ها را دریافت کنید. مثلاً quote=USDT قیمت همهٔ رمزارزها را بر حسب تتر می‌دهد و quote=usd قیمت طلا را به دلار بازار آزاد. برای تبدیل یک مبلغ مشخص از convert استفاده کنید:

# ۱۰۰ دلار چند یورو است؟ (side: buy | sell | mid)
curl -H "X-API-Key: $EZRATE_KEY" \
  "https://api.ezrate.me/v1/convert?from=usd&to=eur&amount=100&side=mid"

در فروشگاه‌ها معمولاً side=sell منطقی‌تر است، چون شما کالا را با ارزی که باید از بازار بخرید قیمت می‌گذارید. در گزارش‌های تحلیلی mid (میانگین خرید و فروش) عدد منصفانه‌تری است.

تاریخچه و نمودار

مسیر history کندل OHLC (باز، بیشترین، کمترین، بسته) برمی‌گرداند. با interval=1d نمودار روزانه و با 1h نمودار ساعتی بسازید. عمق تاریخچهٔ در دسترس به پلن شما بستگی دارد. برای بک‌تست، گزارش‌گیری و تحلیل، آموزش دیتای تاریخی قیمت دلار و طلا را ببینید.

curl -H "X-API-Key: $EZRATE_KEY" \
  "https://api.ezrate.me/v1/history/usd?interval=1d&from=2026-09-01&to=2026-10-01"

معماری درست: هرگز از مرورگر کاربر مستقیم API را صدا نزنید

رایج‌ترین اشتباه این است که برنامه‌نویس کلید را داخل جاوااسکریپت صفحه می‌گذارد. هر بازدیدکننده‌ای می‌تواند با کلید «View Source» آن را بردارد و سهمیهٔ شما را تمام کند. الگوی درست این است:

1. سرور شما هر چند ده ثانیه یک‌بار نرخ‌ها را از EZRate می‌گیرد.
2. پاسخ را در حافظه، فایل یا Redis نگه می‌دارد.
3. صفحه‌های سایت، اپ یا ربات عدد را از سرور خود شما می‌خوانند.

با این الگو، تعداد درخواست به API ثابت می‌ماند، چه سایت شما روزی صد بازدید داشته باشد چه صد هزار. آموزش عملی آن را در کش کردن API قیمت ارز با Redis و نکات امنیتی را در امنیت API Key در فرانت‌اند بخوانید.

مدیریت خطا و سهمیه

یک قانون طلایی: وقتی API در دسترس نیست، صفحهٔ شما نباید خالی شود. آخرین عدد معتبر را با برچسب زمان نشان دهید. الگوهای کامل در مدیریت خطا و Rate Limit در APIهای مالی آمده است.

آموزش‌ها بر اساس زبان و ابزار

این مجموعه برای هر محیط یک آموزش جدا دارد. هر کدام با همین مفاهیم شروع می‌کند و کد آمادهٔ اجرا می‌دهد:

سایر موضوعات این مجموعه: اسکرپ سایت قیمت یا API، WebSocket یا REST، نرخ تتر برای صرافی‌های رمزارز، نرخ درهم، لیر و یورو، محاسبهٔ حباب سکه با API و خطرات وب‌سرویس‌های غیررسمی.

چک‌لیست قبل از انتشار پروژه

• کلید فقط سمت سرور است و در مخزن کد ذخیره نشده است.
• پاسخ‌ها کش می‌شوند و فاصلهٔ درخواست‌ها از freshness_sec پلن کمتر نیست.
• واحد (تومان یا ریال) در همهٔ صفحه‌ها کنار عدد نوشته شده است.
• زمان آخرین به‌روزرسانی کنار نرخ نمایش داده می‌شود.
• خطاهای 401، 403 و 429 جدا مدیریت شده‌اند و صفحه در قطعی خالی نمی‌شود.
• منبع نرخ (EZRate) با لینک ذکر شده است؛ شرط استفاده در شرایط API آمده است.

API قیمت ارز به درد چه کسب‌وکارهایی می‌خورد؟

هر جا عددی به نرخ ارز، طلا یا تتر وابسته است و هنوز کسی آن را دستی وارد می‌کند، جای یک اتصال API خالی است. رایج‌ترین سناریوهایی که در تیم‌های ایرانی دیده‌ایم:

نرخ خرید، فروش یا میانه؛ کدام را استفاده کنیم؟

هر نرخ در API دو عدد دارد: buy قیمتی است که بازار از شما می‌خرد و sell قیمتی است که به شما می‌فروشد. فاصلهٔ این دو (اسپرد) در روزهای آرام کم و در روزهای پرنوسان بیشتر است. انتخاب درست به نقش شما در معامله بستگی دارد:

• قیمت‌گذاری کالا یا خدمت: sell، چون برای تأمین دوبارهٔ ارز باید آن را از بازار بخرید.
• ارزش‌گذاری دارایی‌ای که دارید (مثلاً موجودی ارزی شرکت): buy، چون اگر بفروشید همین را می‌گیرید.
• گزارش، نمودار و تحلیل: میانهٔ دو عدد (side=mid در مسیر convert)، که عدد منصفانه‌تری است.

خطای رایج این است که در یک سیستم جایی buy و جای دیگر sell استفاده شود و گزارش‌ها با هم نخوانند. این تصمیم را یک‌بار بگیرید و در مستندات داخلی تیم بنویسید.

قیمت در بازارهای مختلف: تهران، هرات، سلیمانیه، دبی و استانبول

پیش‌فرض همهٔ نرخ‌ها بازار آزاد تهران است. اما دلار در بازارهای مرزی و منطقه‌ای هم معامله می‌شود و گاهی جهت بازار تهران را زودتر نشان می‌دهد. مسیر /rates/usd قیمت دلار را در همهٔ این بازارها کنار هم برمی‌گرداند و با پارامتر market می‌توانید فقط یک بازار را بخواهید. اگر با این بازارها آشنا نیستید، صفحه‌های دلار هرات، دلار سلیمانیه، دلار دبی و دلار استانبول را ببینید.

دقت داده: «تعداد منبع» را جدی بگیرید

برخلاف بسیاری از وب‌سرویس‌ها که فقط یک عدد می‌دهند، هر نرخ EZRate می‌گوید از چند منبع ساخته شده است. ساعت ۱۱ صبح یک روز کاری ممکن است ده‌ها منبع پشت نرخ دلار باشد، اما ساعت ۳ بامداد جمعه شاید چند منبع. وقتی low_sources برابر true است، نرخ قبلی حفظ شده و برچسب «کم‌منبع» دارد. در رابط کاربری خود این وضعیت را با یک نشانهٔ کوچک نشان دهید؛ کاربر حرفه‌ای قدرش را می‌داند.

اینکه چرا قیمت دلار در سایت‌ها و کانال‌های مختلف فرق دارد و EZRate چطور نرخ‌های پرت را کنار می‌گذارد، در علت تفاوت قیمت دلار در سایت‌ها و حذف داده‌های پرت در قیمت‌گذاری توضیح داده شده است.

زبان پاسخ و نام دارایی‌ها

با پارامتر lang=fa یا lang=en نام دارایی‌ها در پاسخ به همان زبان برمی‌گردد. در کد خود همیشه با symbol کار کنید و name را فقط برای نمایش به کاربر بگذارید؛ نام‌ها ممکن است برای خوانایی بهتر اصلاح شوند اما نماد ثابت می‌ماند.

شرایط استفاده و ذکر منبع

داده‌ها برای نمایش در محصولات شما مجازند، به شرط رعایت شرایط استفادهٔ API. نمایش منبع («نرخ‌ها: EZRate») با لینک، هم شرط استفاده است و هم به اعتماد کاربر کمک می‌کند. انتشار مجدد خود داده به‌صورت یک وب‌سرویس دیگر یا فروش آن مجاز نیست.