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

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

تُرجع واجهة API لأسعار الذهب سعر الذهب الحالي والتاريخي كبيانات منظَّمة، بصيغة JSON عبر HTTPS عادةً، حتى يستخدمها برنامجك دون استخراج البيانات من صفحات الويب أو نسخ الأرقام يدويًا. في MetalAPI، رمز الذهب هو XAU، وهو رمز ISO 4217 لأونصة تروي واحدة من الذهب. وسعره اللحظي هو السعر الفوري: النقطة الوسطى بين أسعار الطلب والعرض في سوق ما بين البنوك.

معظم عمليات التكامل ليست أنظمة تداول، والاستخدامات المعتادة تبدو كما يلي:

• المتاجر الإلكترونية ومحلات المجوهرات التي تعيد تسعير منتجات الذهب مع تحرك السوق.
• حاسبات ذهب الكسر ومجوهرات العيارات وعلاوات السبائك.
• أدوات تتبع المحافظ وتطبيقات التمويل الشخصي التي تقيّم الحيازات بالعملة المحلية.
• أنظمة المحاسبة وتخطيط موارد المؤسسات (ERP) التي تعيد تقييم المخزون بسعر الإغلاق اليومي.
• لوحات المعلومات والنشرات البريدية والتقارير الداخلية التي تحتاج إلى رسم بياني للعام الماضي.

تغطي الواجهة نفسها الفضة (XAG) والبلاتين (XPT) والبلاديوم (XPD)، وأربعة معادن صناعية، وخمسة عقود للطاقة، و57 عملة، و13 عملة مشفرة: 83 رمزًا إجمالًا، مدرجة كلها في صفحة الرموز. يركّز هذا الدليل على الذهب، لكن كل ما فيه ينطبق على الرموز الأخرى أيضًا.

احصل على مفتاح API

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

في لوحة التحكم، افتح API keys وأنشئ مفتاحًا. تبدأ المفاتيح بـ mk_live_. ولا يُعرض المفتاح كاملًا إلا مرة واحدة، لأننا لا نخزّن سوى قيمة تجزئة له، لذا ضعه فورًا في متغير بيئة أو مدير أسرار:

export METALAPI_KEY="mk_live_your_key_here"

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

# 1. Query parameter
curl "https://metalapi.com/api/v1/latest?api_key=$METALAPI_KEY&currencies=XAU"

# 2. Authorization header
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "Authorization: Bearer $METALAPI_KEY"

# 3. X-API-Key header
curl "https://metalapi.com/api/v1/latest?currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

طلبك الأول عبر curl وJavaScript وPython

كل نقطة نهاية هي طلب GET بسيط تحت https://metalapi.com/api/v1/. تُرجع نقطة النهاية /latest الأسعار الحالية. يحدد base العملة التي تُعرض بها الأسعار (افتراضيًا USD)، ويقصر currencies الاستجابة على الرموز التي تحتاجها. ويمكن لطلب واحد أن يُرجع رموزًا كثيرة ويظل محتسبًا طلبًا واحدًا.

curl "https://metalapi.com/api/v1/latest?base=USD&currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

تبدو الاستجابة الناجحة على النحو التالي. والأرقام هي القيم النموذجية المستخدمة في توثيق MetalAPI، وليست أسعارًا لحظية:

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "rates": {
    "XAU": 0.0002501319,
    "USDXAU": 3997.89,
    "XAG": 0.0185392857,
    "USDXAG": 53.94
  },
  "rate_limit": {
    "limit": 10000,
    "remaining": 9876,
    "reset": 1793491200,
    "used": 124,
    "plan": "Standard",
    "reset_date": "2026-11-01T00:00:00.000Z"
  }
}

وهذا الاستدعاء نفسه من Node.js 18 أو أحدث، الذي يتضمن fetch مدمجًا. احفظه باسم gold.mjs حتى يعمل await في المستوى الأعلى، ثم شغّل node gold.mjs:

const params = new URLSearchParams({ base: "USD", currencies: "XAU,XAG" });
const res = await fetch(`https://metalapi.com/api/v1/latest?${params}`, {
  headers: { Authorization: `Bearer ${process.env.METALAPI_KEY}` },
  signal: AbortSignal.timeout(10_000),
});
const data = await res.json();

if (!data.success) {
  throw new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
}

const gold = data.rates[`${data.base}XAU`];
const asOf = new Date(data.timestamp * 1000).toISOString();
console.log(`Gold: ${gold} ${data.base} per troy ounce (data from ${asOf})`);

ومن Python باستخدام مكتبة requests:

import os

import requests

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"base": "USD", "currencies": "XAU,XAG"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data["success"]:
    err = data["error"]
    raise RuntimeError(f"MetalAPI {err['code']} ({err['type']}): {err['info']}")

