كيف تختار واجهة API لأسعار المعادن الثمينة: 12 سؤالًا عليك طرحها

لماذا تفيد قائمة التحقق

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

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

البيانات: المصادر وحداثة البيانات والسجل

1. من أين تأتي الأسعار؟ يمكن أن تأتي أسعار المعادن الثمينة من عدة أنواع من المصادر: تسعيرات البنوك ومزوّدي السيولة في السوق الفورية خارج البورصة، أو العقود الآجلة في البورصات مثل ذهب COMEX، أو الأسعار المرجعية الرسمية مثل أسعار مزادات LBMA، أو مُجمِّع بيانات آخر. لا يُعدّ أي منها خاطئًا، لكنها أرقام مختلفة. اسأل عن المصدر الذي يغذّي كل رمز، وهل تُدمج عدة مصادر وكيف، وكيف تُستبعد التسعيرات الشاذة الواضحة. إذا لم يستطع المزوّد أن يوضح ما يمثله سعر الذهب لديه (السعر الوسطي الفوري أم العقود الآجلة أم السعر المرجعي)، فلن تستطيع أنت أيضًا شرحه لمستخدميك.

2. ما مدى حداثة البيانات في الخطة التي ستدفع ثمنها فعلًا؟ كثيرًا ما تصف عبارة «لحظي» على الصفحة الرئيسية الخطة الأعلى. تحقّق من فترة التحديث في كل خطة، وتأكد من أن كل استجابة تحمل الطابع الزمني للبيانات نفسها، لا لطلبك فقط. واسأل عما يحدث خارج ساعات التداول: يتوقف تداول المعادن الفورية من مساء الجمعة حتى مساء الأحد بتوقيت نيويورك، والواجهة الجيدة توضح أن سعر عطلة نهاية الأسبوع هو سعر إغلاق يوم الجمعة.

3. ما عمق السجل التاريخي، ومما يتكوّن؟ تحقّق من تاريخ البداية لكل فئة أصول، وهل تحصل على أسعار الإغلاق اليومية فقط أم على أسعار الافتتاح والأعلى والأدنى والإغلاق، وكيف يُعرَّف «الإغلاق» (بأي منطقة زمنية ومن أي مصدر). واسأل عما إذا كان السجل الأقدم يأتي من مصدر مختلف عن أسعار اليوم، كتسويات العقود الآجلة قبل تاريخ معيّن، لأن ذلك قد يُحدث انقطاعات طفيفة في الرسوم البيانية الطويلة. وأخيرًا، تحقّق من عدد الأيام التي يمكن أن يغطيها طلب نطاق واحد.

الملاءمة: الوحدات والعملات وسعرا الطلب والعرض

4. ما الوحدات والعملات المدعومة؟ تُتداول المعادن الثمينة بأونصة التروي، لكن مستخدميك قد يفكرون بالغرام أو الكيلوغرام وبعملتهم المحلية. يوفّر عليك معامل الوحدة إجراء كل تحويل بنفسك؛ تحقّق من الطريقة التي تسمّي بها الواجهة الوحدات، لأن أونصة التروي (31.103 غ) والأونصة العادية (28.35 غ) تختلفان بنحو 10% تقريبًا. وإذا كنت تحتاج إلى أسعار متقاطعة، مثل الذهب بالليرة التركية أو الفضة بالين، فتأكد من أنها محسوبة من لقطة واحدة متسقة. وقد تحتاج تطبيقات المجوهرات أيضًا إلى الأسعار حسب العيار.

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

التشغيل: الموثوقية والحدود والأخطاء

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

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

8. كيف يُبلَّغ عن الأخطاء؟ تُرجع الواجهة الجيدة حالة HTTP ذات معنى مع رمز خطأ قابل للقراءة آليًا ورسالة مفهومة للبشر، وتوثّق كل رمز، وتخبرك متى تعيد المحاولة، مثلًا عبر ترويسة Retry-After عند بلوغ حدود المعدل. تأكد من أن صيغة الأخطاء موحّدة في جميع نقاط النهاية، ومن توفر مواصفة قابلة للقراءة آليًا، مثل OpenAPI، لتوليد العملاء والاختبارات.

الجانب التجاري: التسعير والأمان والشروط

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

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

11. ماذا تسمح به الشروط؟ اقرأ ترخيص البيانات قبل أن تبدأ التطوير. هل يحق لك عرض الأسعار على عملائك؟ هل يحق لك تخزين السجل في قاعدة بياناتك؟ هل يُسمح بإعادة التوزيع، كتقديم البيانات عبر واجهة API خاصة بك، وإن لم يكن مسموحًا فهل يتوفر ترخيص لذلك؟ هل يلزم ذكر المصدر؟ تديرُ الأسعارَ المرجعية الرسمية، مثل أسعار LBMA، جهاتٌ مسؤولة عن إدارة المؤشرات المرجعية، وتُرخَّص عادةً بشكل منفصل، لذا اسأل عما إذا كانت التغذية تحتوي على بيانات مرجعية وما يعنيه ذلك بالنسبة إليك. وتحقّق من إخلاء المسؤولية أيضًا: تُقدَّم بيانات الأسعار عادةً لأغراض إعلامية، لا بوصفها عرضًا للتداول.

