وب سرویس نرخ درهم و لیر و یورو؛ راهنمای بازرگانی، گردشگری و دانشجویی

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

این آموزش بخشی از راهنمای کامل API قیمت ارز و طلا است.

ارزهای پرکاربرد و نمادهایشان

فهرست کامل ارزها را با GET /assets?category=fiat بگیرید. ارزهای کم‌حجم‌تر (مثل درام ارمنستان یا منات آذربایجان) هم نرخ دارند اما تعداد منابعشان کمتر است؛ همیشه فیلد sources را کنار عدد ببینید.

دریافت نرخ همهٔ ارزهای کاری در یک درخواست

import os, requests

API, KEY = "https://api.ezrate.me/v1", os.environ["EZRATE_KEY"]
r = requests.get(f"{API}/rates", params={"symbols": "aed,eur,try,iqd,cny", "lang": "fa"},
                 headers={"X-API-Key": KEY}, timeout=10)
r.raise_for_status()
for x in r.json()["data"]:
    print(f"{x['name']:<12} خرید {x['buy']:>10,}  فروش {x['sell']:>10,}  ({x['sources']} منبع)")

دینار عراق به‌دلیل ارزش پایین واحد، معمولاً به ازای هر هزار دینار معامله می‌شود. واحد هر دارایی (unit) را از GET /assets بخوانید و در نمایش رعایت کنید تا عدد اشتباه برداشت نشود.

پیش‌فاکتور با نرخ روز و اعتبار زمانی

آژانسی که تور استانبول را به یورو یا لیر خریده و به تومان می‌فروشد، با یک مشکل همیشگی روبه‌روست: پیش‌فاکتوری که امروز صادر شده، فردا با نرخ جدید زیان‌ده است. راه حل استاندارد، صدور پیش‌فاکتور با نرخ لحظه‌ای و اعتبار زمانی محدود است:

from datetime import datetime, timedelta, timezone

def proforma(amount, currency, margin=0.015, valid_hours=24):
    c = requests.get(f"{API}/convert", params={"from": currency, "to": "irt", "amount": amount, "side": "sell"},
                     headers={"X-API-Key": KEY}, timeout=10).json()["data"]
    total = round(c["result"] * (1 + margin), -3)          # گرد به هزار تومان
    return {
        "amount": amount, "currency": currency.upper(), "rate": c["rate"],
        "total_toman": int(total),
        "rate_time": c["as_of"],
        "valid_until": (datetime.now(timezone.utc) + timedelta(hours=valid_hours)).isoformat(),
    }

print(proforma(2500, "eur"))

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

نرخ متقاطع: یک یورو چند درهم است؟

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

curl -H "X-API-Key: $EZRATE_KEY" "https://api.ezrate.me/v1/cross?base=eur&symbols=aed,try,usd"

نکته: نرخ درهم به دلار در بازار جهانی به‌صورت رسمی تقریباً ثابت (حدود ۳٫۶۷۲۵ درهم برای هر دلار) است، اما در بازار آزاد ایران نسبت تومانی این دو ممکن است کمی متفاوت باشد. چرایی آن در رابطهٔ درهم امارات و دلار تهران توضیح داده شده است.

بازار مرجع: تهران یا دبی؟

نرخ پیش‌فرض همهٔ ارزها بازار آزاد تهران است. اما برای دلار، قیمت بازارهای دیگر مثل دلار دبی و دلار استانبول هم در API هست (GET /rates/usd). اگر کسب‌وکار شما حواله را در دبی تسویه می‌کند، ممکن است نرخ آن بازار برایتان مرجع دقیق‌تری باشد. تفاوت انواع نرخ (نقدی، حواله، فردایی) در دلار نقدی، فردایی، حواله و کاغذی آمده است.

اتصال به نرم‌افزار حسابداری و اکسل

بسیاری از این کسب‌وکارها نرخ را در اکسل یا نرم‌افزار حسابداری لازم دارند، نه در کد. برای اکسل و گوگل شیت آموزش قیمت لحظه‌ای طلا و دلار در اکسل و برای نرم‌افزارهای حسابداری تسعیر ارز در حسابداری را ببینید. نسخهٔ انگلیسی مخصوص آژانس‌ها و معامله‌گران مرزی در TRY/IRR and EUR/IRR Live Feeds آمده است.

خطاهای رایج