أسعار صرف حية في Google Sheets

للحصول على أسعار صرف حية في Google Sheets، الصق دالة Apps Script مخصصة تستدعي /v1/latest/{base} مع مفتاحك في ترويسة Authorization، ثم اكتب =FXRATE("USD","EUR") في أي خلية. المفتاح المجاني يغطي 10,000 استدعاء شهريًا دون بطاقة. الدالة أدناه تخزّن مؤقتًا لعشر دقائق وتعالج الخطأين اللذين ستصادفهما فعلًا. إنها مدخل العملات الحي لنموذج أو لوحة متابعة تحتفظ بها في Sheets.

احصل على مفتاح API مجاني

سجّل في exchangerate.dev/signup. بعد تأكيد البريد تعرض لوحة التحكم مفتاحًا يبدأ بـexr_live_. انسخه — ستلصقه في Apps Script بعد قليل. الخطة المجانية 10,000 استدعاء شهريًا دون بطاقة.

افتح Apps Script من جدولك

افتح أي جدول في Google Sheets. من القائمة، اضغط الإضافات ← Apps Script. يفتح تبويب جديد فيه دالة function myFunction() {} افتراضية. احذف محتواها — ستستبدله في الخطوة التالية.

الصق دالة FXRATE

استبدل محتوى المحرر بهذه الدالة. تستدعي exchangerate.dev، وتخزّن كل زوج مؤقتًا لعشر دقائق عبر CacheService، وتعيد علامة مقروءة للخطأين الممكنين (401 و429).

// google-sheets: Apps Script Code.gs
// Replace API_KEY with your exchangerate.dev key from /signup

const API_KEY = 'exr_live_replace_with_your_key_here';
const CACHE_TTL = 600; // seconds — FX moves slower than equities; 10 min is plenty

function FXRATE(from, to) {
  from = (from || 'USD').toString().toUpperCase();
  to = (to || 'EUR').toString().toUpperCase();

  const cacheKey = `fx_${from}_${to}`;
  const cache = CacheService.getScriptCache();
  const cached = cache.get(cacheKey);
  if (cached) return Number(cached);

  const url = `https://api.exchangerate.dev/v1/latest/${from}?symbols=${to}`;
  const resp = UrlFetchApp.fetch(url, {
    headers: { Authorization: `Bearer ${API_KEY}` },
    muteHttpExceptions: true,
  });

  const code = resp.getResponseCode();
  if (code === 401) return '#AUTH_ERROR';
  if (code === 429) return '#RATE_LIMIT';
  if (code !== 200) return '#ERROR';

  const data = JSON.parse(resp.getContentText());
  const rate = data.rates && data.rates[to];
  if (rate == null) return '#NO_PAIR'; // unknown currency code
  cache.put(cacheKey, String(rate), CACHE_TTL);
  return Number(rate); // coerce so cells sum and sort
}

استخدم =FXRATE() في أي خلية

ارجع إلى الجدول واكتب =FXRATE("USD","EUR") في خلية فارغة. بعد ثانية تقريبًا تعرض الخلية السعر الحالي. الدالة نفسها تعمل مع أي زوج مدعوم — بدّل رمزي العملتين:

// Euro per US dollar
=FXRATE("USD", "EUR")        // 0.9245

// Japanese yen per US dollar
=FXRATE("USD", "JPY")        // 157.32

// British pound per euro
=FXRATE("EUR", "GBP")        // 0.8531

// Indonesian rupiah per US dollar
=FXRATE("USD", "IDR")        // 16285.0

خلف الكواليس يعيد كل استدعاء عملة الأساس، والزوج الذي رشّحت عليه، وحقلي حداثة — source وmarket_session — فتعرف دائمًا مدى حداثة الرقم:

{
  "result": "success",
  "base": "USD",
  "source": "live",
  "market_session": "open",
  "timestamp": "2026-06-29T09:14:02Z",
  "data_updated_at": "2026-06-29T09:14:00Z",
  "rates": { "JPY": 157.32 },
  "sources": { "JPY": "live" },
  "notice": "Indicative rates, not for settlement."
}

التحديث والاستيعاب ضمن الخطة المجانية

لا يعيد Apps Script تشغيل الدوال المخصصة بمؤقت من تلقاء نفسه. للتحديث الدوري، أضف مشغّلًا زمنيًا: من الشريط الأيسر في Apps Script اضغط المشغّلات ← إضافة مشغّل، واختر FXRATE، والمصدر مستند إلى الوقت، ثم مؤقت بالدقائق. التخزين المؤقت لعشر دقائق مع الحصة السخية يبقي المصنّف المزدحم في أمان:

• 10,000 استدعاء شهريًا، 12 طلبًا في الدقيقة، دون بطاقة
• يعيد CacheService السعر المخزّن لمدة 10 دقائق، فلا تكلّف التعديلات المتكررة شيئًا
• ارفع CACHE_TTL إذا لامس جدول بأزواج كثيرة حدّ الدقيقة
• يغطي /v1/latest و/v1/convert و/v1/range و/v1/{date}/{base}