الاستعداد للمستقبل: دعم الذكاء الاصطناعي وMCP

12. هل يمكن لمساعدي الذكاء الاصطناعي والوكلاء استخدامها؟ يجري اليوم جزء متزايد من التحليل داخل مساعدي المحادثة ووكلاء البرمجة. وبروتوكول سياق النموذج (MCP) معيار مفتوح لربطهم بالأدوات والبيانات، والمزوّد الذي يوفر خادم MCP يتيح للمساعد جلب أسعار حقيقية بدلًا من تخمينها من بيانات تدريبه. أسئلة ينبغي طرحها:

• هل يوجد خادم MCP مستضاف، وما بروتوكولات النقل والعملاء التي يدعمها؟
• كيف تتم المصادقة: تسجيل الدخول عبر OAuth لتطبيقات المحادثة، أم مفتاح API لأدوات المطورين، أم كلاهما؟
• ما الأدوات المخصصة للقراءة فقط، وهل تطلب الأدوات التي تُجري تغييرًا تأكيدك أولًا؟
• هل تُحتسب استدعاءات المساعد من الحصة نفسها، وهل يمكن للخادم أن يفرض عليك رسومًا من تلقاء نفسه؟
• هل يتوفر توثيق مكتوب للنماذج اللغوية، مثل ملف llms.txt أو مواصفة OpenAPI، حتى يتمكن مساعد البرمجة من كتابة التكامل بشكل صحيح؟

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

نموذج مقارنة يمكنك تعبئته

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

الإجابات المكتوبة بداية جيدة، لكن اختبارًا عمليًا قصيرًا يحسم معظمها. باستخدام مفتاح مجاني أو تجريبي لكل مزوّد مرشّح:

1. اطلب الرموز نفسها في اللحظة نفسها من كل مزوّد، وقارن القيم والطوابع الزمنية والوحدات.
2. كرّر الطلب يوم السبت، وانظر كيف تعبّر كل واجهة عن السوق المغلقة.
3. تسبّب في أخطاء عمدًا (مفتاح خاطئ، رمز غير معروف، تاريخ مستقبلي) وتحقّق من رموز الحالة والرسائل.
4. اطلب سجلًا يوميًا لمدة عام، وابحث عن الفجوات والقفزات المفاجئة وأي تغيّر ظاهر في المستوى قد يدل على تبديل المصدر.
5. قِس زمن الاستجابة من المكان الذي تعمل فيه خوادمك، لا من حاسوبك المحمول.

يساعدك هذا السكربت الصغير في النقطتين الأولى والأخيرة. عدّل عنوان URL وترويسة المصادقة وحقل الطابع الزمني وفق توثيق كل مزوّد، وتذكّر أن كل استدعاء يستهلك من الحصة:

// Calls an endpoint a few times and records HTTP status, latency and data age.
const TARGET = process.env.PRICE_API_URL;
const HEADERS = { Authorization: "Bearer " + process.env.PRICE_API_KEY };

