تحويل العملات في JavaScript وNode.js

أسرع طريق إلى أسعار الصرف في JavaScript هو طلب GET إلى /v1/latest/USD عبر fetch. الاستجابة JSON بسيط بأسعار 31 عملة وحقلي حداثة، source وmarket_session. استدعاؤك الأول لا يحتاج مفتاح API.

استدعاؤك الأول، دون مفتاح

في Node 18 أو أي متصفح حديث لديك fetch جاهزة. await واحدة تكفي لقراءة سعر اليورو:

const response = await fetch("https://api.exchangerate.dev/v1/latest/USD?symbols=EUR,GBP", {
  signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);
const data = await response.json();
console.log(data.rates.EUR);
console.log(data.sources.EUR, data.effective_at.EUR);
console.log(data.market_session);

الاستدعاءات المجهولة محدودة لكل عنوان IP، فانتقل إلى مفتاح مجاني قبل أن تتجاوز مرحلة التجربة السريعة.

أضف مفتاحًا ومعالجة للأخطاء

مرّر مفتاحك كرمز bearer في ترويسة Authorization. افحص res.ok وارمِ استثناء عند حالة سيئة كي تظهر الأخطاء مبكرًا:

// Node.js server only. Never put an account key in browser code.
const KEY = process.env.EXCHANGERATE_API_KEY;
if (!KEY) throw new Error("Set EXCHANGERATE_API_KEY on your server");

async function getLatest(base = "USD") {
  const response = await fetch(`https://api.exchangerate.dev/v1/latest/${encodeURIComponent(base)}`, {
    headers: { Authorization: `Bearer ${KEY}` },
    redirect: "error",
    signal: AbortSignal.timeout(10_000),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);
  return response.json();
}

const data = await getLatest("USD");
console.log(data.rates.GBP, data.effective_at.GBP);

ترويسة X-API-Key: exr_live_... مقبولة أيضًا، للمنصات التي لا تستطيع ضبط ترويسة Authorization (بعض بيئات serverless وZapier وأدوات no-code المماثلة).

حوّل مبلغًا

للتحويل المباشر استدعِ /v1/convert/{from}/{to}/{amount}. تعطيك الاستجابة السعر والمبلغ المحوّل في رحلة واحدة:

// Node.js server only.
const KEY = process.env.EXCHANGERATE_API_KEY;
if (!KEY) throw new Error("Set EXCHANGERATE_API_KEY on your server");
const response = await fetch("https://api.exchangerate.dev/v1/convert/USD/EUR/100", {
  headers: { Authorization: `Bearer ${KEY}` },
  redirect: "error",
  signal: AbortSignal.timeout(10_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}; Retry-After: ${response.headers.get("Retry-After")}`);
const data = await response.json();
console.log(data.rate, data.converted);

يعيد مسار التحويل حقلي source وmarket_session نفسيهما اللذين يعيدهما مسار latest، فتستطيع أن تعرض للمستخدمين فئة السعر وهل أسبوع التداول بين البنوك مفتوح.

افهم source وmarket_session

للعملة المعروضة، اقرأ sources[currency] لمعرفة نوع المصدر وeffective_at[currency] لمعرفة وقت الرصد. يلخص source البيانات الأقل حداثة في الاستجابة كلها. يصف market_session جلسة السوق، بينما يشير timestamp إلى وقت إنشاء الاستجابة لا إلى وقت رصد السعر.

يخبرك حقل data_updated_at بآخر مرة كُتب فيها السعر الأساسي. ويسجّل timestamp وقت بناء الاستجابة. معًا يتيحان لك تقرير كيفية التخزين المؤقت للقيمة وعرضها.

حدود الخطة المجانية

تُعاد الحصة الشهرية عند الساعة 00:00 UTC في اليوم الأول من كل شهر. عند تلقي 429، انتظر المدة المحددة في Retry-After قبل إعادة المحاولة.

• 10,000 استدعاء شهريًا
• 12 طلبًا في الدقيقة
• دون بطاقة ائتمان
• يغطي /v1/latest و/v1/convert و/v1/range و/v1/{date}/{base}