base = data["base"]
print(f"Gold:   {data['rates'][base + 'XAU']} {base} per troy ounce")
print(f"Silver: {data['rates'][base + 'XAG']} {base} per troy ounce")

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

اقرأ صيغة الأسعار بشكل صحيح

يظهر كل رمز مرتين في rates، والرقمان مقلوبان أحدهما للآخر:

القاعدة العامة: rates.<BASE><SYMBOL> هو سعر وحدة واحدة من الرمز بعملة الأساس. أما المفتاح المجرد rates.<SYMBOL> فهو المقلوب، أي عدد وحدات الرمز لكل وحدة واحدة من عملة الأساس. ويُحتفظ بالصيغة المقلوبة للتوافق مع واجهات API على نمط أسواق الصرف ومع عمليات التكامل القديمة مع MetalAPI.

إذا كنت تخزّن قيمًا مقلوبة من تكامل قديم، فلا حاجة إلى تنزيلها مجددًا: السعر = 1 ÷ المقلوب. ومع المثال أعلاه، يعطي 1 ÷ 0.0002501319 القيمة 3997.89 مجددًا، باستثناء الأرقام الأخيرة الناتجة عن التقريب.

تتبع العملات القاعدة نفسها. فمع عملة الأساس USD، يكون USDEUR سعر يورو واحد بالدولار، وEUR عدد اليوروهات لكل دولار. ويتضمن دليل صيغ البيانات مزيدًا من الأمثلة، بما فيها مفاتيح الطلب والعرض المتاحة في خطة Standard وما فوقها.

عملات الأساس والوحدات

لتسعير الذهب بعملة أخرى، غيّر base، وسيتغير مفتاح السعر معها: يُرجع base=EUR المفتاح EURXAU، ويُرجع base=INR المفتاح INRXAU. وتأتي الأسعار المتقاطعة من لقطة واحدة، لذا يبقى سعر الذهب باليورو وسعر اليورو بالدولار متسقين دائمًا.

تُسعَّر المعادن لكل أونصة تروي افتراضيًا، ويُرجعها المعامل unit لكل وحدة وزن أخرى:

يُرجع هذا الطلب الذهب والفضة باليورو لكل غرام. وعندما لا تكون unit هي الافتراضية، تكررها الاستجابة في حقل unit في المستوى الأعلى:

curl "https://metalapi.com/api/v1/latest?base=EUR&currencies=XAU,XAG&unit=gram" \
  -H "X-API-Key: $METALAPI_KEY"

لا يؤثر unit إلا في المعادن الثمينة والصناعية، ولا يغيّر الطاقة أو العملات أو العملات المشفرة. ولتفاصيل أونصات التروي والغرامات والتولة والتقريب، اقرأ أونصات التروي والغرامات والكيلوغرامات. وإذا كنت تبيع المجوهرات، فإن مقال شرح أسعار الذهب حسب العيار يتناول أسعار عيار 22 وعيار 18 ونقطة النهاية /carat.

أسعار الذهب التاريخية

تستخدم الأسعار السابقة المعاملات نفسها وصيغة الاستجابة نفسها. يبدأ السجل في عام 2000 للمعادن والطاقة، وفي 1999-01-04 للعملات، وفي عام 2014 للعملات المشفرة. وتغطي أربع نقاط نهاية معظم الاحتياجات:

• /YYYY-MM-DD (أو /historical?date=YYYY-MM-DD، أو /yesterday): أسعار الإغلاق ليوم واحد. وفي عطلات نهاية الأسبوع والعطلات الرسمية، يُرجَع سعر إغلاق أحدث يوم تداول.
• /timeframe (واسمها البديل /timeseries): أسعار الإغلاق اليومية بين start_date وend_date، بحد أقصى 30 يومًا لكل طلب في Free و365 يومًا في الخطط المدفوعة.
• /change: سعر البداية وسعر النهاية والتغيّر المطلق والتغيّر بالنسبة المئوية بين تاريخين.
• /ohlc: سعر الافتتاح والأعلى والأدنى والإغلاق ليوم واحد.

# Gold and silver at the close of 15 January 2024
curl "https://metalapi.com/api/v1/2024-01-15?currencies=XAU,XAG" \
  -H "X-API-Key: $METALAPI_KEY"

# Daily gold closes in euros for September 2026
curl "https://metalapi.com/api/v1/timeframe?start_date=2026-09-01&end_date=2026-09-30&base=EUR&currencies=XAU" \
  -H "X-API-Key: $METALAPI_KEY"

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

الأخطاء والحصص وحدود الخطط

