واجهة API لأسعار الصرف على Stack Overflow: حل مشكلات المطورين

حين يتعطل التكامل، يلصق المطورون الخطأ في Stack Overflow. بالنسبة لواجهة API لأسعار الصرف، تكاد الأسئلة تكون نفسها دائمًا: مفتاح مرفوض، جدار حد طلبات، خطأ CORS، أو سعر يبدو راكدًا في عطلة الأسبوع. إليك حلولًا مباشرة، باستخدام exchangerate.dev كمثال عملي. كل مقتطف استدعاء حقيقي ضد https://api.exchangerate.dev.

الـ base URL هو https://api.exchangerate.dev. يعمل أول استدعاء دون تسجيل (بحد أقصى لكل IP)، فيمكنك إعادة إنتاج أي من هذه الحالات قبل التسجيل بمفتاح مجاني.

401 Unauthorized — المفتاح مرفوض

يوضع المفتاح في ترويسة Authorization كرمز bearer، ويجب أن تكون كلمة Bearer متبوعة بمسافة موجودة. تبدأ المفاتيح بالبادئة exr_live_.

curl https://api.exchangerate.dev/v1/latest/USD \
  -H "Authorization: Bearer exr_live_YOUR_KEY"

الأسباب المعتادة لخطأ 401: غياب بادئة Bearer ، أو التقط المفتاح سطرًا جديدًا أو علامة اقتباس شاردة من النسخ واللصق، أو أن متغير البيئة الحامل له غير مُحمَّل. المنصات التي لا يمكنها ضبط Authorization يمكنها إرسال المفتاح كترويسة X-API-Key بدلاً من ذلك.

429 Too Many Requests — التعامل مع حدود الطلبات

تحمل الاستجابات الناجحة المحتسبة X-RateLimit-Remaining. ويعيد 429 Retry-After، فانتظر المدة المحددة قبل المحاولة. يوضح X-RateLimit-Scope هل استنفدت حد الدقيقة، أو حد الساعة المجهول، أو الحصة الشهرية. الخطة المجانية 12 طلبًا في الدقيقة، وBasic 120، وPro 500. افحص حصة الحساب وموعد إعادة تعيينها الشهري عبر GET /v1/account.

خطأ CORS — استدعاء الـ API من المتصفح

تسمح CORS بالقراءات المجهولة وبترويستي Authorization وX-API-Key. لكن ذلك لا يجعل طلب المتصفح المزود بمفتاح سريًا: يستطيع أي شخص يفتح أدوات المطورين نسخ exr_live_.... استخدم الاستدعاء المجهول للعرض العام؛ ولاستخدام حصة الحساب، مرر الطلب عبر خادمك الخلفي واحتفظ بالمفتاح على الخادم.

// the key never reaches the browser
const r = await fetch("https://api.exchangerate.dev/v1/latest/USD", {
  headers: { Authorization: `Bearer ${process.env.EXCHANGERATE_API_KEY}` },
});
const data = await r.json();

كيف أخزّن أسعار الصرف مؤقتًا بأمان؟

خزّن الرصد الناجح كاملًا: السعر وsource وmarket_session وdata_updated_at. ابدأ للأزواج النشطة بتخزين 60 ثانية على الخادم. يقلل ذلك الطلبات المكررة، لكنه لا يجعل السعر المرجعي اليومي أحدث.

• اجمع العملات في طلب symbols واحد بدل استدعاء HTTP مستقل لكل زوج.
• خزّن استجابات 2xx الناجحة فقط. لا تحفظ 401 أو 429 أو خطأ المصدر كسعر.
• عند 429 استخدم Retry-After وX-RateLimit-Scope، ولا تفترض مدة انتظار ثابتة.
• احتفظ بمفاتيح الحساب في إعدادات الخادم، لا في cache أو حزمة متصفح عامة.

السعر يبدو راكدًا أو لا يتغير في عطلة الأسبوع

هذا متوقع، والاستجابة تخبرك بالسبب. العملات المتداولة بنشاط تُحدَّث مباشرة (~60 ثانية في أيام التداول)؛ التغطية الحالية تأتي من الـ API لا من رقم تسويقي ثابت، والباقي يستخدم أسعارًا مرجعية يومية من ECB وFRED. في عطلة الأسبوع يكون السوق بين البنوك مغلقًا، فتتوقف التغذية المباشرة وتحمل الأسعار المرجعية آخر قيمة منشورة. حقلان يوضحان ذلك صراحة:

كيف أحوّل مبلغًا، لا أن أقرأ سعرًا فقط؟

استخدم /v1/convert/{from}/{to}/{amount}. تعيد السعر والمبلغ المحوَّل معًا، فلا تحتاج للضرب يدويًا:

curl https://api.exchangerate.dev/v1/convert/USD/EUR/100 \
  -H "Authorization: Bearer exr_live_YOUR_KEY"

كيف أحصل على بيانات تاريخية أو سلسلة زمنية؟

ليوم واحد سابق، ضع التاريخ في المسار: GET /v1/{YYYY-MM-DD}/{base}، يمتد حتى 1999-01-04. لسلسلة كاملة عبر مدى زمني في استدعاء واحد، استخدم GET /v1/range مع start_date وend_date؛ يستخدم ترقيمًا بالمؤشر (keyset)، فاتبع المؤشر بدل طلب مدى ضخم دفعة واحدة.

أُرحّل من واجهة API أخرى لأسعار الصرف وأواجه أخطاء؟

تتبع معاملات الطلب الاصطلاحات الشائعة بين واجهات API لأسعار الصرف (عملة أساس مع مرشّح symbols)، فمعظم عمليات الترحيل مجرد تبديل الـ base URL دون إعادة كتابة الكود. حيث تختلف الاستجابات، تضيف هذه الـ API حقولًا (source وmarket_session وnotice) بدل حذفها — راجع الكود الذي يقرأ الاستجابة تحسبًا لافتراضه مجموعة ثابتة من المفاتيح.

أقصر استدعاء يعمل

دون مفتاح، دون تبعيات:

curl https://api.exchangerate.dev/v1/latest/USD

تحصل على الأسعار إضافة إلى source وmarket_session فتعرف مدى حداثة كل منها. مفتاح مجاني يرفع الحد إلى 10,000 استدعاء شهريًا ويستغرق دقيقة.