واجهة 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. اقرأها وخفّف الوتيرة قبل أن تصل إلى الصفر بدل الاستطلاع عشوائيًا. الخطة المجانية 12 طلبًا في الدقيقة، وBasic 120، وPro 500. يمكنك التحقق من حصتك المتبقية وموعد إعادة التعيين الشهري في أي وقت عبر GET /v1/account. السعر المرجعي لا يتغير كل ثانية، فتخزين مؤقت قصير من جهة العميل يبقيك عادة ضمن الحد بارتياح.

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

لا تستدعِ الـ API مباشرة من جافاسكربت الواجهة الأمامية بمفتاحك: فهذا يعرّض exr_live_... لأي شخص يفتح أدوات المطورين، وسيحظره المتصفح بسبب CORS. مرِّر الاستدعاء عبر خادمك الخلفي، واحتفظ بالمفتاح على الخادم، واجعل المتصفح يستدعي نقطة نهايتك.

// 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();

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

هذا متوقع، والاستجابة تخبرك بالسبب. العملات المتداولة بنشاط تُحدَّث مباشرة (~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)، فاتبع المؤشر بدل طلب مدى ضخم دفعة واحدة.

أُرحّل من Frankfurter وأواجه أخطاء؟

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

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

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

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

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