for (let i = 0; i < 5; i++) {
  const started = Date.now();
  const res = await fetch(TARGET, { headers: HEADERS });
  const body = await res.json().catch(() => ({}));
  const latencyMs = Date.now() - started;

  // Many APIs return Unix seconds; adapt this line to the provider's field.
  const dataTime = typeof body.timestamp === "number" ? body.timestamp * 1000 : null;
  const dataAgeSeconds = dataTime ? Math.round((Date.now() - dataTime) / 1000) : "n/a";

  console.log({ status: res.status, latencyMs, dataAgeSeconds });
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

كيف يجيب MetalAPI عن هذه الأسئلة

للاكتمال، إليك إجاباتنا نحن، مقتصرةً على حقائق يمكنك التحقق منها في توثيقنا. ونرجو أن تحاسبنا بالمعيار نفسه الذي تحاسب به الآخرين.

1. المصادر: المعادن الثمينة الفورية والعملات الرئيسية من تغذيات أسعار الطلب والعرض ما بين البنوك؛ والمعادن الصناعية والطاقة من العقود الآجلة للشهر الأقرب في COMEX وNYMEX وICE؛ والعملات المشفرة من Kraken وBinance؛ والأسعار المرجعية للبنك المركزي الأوروبي لأسعار الصرف. تُدمج المصادر المتعددة بحساب الوسيط، وتُفحص بحثًا عن التسعيرات الشاذة.
2. حداثة البيانات: يوميًا في Free، وكل 30 دقيقة في Lite، وكل 10 دقائق في Standard، وكل دقيقة في Advanced وPro، وكل 15 ثانية في Ultra وBusiness، وكل 5 ثوانٍ في Enterprise. تحمل كل استجابة timestamp الخاص بالبيانات؛ وخلال عطلة نهاية الأسبوع تبقى أسعار المعادن والعملات والعقود الآجلة عند إغلاق يوم الجمعة.
3. السجل التاريخي: أسعار الافتتاح والأعلى والأدنى والإغلاق اليومية للعملات منذ 1999، وللمعادن والطاقة منذ 2000، وللعملات المشفرة منذ 2014. ويستند سجل المعادن قبل أكتوبر 2026 إلى تسويات العقود الآجلة للشهر الأقرب. ويغطي طلب النطاق الواحد حتى 30 يومًا في Free و365 يومًا في الخطط المدفوعة.
4. الوحدات والعملات: سبع وحدات كتلة من الغرام إلى الطن القصير، و57 عملة، وإمكانية استخدام أي رمز كعملة أساس، مع أسعار متقاطعة من لقطة واحدة. وأسعار الذهب حسب العيار في الخطط المدفوعة.
5. الطلب/العرض: رموز على غرار XAU-BID وXAU-ASK في خطة Standard وما فوقها، للمعادن الثمينة والعملات الرئيسية، من اللقطة نفسها التي يأتي منها السعر الوسطي.
6. الموثوقية: صفحة حالة عامة تعرض مصادر البيانات وزمن الاستجابة وحجم استخدام الواجهة، بما في ذلك الأوقات التي تُستخدم فيها المصادر الاحتياطية؛ واتفاقية مستوى خدمة لوقت التشغيل في خطتي Business وEnterprise.
7. الحدود: حصة شهرية إضافةً إلى حد في الدقيقة في كل خطة. يُحتسب الطلب مرة واحدة مهما كان عدد الرموز التي يُرجعها؛ و/symbols و/usage مجانيتان؛ ولا تُحتسب الطلبات المرفوضة بسبب حدود المعدل أو قيود الخطة أو التحقق من المصدر أو أخطاء الخادم. وعند بلوغ الحصة، تُرجع الطلبات الخطأ 105 حتى اليوم الأول من الشهر (UTC) أو حتى الترقية؛ ولا توجد رسوم تجاوز تلقائية.
8. الأخطاء: حالة HTTP مع code رقمي وtype ورسالة info بصيغة JSON، وترويسة Retry-After عند بلوغ حدود المعدل، وقائمة موثّقة بالرموز، ومواصفة OpenAPI 3.1.
9. التسعير: خطط ثابتة تبدأ من Free ($0، و100 طلب شهريًا) مرورًا بـ Lite ($4.99) وStandard ($11.99) وAdvanced ($24.99) وPro ($49.99) وUltra ($99.99) وBusiness ($149.99) وصولًا إلى Enterprise ($299.99، و1.5 مليون طلب)، بفوترة شهرية أو سنوية، ويمكن إلغاؤها من صفحة الفوترة. التفاصيل في صفحة الأسعار.
10. الأمان: لا تُخزَّن المفاتيح إلا كقيم تجزئة، ويمكن إرسالها في ترويسة؛ وبحسب الخطة يمكنك الاحتفاظ بعدة مفاتيح وتدويرها أو إلغاؤها وتقييدها بنطاقاتك. وتعرض الودجات القابلة للتضمين الأسعار دون كشف أي مفتاح.
11. الشروط: يحق لك استخدام البيانات في مواقعك وتطبيقاتك وأنظمتك الداخلية وتقاريرك، بما في ذلك عرض الأسعار على مستخدميك؛ أما إعادة توزيع التغذية الخام، كتقديمها مثلًا عبر واجهة API خاصة بك، فتتطلب اتفاقية مكتوبة منفصلة. تُقدَّم البيانات لأغراض إعلامية ولا تُعد نصيحة استثمارية. راجع الشروط.
12. الذكاء الاصطناعي وMCP: خادم MCP مستضاف على https://metalapi.com/mcp (Streamable HTTP، مع OAuth 2.1 أو مفتاح API) يضم 13 أداة، منها 11 للقراءة فقط؛ وتطلب الأداتان اللتان تُجريان تغييرًا تأكيدك أولًا، ولا يفرض الخادم أي رسوم على الإطلاق. وهو مُدرج في سجل MCP الرسمي، كما نُشر ملف llms.txt ومواصفة OpenAPI. راجع الذكاء الاصطناعي وMCP.

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