واجهة API مجانية لأسعار الذهب: ماذا تقدّم 100 طلب شهريًا

ما الذي تستطيع واجهة API مجانية لأسعار الذهب تقديمه فعلًا؟

واجهة API المجانية لأسعار الذهب هي أسرع طريقة لإدخال أسعار ذهب حقيقية في نموذج أولي أو موقع هواية أو تقرير داخلي دون أمر شراء. لكن من السهل أيضًا أن تتوقع منها أكثر مما ينبغي. فالخطط المجانية موجودة لتبني تكاملًا وتختبره، ولتشغّل أعباء عمل صغيرة تحتاج إلى سعر مرة واحدة يوميًا. وهي ليست مصممة لتشغيل صفحة دفع يجب أن تتبع السوق دقيقة بدقيقة.

تصف هذه المقالة خطة Free في MetalAPI كما هي، بما في ذلك ما لا تتضمنه. ثم تبيّن كيف تجعل 100 طلب شهريًا تغطي قدرًا مفاجئًا من العمل، وكيف تعرف أن احتياجاتك تجاوزت هذه الخطة. وإذا كنت تقارن بين عدة مزودين، فإن قائمة التحقق قرب نهاية المقالة تنطبق على أي واجهة API مجانية لأسعار المعادن.

ما الذي تتضمنه خطة Free في MetalAPI؟

خطة Free مجانية ولا تتطلب بطاقة ائتمان. وباختصار:

تتطلب بعض الميزات خطة مدفوعة:

• أسعار الذهب حسب العيار من /carat: من خطة Lite فما فوق. وفي خطة Free يمكنك مع ذلك حساب أسعار العيارات بنفسك من سعر عيار 24.
• أسعار الطلب والعرض، مثل XAU-BID وXAU-ASK: من خطة Standard فما فوق.
• تنبيهات الأسعار: بالبريد الإلكتروني من خطة Lite، وعبر خطافات الويب من خطة Advanced.
• البث اللحظي عبر Server-Sent Events: من خطة Pro فما فوق.
• اتفاقية مستوى الخدمة (SLA) لوقت التشغيل: خطتا Business وEnterprise.

يُرجع طلب الواجهة لميزة خارج خطتك الخطأ 106 (plan_restriction) مع upgrade_url، ولا يُحتسب ذلك الطلب. وتعمل خطة Free أيضًا مع خادم MetalAPI MCP، فيستطيع مساعد الذكاء الاصطناعي البحث عن أسعار الذهب ضمن حصتك المجانية، وبالحداثة اليومية نفسها.

كم مرة تُحدَّث واجهة API المجانية لأسعار الذهب؟

أهم سطر في ذلك الجدول هو فترة التحديث. ففي خطة Free تلتقط الواجهة لقطة أسعار واحدة يوميًا عند منتصف الليل بتوقيت UTC، ويُرجع كل طلب إلى /latest حتى منتصف الليل التالي تلك اللقطة نفسها. وتبدو الاستجابة على النحو التالي، بالقيم النموذجية من توثيق MetalAPI:

