Frankfurter واجهة API لأسعار الصرف والعملات
Frankfurter واجهة API مجانية لأسعار صرف 219 عملة و39 من الأصول الأخرى، مصدرها 112 من البنوك المركزية والمصادر الرسمية. تتحدّث الأسعار على مدار اليوم، ويعود السجل اليومي إلى عام 1948.
الواجهة العامة متاحة على api.frankfurter.dev، ولا تحتاج إلى مفتاح API. المشروع مفتوح المصدر، لذا يمكنك أيضًا استضافته بنفسك والتحكم فيه بالكامل.
هذه أسعار مرجعية، وليست أسعار سوق لحظية. ينشرها كل مصدر مرة واحدة أو بضع مرات في اليوم.
تعمل مع وكيل ذكاء اصطناعي؟ وجّهه إلى llms.txt، أو أضف خادم MCP.
الأسعار
احصل على أحدث أسعار الصرف.
curl https://api.frankfurter.dev/v2/rates
غيّر العملة الأساسية باستخدام base.
curl https://api.frankfurter.dev/v2/rates?base=usd
حدّد العملات المستهدفة باستخدام quotes.
curl https://api.frankfurter.dev/v2/rates?quotes=usd,gbp
الأسعار التاريخية
اطّلع على الأسعار في تاريخ محدد.
curl https://api.frankfurter.dev/v2/rates?date=1999-01-04
السلاسل الزمنية
احصل على الأسعار خلال فترة باستخدام from وto.
curl https://api.frankfurter.dev/v2/rates?from=2026-01-01"es=usd
نصيحة: تقليل عدد العملات يُبقي الاستجابات صغيرة. وللنطاقات الزمنية الكبيرة، اطلب NDJSON لتتلقى النتائج سطرًا بسطر.
التجميع
قلّل كثافة السلسلة الزمنية باستخدام group. القيم المدعومة: week وmonth.
curl https://api.frankfurter.dev/v2/rates?from=2026-01-01&group=month
التصفية حسب المصدر
اقصر النتائج على مصادر محددة باستخدام providers.
curl https://api.frankfurter.dev/v2/rates?providers=ecb
تُدمج الأسعار افتراضيًا من جميع المصادر. استخدم providers للحصول على أسعار مصدر محدد، أو استخدم
مسارات المصادر للاستعلام من المصدر
مباشرة.
تنشر بعض المصادر أكثر من مجموعة بيانات، مثل جداول NBP اليومية والأسبوعية. مفتاح المصدر يختار مجموعات بياناته الافتراضية، ومفتاح مجموعة البيانات يختار مجموعة واحدة فقط.
curl https://api.frankfurter.dev/v2/rates?providers=nbp.b&base=pln"es=ars,ngn
نسبة الأسعار إلى مصادرها
أضف expand=providers لمعرفة المصادر التي أسهمت في كل سعر
مدمج.
curl https://api.frankfurter.dev/v2/rates?expand=providers
يحصل كل صف على مصفوفة providers بمفاتيح المصادر المساهمة.
أما صفوف العملات المربوطة فلا تتضمن هذا الحقل، لأن أسعارها تأتي من الربط
وليس من بيانات المصادر.
إخراج CSV
الأسعار متاحة أيضًا بصيغة CSV. أضف .csv إلى المسار أو اضبط
ترويسة Accept على text/csv.
curl https://api.frankfurter.dev/v2/rates.csv
إخراج NDJSON
للاستجابات الكبيرة، اطلب
NDJSON
(JSON مفصول بأسطر جديدة) بضبط ترويسة Accept على
application/x-ndjson. كل سطر كائن JSON مستقل، وهذا مفيد
لبث السلاسل الزمنية الكبيرة دون تخزين الاستجابة كاملة في الذاكرة.
curl https://api.frankfurter.dev/v2/rates?from=2026-01-01
السعر
احصل على سعر زوج عملات واحد. ويمكنك إضافة date أو
providers.
curl https://api.frankfurter.dev/v2/rate/eur/usd
العملات
احصل على العملات المتاحة مع تغطية المصادر لها.
curl https://api.frankfurter.dev/v2/currencies
أدرج العملات القديمة باستخدام scope.
curl https://api.frankfurter.dev/v2/currencies?scope=all
العملة
احصل على تفاصيل عملة واحدة وتغطية المصادر لها.
curl https://api.frankfurter.dev/v2/currency/eur
المصادر
اعرض قائمة المصادر التي تعتمد عليها الواجهة.
curl https://api.frankfurter.dev/v2/providers
احصل على تفاصيل مصدر واحد.
curl https://api.frankfurter.dev/v2/providers/ecb
يعرض كل مصدر مجموعات بياناته، ولكل منها تواريخها وجدول نشرها وعملاتها.
الأسعار حسب المصدر
استعلم عن الأسعار مباشرة من مصدر محدد. يدعم المعاملات نفسها التي يدعمها
/v2/rates و/v2/rate.
curl https://api.frankfurter.dev/v2/providers/ecb/rates
احصل على زوج عملات واحد من ذلك المصدر.
curl https://api.frankfurter.dev/v2/providers/ecb/rate/eur/usd
اجمع ذلك مع date أو نطاقات التواريخ (from وto)
أو التجميع. وتعمل هنا أيضًا صيغ مثل .csv وndjson.
curl https://api.frankfurter.dev/v2/providers/ecb/rates?date=2024-05-15
التحويل
لا توجد نقطة نهاية للتحويل. احصل على السعر وحوّل المبلغ ببضعة أسطر من الكود.
function convert(base, quote, amount) {
const api = "https://api.frankfurter.dev";
return fetch(`${api}/v2/rate/${base}/${quote}`)
.then((r) => r.json())
.then((d) => (amount * d.rate).toFixed(2));
}
convert("eur", "usd", 10).then((result) =>
alert(`10 EUR = ${result} USD`)
);
الأخطاء
تُرجع الواجهة رموز حالة HTTP القياسية مع متن JSON.
{
"status": 422,
"message": "invalid currency: ABC"
}
400- معامل غير صالح أو طلب غير سليم.
404- العملة أو السعر أو المورد غير موجود.
422- الطلب مفهوم لكن تتعذّر معالجته.
الاستضافة الذاتية
يمكنك استضافة الواجهة بنفسك باستخدام Docker. راجع دليل النشر لإعداد بيئة الإنتاج وضبط مفاتيح API.
الأسئلة الشائعة
- لمن صُمّم Frankfurter (ولمن لا يناسب)؟
- يناسب الفوترة في تطبيقات SaaS، والتجارة الإلكترونية، والتقارير الضريبية، وأنظمة ERP والمحاسبة، والأبحاث الأكاديمية على سلاسل تاريخية تعود إلى 1948. لم يُصمَّم للتداول اللحظي، ولا للعملات النادرة ذات التقلبات الحادة خلال اليوم.
- هل الواجهة مجانية للاستخدام التجاري؟
- نعم. الأسعار المدمجة من حسابات Frankfurter الخاصة ومجانية الاستخدام. أما الاستعلامات المباشرة لنقاط نهاية مصادر بعينها فتخضع لـشروط كل مصدر.
- هل يمكنني تخزين الأسعار أو حفظها مؤقتًا في قاعدة بياناتي؟
- نعم. نشجّع على تخزين القيم اليومية محليًا للتخزين المؤقت أو التحليلات التاريخية، لتخفيف حركة المرور على الواجهة.
- هل للواجهة حدود على عدد الطلبات؟
- لا توجد حصص. يُحدّ معدل الطلبات لمنع إساءة الاستخدام، لكن لا توجد سقوف شهرية أو يومية. للاستخدام الكثيف، فكّر في التخزين المؤقت للاستجابات، أو الاستضافة الذاتية، أو الاستعلام من مجموعات البيانات مباشرة.
- هل تدعم الواجهة GraphQL؟
-
لا. واجهة REST بسيطة بما يكفي، وإضافة GraphQL ستزيد التعقيد دون فائدة
تُذكر. كما أنها ستعطّل التخزين المؤقت على الحافة، وهو ما يُبقي الواجهة
سريعة. استخدم معاملات الاستعلام مثل
baseوquotesوfrom/toللحصول على البيانات التي تحتاجها بالضبط. - هل سيتوقف الإصدار v1 من الواجهة؟
- لا. الإصدار v1 مُهمَل لصالح v2، لكنه يبقى متاحًا إلى أجل غير مسمى. راجع توثيق v1. ولبيانات البنك المركزي الأوروبي، استخدم /v2/providers/ecb/rates.
- ما سياسة الخصوصية في الواجهة؟
- لا تجمع الواجهة البيانات الشخصية ولا عناوين IP ولا روابط الطلبات، ولا تسجّلها. تعمل النسخة العامة خلف Cloudflare للتخزين المؤقت والحماية من هجمات DDoS، ولا يوفّر ذلك سوى إحصاءات إجمالية عن حركة المرور.
- هل عليّ الإفصاح عن الواجهة في ملصقات الخصوصية في App Store أو Google Play؟
- لا. لأن الاستعلامات مجهولة الهوية ولا تُحفظ سجلات للطلبات، تندرج الطلبات ضمن فئة Data Not Collected (لا تُجمع بيانات) وفق إرشادات Apple وGoogle Play.
- أين أبلغ عن خطأ أو أطرح سؤالًا؟
- افتح issue للإبلاغ عن خطأ أو طلب ميزة أو اقتراح مصدر جديد. واستخدم Discussions لطرح الأسئلة أو مشاركة مكتبة أو أداة بنيتها باستخدام Frankfurter.
- ما مدى دقة الأسعار؟
- لأغراض الامتثال (الضرائب والمحاسبة)، صفِّ النتائج حسب مصدر محدد للحصول على الأسعار المرجعية الرسمية. وللاستخدام العام، تفي الأسعار المدمجة الافتراضية بالغرض، وإن كانت الخانات العشرية الأخيرة قد تتغير مع وصول بيانات جديدة.
- هل الأسعار أسعار منتصف السوق أم أسعار شراء أم بيع؟
- تُرجع الواجهة أسعار منتصف السوق. وحين ينشر المصدر سعري الشراء والبيع بدلًا من سعر مرجعي، يخزّن Frankfurter السعرين ويحسب نقطة المنتصف بينهما.
- هل جميع أسعار الصرف يومية؟
-
معظمها كذلك. بعض المصادر تقدّم قيمًا أسبوعية أو شهرية أو فصلية، وهذه مستبعدة من الأسعار المدمجة. استعلم عنها مباشرة باستخدام مرشّح
providers. - هل لديكم أسعار المعادن النفيسة أو العملات المشفرة؟
-
نعم. تنشر عدة بنوك مركزية أسعارًا يومية للذهب (
XAU) والفضة (XAG) والبلاتين (XPT) والبلاديوم (XPD) لكل أونصة تروي. أما العملات المشفرة، فنقصر القائمة على العملات التي لها عقود آجلة في CME أو سعر CME CF Reference Rate (مثلBTCوETHوSOLوXRP)، إضافة إلىUSDTوUSDC. قلة من المصادر تغطي العملات المشفرة، لذا تبقى التغطية محدودة. - لماذا تتداخل تواريخ بعض العملات القديمة والجديدة؟
-
تُرجع بعض المصادر تاريخ العملات البديلة إلى فترة العملة القديمة (مثلًا،
تنتهي
TRLفي 2010 بينما تبدأTRYفي 1996). نسجّل بيانات المصادر كما هي، ولا نستبعد التداخلات إلا عند الدمج. - لماذا Frankfurter؟
-
لأن مصدر بياناتنا الأصلي هو