يُرجع الطلب الفاشل حالة خطأ HTTP وجسمًا يتضمن success: false. ويحتوي الكائن error على code رقمي، وtype قابل للقراءة آليًا، وinfo مقروء للبشر. ابنِ منطقك على code أو type، ولا تعتمد أبدًا على نص info. وتتضمن أخطاء حد المعدل (104) والحصة (105) وقيود الخطة (106) والنطاق الزمني (207) أيضًا upgrade_url:

{
  "success": false,
  "error": {
    "code": 106,
    "type": "plan_restriction",
    "info": "The carat endpoint requires a paid subscription plan",
    "upgrade_url": "https://metalapi.com/dashboard/billing"
  }
}

الرموز التي يُرجَّح أن تصادفها:

تُبلغ كل استجابة لطلب مُصادَق عن حصتك، في ترويسات X-RateLimit-* وفي الكائن rate_limit ضمن الجسم معًا. ولا تُحتسب /usage و/symbols من الحصة أبدًا، لذا يمكن لأدوات المراقبة استدعاؤهما بحرية. ولا تُحتسب الطلبات المرفوضة بالأخطاء 104 أو 106 أو 107 أو بخطأ في الخادم، أما أخطاء التحقق فتُحتسب. ويسرد دليل معالجة الأخطاء جميع الرموز ويتضمن دالة مساعدة لإعادة المحاولة.

تختلف الخطط أساسًا في حجم الطلبات ومدى حداثة الأسعار:

توفّر الفوترة السنوية ما يصل إلى 25%. وتجد التفاصيل الحالية دائمًا في صفحة الأسعار.

التخزين المؤقت ونصائح لبيئة الإنتاج

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

import os
import time

import requests

TTL_SECONDS = 600  # Standard plan: prices update every 10 minutes
session = requests.Session()
session.headers["X-API-Key"] = os.environ["METALAPI_KEY"]
_cache = {"at": 0.0, "data": None}


def latest_prices():
    now = time.monotonic()
    if _cache["data"] and now - _cache["at"] < TTL_SECONDS:
        return _cache["data"]
    try:
        r = session.get(
            "https://metalapi.com/api/v1/latest",
            params={"currencies": "XAU,XAG,XPT,XPD"},
            timeout=10,
        )
        data = r.json()
    except (requests.RequestException, ValueError):
        data = None
    if data and data.get("success"):
        _cache.update(at=now, data=data)
        return data
    if _cache["data"]:
        return _cache["data"]  # last good prices; show their timestamp
    raise RuntimeError(data["error"] if data else "MetalAPI unreachable")

وإليك عادات أخرى تُبقي التكامل منخفض التكلفة وموثوقًا:

• اطلب كل الرموز في استدعاء واحد. يكلّف currencies=XAU,XAG,XPT,XPD طلبًا واحدًا، بينما تكلّف أربعة استدعاءات منفصلة أربعة طلبات.
• أبقِ المفتاح على الخادم. إذا اضطر المتصفح إلى استدعاء الواجهة، فاستخدم مفتاحًا مقيّدًا بالنطاق. ولعرض الأسعار على موقع ويب دون كتابة شيفرة، تُبقي الودجة القابلة للتضمين المفتاح خارج الصفحة تمامًا.
• اعرض الطابع الزمني. timestamp هو وقت البيانات، لا وقت طلبك. اعرضه بجوار السعر، خاصةً عند تقديم قيمة مخزَّنة مؤقتًا أو حين تكون السوق مغلقة في عطلة نهاية الأسبوع.
• ضع ميزانية للاستطلاع. الاستطلاع كل 10 دقائق يستهلك نحو 4,500 طلب شهريًا، والاستطلاع كل دقيقة نحو 45,000. ومن خطة Pro فما فوق يمكنك استخدام البث اللحظي بدلًا من ذلك، ومن Advanced فما فوق يمكنك تلقي تنبيهات الأسعار عبر خطافات الويب.
• استخدم مهلًا زمنية وإعادة محاولة انتقائية. اضبط مهلة تقارب 10 ثوانٍ، وأعد محاولة 104 بعد انقضاء Retry-After، وأخطاء 5xx مع تراجع تدريجي، ولا تُعِد أبدًا محاولة أخطاء التحقق.
• تحقّق من الرموز مسبقًا. حمّل /symbols مرة واحدة عند بدء التشغيل (فهي مجانية)، وارفض الرموز غير المعروفة قبل أن تكلّفك طلبًا.

إذا كنت تعمل مع مساعدي الذكاء الاصطناعي، فإن خادم MetalAPI MCP على https://metalapi.com/mcp يتيح البيانات نفسها كأدوات، فيستطيع Claude أو ChatGPT أو Cursor أو VS Code البحث عن أسعار الذهب وسجلها ضمن خطتك؛ راجع الذكاء الاصطناعي وMCP. وللاطلاع على كل نقطة نهاية ومعامل، فإن توثيق API هو المرجع.