{
  "success": true,
  "timestamp": 1792713600,
  "date": "2026-10-23",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319446,
    "USDXAU": 3997.89
  },
  "rate_limit": {
    "limit": 100,
    "remaining": 99,
    "reset": 1793491200,
    "used": 1,
    "plan": "Free",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

USDXAU هو سعر أونصة تروي واحدة من الذهب بالدولار، وXAU معكوسه. وtimestamp هو وقت البيانات، وهو هنا 00:00 UTC في 23 أكتوبر 2026، ويبيّن الجزء rate_limit ما تبقى من حصة الشهر.

ويترتب على ذلك أمران. أولًا، استدعاء /latest أكثر من مرة يوميًا في خطة Free يستهلك الحصة دون أن يُرجع سعرًا أحدث أبدًا. ثانيًا، تناسب خطة Free المهام التي يكون فيها السعر اليومي هو السعر المناسب:

• التقييم اليومي للحيازات أو المخزون أو المحفظة.
• تقارير نهاية اليوم والنشرات البريدية ولوحات المعلومات الداخلية.
• المحاسبة والفواتير التي تحتاج إلى سعر الذهب في يوم معيّن.
• النماذج الأولية ومشاريع الطلاب وتعلّم الواجهة قبل اختيار خطة.

ولا تناسب متجرًا يعيد تسعير منتجات الذهب خلال اليوم، ولا شاشة تداول، ولا أي شيء يَعِد العملاء بسعر لحظي.

إلى أي مدى تكفي 100 طلب شهريًا؟

كل استدعاء ناجح لنقطة نهاية بيانات يُحتسب طلبًا واحدًا، مهما كان عدد الرموز التي يُرجعها. وهذه القاعدة هي ما يجعل الحصة الصغيرة عملية. وإليك ميزانية شهرية واقعية لموقع صغير:

قارن ذلك بأنماط لا تناسب الخطة:

• التحديث كل ساعة: نحو 744 طلبًا شهريًا، لسعر يتغير مرة واحدة يوميًا.
• طلب واحد لكل معدن يوميًا للذهب والفضة والبلاتين والبلاديوم: نحو 124 طلبًا، بينما يكلّف طلب مجمّع واحد يوميًا 31 طلبًا.
• استدعاء الواجهة من المتصفح عند كل مشاهدة للصفحة: مئة زيارة تستنفد حصة الشهر.

سبع طرق لتمديد الحصة المجانية

1. اطلب كل الرموز في استدعاء واحد. يكلّف currencies=XAU,XAG,XPT,XPD,EUR,GBP طلبًا واحدًا. وحذف currencies يُرجع كل الرموز، بطلب واحد أيضًا.
2. خزّن مؤقتًا حتى منتصف الليل التالي بتوقيت UTC. ففي خطة Free لا يوجد ما هو أحدث لتجلبه قبل ذلك. احتفظ بآخر استجابة صالحة وقدّمها إذا فشل أحد الاستدعاءات.
3. حوّل محليًا. الغرام والكيلوغرام مضاعفات دقيقة لأونصة التروي (1 أونصة تروي = 31.1034768 غرامًا)، وأسعار الصرف التقاطعية تأتي من لقطة واحدة: سعر الذهب باليورو هو USDXAU ÷ USDEUR. فطلب واحد بالدولار لكل أونصة يمكنه تغذية كل وحدة وعملة تعرضها.
4. خزّن السجل مرة واحدة. أسعار الإغلاق السابقة لا تتغير أبدًا. اجلب النطاق مرة واحدة، واحفظه في قاعدة بيانات أو ملف، ولا تطلب إلا الأيام الجديدة.
5. تحقّق قبل الإرسال. أخطاء التحقق (الرموز من 201 إلى 210) والخطأ 300 (لا توجد نتائج) تُحتسب طلبات. تحقّق من التواريخ والرموز أولًا؛ فنقطة النهاية /symbols تسرد كل رمز صالح ولا تُحتسب من الحصة أبدًا.
6. أبقِ الاستدعاءات على الخادم. المفتاح في شيفرة المتصفح مرئي للجميع ويستهلك طلبًا لكل زائر. اجلب البيانات على الخادم وقدّم النتيجة المخزنة مؤقتًا، أو ضمّن ودجة لا تُحتسب مشاهدات صفحاتها من حصتك.
7. راقب العدّاد. تحمل كل استجابة الجزء rate_limit وترويسات X-RateLimit-*، وتُرجع /usage الأرقام نفسها دون أن تُحتسب. كما لا تُحتسب حالات الرفض بسبب حدود المعدل (104) أو قيود الخطة (106) أو المصادر (107) أو أخطاء الخادم، لذا فإن إعادة محاولتها لا تكلّف شيئًا.

وعند جمع ذلك كله، يصبح جوهر التكامل مع خطة Free مهمة مجدولة واحدة. يعمل سكربت Node.js هذا مرة يوميًا بعد منتصف الليل بتوقيت UTC بقليل، ويرسل طلبًا واحدًا، ويكتب أسعار الذهب والفضة والبلاتين والبلاديوم لكل أونصة ولكل غرام بثلاث عملات في ملف JSON تقرؤه صفحاتك:

// Run once a day after 00:00 UTC, e.g. with cron: 5 0 * * *  (server clock on UTC)
import { writeFile } from "node:fs/promises";

const GRAMS_PER_TROY_OZ = 31.1034768;
const METALS = ["XAU", "XAG", "XPT", "XPD"];
const CURRENCIES = ["EUR", "GBP"];

const params = new URLSearchParams({ base: "USD", currencies: [...METALS, ...CURRENCIES].join(",") });
const res = await fetch(`https://metalapi.com/api/v1/latest?${params}`, {
  headers: { "X-API-Key": process.env.METALAPI_KEY },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();
if (!data.success) {
  // Leave yesterday's file in place, so pages keep showing the last good prices.
  throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
}

const prices = {};
for (const metal of METALS) {
  const usdPerOz = data.rates[`USD${metal}`];
  prices[metal] = {};
  for (const cur of ["USD", ...CURRENCIES]) {
    const perOz = cur === "USD" ? usdPerOz : usdPerOz / data.rates[`USD${cur}`];
    prices[metal][cur] = { perOz, perGram: perOz / GRAMS_PER_TROY_OZ };
  }
}

await writeFile("prices.json", JSON.stringify({ asOf: data.timestamp, prices }, null, 2));
console.log(`Saved. ${data.rate_limit.remaining} requests left this month.`);

بتشغيل واحد يوميًا، تستهلك المهمة من 28 إلى 31 طلبًا شهريًا وتترك الباقي للسجل والاختبار. وعلى المنصات عديمة الخوادم (serverless)، اكتب النتيجة في مخزن مفتاح-قيمة أو في ذاكرة التخزين المؤقت للبيانات في إطار عملك بدلًا من ملف.

أما السجل، فإن حد النطاق البالغ 30 يومًا يعني طلبًا واحدًا لكل شهر تقويمي: فسنة من أسعار الذهب اليومية تتطلب 12 طلبًا. ويتضمن مقال أسعار الذهب والفضة التاريخية عبر API سكربتًا لملء البيانات السابقة ونصائح للتخزين؛ وفي خطة Free غيّر نوافذه السنوية إلى أشهر تقويمية.

كيف تقيّم أي واجهة API مجانية لأسعار الذهب

إذا كنت تقارن بين واجهات API مجانية لأسعار المعادن، فإن الأرقام البارزة تقول أقل مما تقوله التفاصيل. وهذه أسئلة تستحق الإجابة عنها لأي مزود، بما في ذلك نحن:

• ما مدى حداثة البيانات المجانية؟ لحظية أم متأخرة أم يومية، وهل تذكر كل استجابة وقت أسعارها؟
• ما الذي يُحتسب طلبًا؟ استدعاء واحد لرموز كثيرة، أم طلب لكل رمز؟ وهل تُحتسب الاستدعاءات الفاشلة أو المرفوضة؟
• ما نقاط النهاية المشمولة؟ أحدث الأسعار فقط، أم السجل والتحويل والسلاسل الزمنية أيضًا؟
• كم من السجل، وبأي أجزاء؟ إلى أي مدى تعود البيانات، وكم يومًا يمكن أن يغطي طلب النطاق الواحد.
• الوحدات والعملات. الغرام والكيلوغرام وعملتك المحلية، أم أونصات التروي بالدولار الأمريكي فقط؟
• شروط الاستخدام. هل يجوز عرض البيانات على موقع تجاري، وما المستثنى؟
• ماذا يحدث عند بلوغ الحد؟ توقف تام مع خطأ واضح، أم رسوم تلقائية؟ وما سرعة سريان الترقية؟
• التعامل مع المفتاح. هل يمكن إرسال المفتاح في ترويسة بدلًا من عنوان URL، حيث ينتهي به المطاف في السجلات؟

ثم أجرِ اختبارًا عمليًا قصيرًا برموزك وعملاتك؛ ويكفي لذلك مفتاح مجاني. ويحوّل مقال كيف تختار واجهة API لأسعار المعادن الثمينة هذه الأسئلة إلى قائمة تحقق كاملة مع نموذج للمقارنة.

أما إجابات MetalAPI فهي أعلاه وفي التوثيق: لقطات يومية مع timestamp في خطة Free؛ وطلب واحد لكل استدعاء مهما كان عدد الرموز التي يُرجعها؛ وعدم احتساب حالات الرفض بسبب حدود المعدل والخطة والمصدر وأخطاء الخادم؛ وشمول السجل والتحويل والسلاسل الزمنية؛ وأي وحدة وأي عملة من 57 عملة؛ واستخدام البيانات في مواقعك وتطبيقاتك وتقاريرك، بما في ذلك عرض الأسعار لمستخدميك، دون إعادة توزيع التغذية الخام؛ وتوقف تام مع الخطأ 105 عند بلوغ الحصة دون رسوم تجاوز؛ والمفاتيح في ترويسة أو في سلسلة الاستعلام.

متى تنتقل من خطة Free إلى خطة مدفوعة

تكفي خطة Free ما دام السعر اليومي هو السعر المناسب وما دامت 100 طلب تغطي شهرك. وهذه هي العلامات المعتادة على أنها لم تعد كافية:

تسري الترقيات فورًا، لذا فإن المفتاح الذي بلغ الخطأ 105 (quota_exceeded) يعمل مجددًا بمجرد تغيير الخطة؛ وإلا فعليه انتظار إعادة ضبط الحصة في اليوم الأول من الشهر. وتوفّر الفوترة السنوية ما يصل إلى 25%. وتجد في صفحة الأسعار الأسعار الحالية والمقارنة الكاملة، ويشرح دليل حدود المعدل والخطط الحصص والحدود لكل دقيقة بالتفصيل.

أسرع طريقة لمعرفة ما إذا كانت خطة Free تكفي مشروعك هي تجربتها. أنشئ حسابًا مجانيًا، وانسخ مفتاح API من لوحة التحكم، وأرسل طلبك الأول باتباع دليل البدء السريع. لا حاجة إلى بطاقة ائتمان، ويمكنك الانتقال إلى خطة مدفوعة متى احتاج مشروعك إلى أسعار أحدث.

الأسئلة الشائعة

هل توجد واجهة API مجانية تمامًا لأسعار الذهب؟

نعم. خطة Free في MetalAPI مجانية ولا تتطلب بطاقة ائتمان، وتشمل الذهب والفضة والبلاتين والبلاديوم وكل الرموز الأخرى، مع 100 طلب شهريًا وأسعار تُحدَّث مرة يوميًا.

كم مرة تُحدِّث الخطة المجانية أسعار الذهب؟

مرة يوميًا. ترى خطة Free لقطة واحدة تُلتقط عند منتصف الليل بتوقيت UTC، ويُرجع كل طلب حتى منتصف الليل التالي الأسعار نفسها. أما الخطط المدفوعة فتُحدَّث كل 30 دقيقة في Lite وبوتيرة تصل إلى كل 5 ثوانٍ في Enterprise.

هل يمكنني استخدام واجهة API مجانية لأسعار الذهب على موقع تجاري؟

مع MetalAPI، نعم. يمكن استخدام البيانات في مواقعك وتطبيقاتك وأنظمتك الداخلية وتقاريرك، بما في ذلك عرض الأسعار لمستخدميك. أما إعادة توزيع التغذية الخام، كتقديمها على أنها واجهة API خاصة بك، فتتطلب اتفاقية مكتوبة منفصلة.

ماذا يحدث عندما أستنفد 100 طلب؟

تُرجع الطلبات اللاحقة الخطأ 105 (quota_exceeded) مع رمز حالة HTTP 429 حتى تُعاد الحصة في اليوم الأول من الشهر عند 00:00 UTC. ولا توجد رسوم تجاوز تلقائية، والترقية ترفع الحد فورًا.

هل تتضمن الخطة المجانية أسعار الذهب التاريخية؟

نعم. يمكن للمفاتيح المجانية الاستعلام عن السجل الكامل، الذي يعود إلى عام 2000 للذهب، واستخدام /timeframe و/change بنطاقات تصل إلى 30 يومًا لكل طلب.