أسعار النحاس والألومنيوم والزنك والنفط عبر API: دليل للمطورين

رموز المعادن الصناعية والطاقة

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

تسرد صفحة الرموز هذه الرموز مع أسعارها المباشرة، ويُرجع GET /api/v1/symbols?details=1 فئة كل رمز ووحدته بصيغة JSON. وهذا الاستدعاء مجاني ولا يُحتسب من حصتك.

الوحدات الأصلية مقابل توحيد الواجهة

لكل سوق من هذه الأسواق اصطلاحها الخاص. ففي نيويورك يُتداول النحاس بالرطل، والألومنيوم والزنك بالطن المتري، والصلب الأمريكي بالطن القصير، والنفط الخام بالبرميل، والغاز الطبيعي بالمليون وحدة حرارية بريطانية (MMBtu)، والمنتجات المكررة بالغالون. وإذا خلطت بينها، فستنحرف أرقامك بمعامل ألف أو أكثر.

توحّد MetalAPI وحدات المعادن وتترك الطاقة بوحدات عقودها:

• جميع المعادن، الثمينة والصناعية، تُسعَّر لكل أونصة تروي افتراضيًا. وهذا يجعل كل المعادن قابلة للمقارنة مباشرةً، ويتيح لك تحويل أي منها بمعامل واحد. لكن سعر النحاس لكل أونصة تروي ليس رقمًا يتداوله أحد، لذا ستمرّر unit في الغالب مع المعادن الصناعية.
• تُسعَّر الطاقة بوحدة العقد: البرميل لـ WTI وBRENT، وMMBtu لـ NATURALGAS، والغالون الأمريكي لـ GASOLINE وHEATINGOIL. ولا ينطبق المعامل unit على الطاقة أو العملات أو العملات المشفرة.

يقبل unit القيم troy_oz (الافتراضية) وgram وkilogram وounce وpound وmetric_ton وshort_ton. وللحصول على كل معدن بالوحدة التي تستخدمها سوقه:

# Copper in USD per pound
curl "https://metalapi.com/api/v1/latest?currencies=XCU&unit=pound" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Aluminium and zinc in USD per metric ton
curl "https://metalapi.com/api/v1/latest?currencies=ALU,ZNC&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Hot-rolled coil steel in USD per short ton
curl "https://metalapi.com/api/v1/latest?currencies=HRC&unit=short_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

عند استخدام وحدة غير افتراضية، تذكر الاستجابة ذلك في الحقل unit. والسعر الذي تريده هو المفتاح المسبوق بعملة الأساس (USDXCU)؛ أما المفتاح المجرد XCU فهو مقلوبه، ويُحتفظ به للتوافق مع عمليات التكامل القديمة:

{
  "success": true,
  "timestamp": 1792834892,
  "date": "2026-10-24",
  "base": "USD",
  "unit": "pound",
  "rates": {
    "XCU": 0.2222222222,
    "USDXCU": 4.5
  }
}

الأسعار المبنية على العقود الآجلة ومعنى الشهر الأقرب

يُتداول الذهب الفوري خارج البورصة على مدار الساعة، أما المعادن الصناعية والطاقة فتُسعَّر بأكبر قدر من الشفافية في بورصات العقود الآجلة. تأخذ MetalAPI هذه الأسعار من COMEX وNYMEX (وكلتاهما جزء من CME Group) ومن ICE. والعقد الآجل اتفاق موحَّد لشراء كمية محددة أو بيعها بسعر محدد للتسليم في شهر معيّن، وكل شهر تسليم عقد مستقل بسعره الخاص.

الشهر الأقرب هو أقرب شهر تسليم لا يزال قيد التداول. وتتبع سلسلة الشهر الأقرب المستمرة ذلك العقد حتى يقترب من الاستحقاق، ثم تنتقل، أو تُدحرَج، إلى العقد التالي. وثلاث نتائج لذلك تهم المطورين:

• قفزات الدحرجة. في تاريخ الدحرجة قد تقفز السلسلة، لا لأن السوق تحركت، بل لأن العقد التالي يُتداول بسعر مختلف. فعندما تكون الأشهر اللاحقة أغلى (الكونتانجو) ترتفع السلسلة درجة، وعندما تكون أرخص (الباكورديشن) تنخفض درجة. ضع ذلك في الحسبان قبل إطلاق تنبيه بناءً على تغيّر يوم واحد قرب الاستحقاق.
• بورصة واحدة ليست السوق كلها. سعر النحاس في COMEX سعر بورصة أمريكية. ويُسعَّر جزء كبير من النحاس والألومنيوم والزنك المادي في العالم استنادًا إلى بورصة لندن للمعادن، وتضيف عمليات التسليم المادي علاوات إقليمية وتكاليف شحن وضرائب. تتتبع الأسعار في الأسواق المختلفة بعضها بعضًا عن كثب، لكن ليس بدقة تامة. وإذا نصّ عقد توريد على مرجع محدد، مثل السعر الرسمي لبورصة LME أو تقييم سعري منشور، فذلك المرجع هو الذي يحكم فاتورتك. فبيانات العقود الآجلة من البورصة أداة جيدة للمراقبة والتقدير، لكنها ليست بديلًا عن المؤشر التعاقدي.
• ساعات التداول. تتبع هذه العقود ساعات بورصاتها: على مدار الساعة تقريبًا من مساء الأحد إلى ظهر الجمعة بتوقيت نيويورك، مع استراحة يومية قصيرة. وفي عطلة نهاية الأسبوع تواصل MetalAPI إرجاع آخر سعر.

ولأن هذه الرموز مأخوذة من العقود الآجلة، فإنها تُنشر بسعر واحد، ولا تتوفر لها لاحقتا الطلب والعرض. ويمتد السجل اليومي للمعادن والطاقة إلى عام 2000، ويوضح دليل البيانات التاريخية كيفية الاستعلام عن أسعار الإغلاق والنطاقات وأشرطة OHLC.

تحويل الوحدات والعملات

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

// Troy ounces in one unit of mass
const GRAMS_PER_TROY_OZ = 31.1034768;
const TROY_OZ_PER = {
  lb: 453.59237 / GRAMS_PER_TROY_OZ,        // 14.5833…
  short_ton: 907184.74 / GRAMS_PER_TROY_OZ, // 29,166.67…
  metric_ton: 1e6 / GRAMS_PER_TROY_OZ,      // 32,150.75…
};

const NATURAL_UNIT = { XCU: "lb", ALU: "metric_ton", ZNC: "metric_ton", HRC: "short_ton" };

const url = new URL("https://metalapi.com/api/v1/latest");
url.searchParams.set("currencies", Object.keys(NATURAL_UNIT).join(","));

const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
const data = await res.json();
if (!data.success) throw new Error(data.error.code + ": " + data.error.info);

for (const [symbol, unit] of Object.entries(NATURAL_UNIT)) {
  const perTroyOz = data.rates["USD" + symbol]; // USD per troy ounce
  if (perTroyOz === undefined) continue;
  console.log(symbol, (perTroyOz * TROY_OZ_PER[unit]).toFixed(2), "USD per", unit);
}

تعمل العملات بالطريقة نفسها مع المعادن والطاقة. أضف base=EUR، أو أيًا من العملات الـ 57 المدعومة، وستُعرض كل الأسعار في الاستجابة بتلك العملة، محوَّلة من اللقطة نفسها. ولتقييم كمية مباشرةً، تأخذ /convert مبلغًا ووحدة:

# 25 metric tons of copper in euros
curl "https://metalapi.com/api/v1/convert?from=XCU&to=EUR&amount=25&unit=metric_ton" \
  -H "Authorization: Bearer YOUR_API_KEY"

أما تحويلات الطاقة فتجري في شيفرتك. ومن المعاملات القياسية المفيدة: البرميل الواحد يساوي 42 غالونًا أمريكيًا أو نحو 158.987 لترًا؛ والغالون الأمريكي يساوي 3.785411784 لترات؛ وMMBtu الواحد يساوي نحو 1.055 جيجاجول أو 293.07 كيلوواط ساعة أو 10 ثيرم. ويعتمد تحويل براميل النفط الخام إلى أطنان على كثافة النفط، لذا استخدم المعامل الخاص بالدرجة التي تشتريها فعلًا.

حالة استخدام: المشتريات ومراقبة التكاليف

تستخدم فرق المشتريات أسعار البورصات لفهم اتجاه تكاليف المدخلات وللتحقق من معقولية عروض الموردين. ومن اللبنات المعتادة:

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

# Copper and aluminium per metric ton: change over September 2026
curl "https://metalapi.com/api/v1/change?currencies=XCU,ALU&unit=metric_ton&start_date=2026-09-01&end_date=2026-09-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

تذكّر التحفظ السابق: إذا كان العقد مربوطًا بسعر منشور محدد، فطابِق مع ذلك المؤشر كل ما ينتهي به المطاف في فاتورة.

حالة استخدام: نماذج تكاليف التصنيع

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

import os
import requests

# Metal content per unit of product, in kg (illustrative)
BOM = {"XCU": 1.20, "ALU": 0.85, "ZNC": 0.05}

resp = requests.get(
    "https://metalapi.com/api/v1/latest",
    params={"currencies": ",".join(BOM), "unit": "kilogram", "base": "EUR"},
    headers={"X-API-Key": os.environ["METALAPI_KEY"]},
    timeout=10,
)
data = resp.json()
if not data.get("success"):
    raise RuntimeError(data["error"])

total = 0.0
for symbol, kg in BOM.items():
    eur_per_kg = data["rates"]["EUR" + symbol]
    cost = kg * eur_per_kg
    total += cost
    print(f"{symbol}: {kg} kg x {eur_per_kg:.4f} EUR/kg = {cost:.2f} EUR")

print(f"Metal content per unit: {total:.2f} EUR (prices of {data['date']})")

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

حالة استخدام: الخدمات اللوجستية وتكاليف الوقود

الوقود هو أكبر تكلفة متغيرة لدى كثير من شركات النقل، وكثيرًا ما يُعاد حساب رسوم الوقود الإضافية أسبوعيًا أو شهريًا. ويُعد HEATINGOIL، وهو عقد الديزل فائق انخفاض الكبريت في ميناء نيويورك، مرجعًا واسع المتابعة لأسعار الديزل بالجملة. ويؤدي GASOLINE (RBOB) الدور نفسه للبنزين، بينما يغطي WTI وBRENT النفط الخام.

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

يحسب هذا المثال متوسط أسعار الإغلاق اليومية لعقد الديزل في الأسبوع الماضي، ويحوّل النتيجة من دولار أمريكي لكل غالون إلى يورو لكل لتر:

const LITRES_PER_GALLON = 3.785411784;

const url = new URL("https://metalapi.com/api/v1/timeframe");
url.searchParams.set("currencies", "HEATINGOIL");
url.searchParams.set("base", "EUR");
url.searchParams.set("start_date", "2026-10-19");
url.searchParams.set("end_date", "2026-10-23");

const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
const data = await res.json();
if (!data.success) throw new Error(data.error.code + ": " + data.error.info);

// rates is keyed by date; days without a close (weekends, holidays) are missing
const closes = Object.values(data.rates).map((day) => day.EURHEATINGOIL);
const avgPerGallon = closes.reduce((sum, p) => sum + p, 0) / closes.length;

console.log("Average:", (avgPerGallon / LITRES_PER_GALLON).toFixed(4), "EUR per litre");

نصائح عملية

• استطلع وفق فترة خطتك، لا أسرع. ترى Free أسعارًا يومية، وLite كل 30 دقيقة، وStandard كل 10 دقائق، وAdvanced وPro كل دقيقة، وUltra وBusiness كل 15 ثانية، وEnterprise كل 5 ثوانٍ. والطلبات بين التحديثات تُرجع اللقطة نفسها وتُحتسب مع ذلك. ومن خطة Pro فما فوق، يحل البث اللحظي محل الاستطلاع.
• اجمع الرموز في طلب واحد. يمكن لطلب واحد أن يُرجع رموز المعادن الصناعية والطاقة التسعة كلها، وتكلفته مثل تكلفة طلب رمز واحد.
• خزّن ما جلبته. احفظ كل سعر مع رمزه ووحدته وعملة الأساس وtimestamp. فالتحويل لاحقًا سهل، أما تخمين وحدة رقم قديم فليس كذلك.
• توقّع فجوات في السجل. تتخطى السلاسل اليومية عطلات نهاية الأسبوع وعطلات البورصات، لذا لا تفترض وجود إدخال لكل يوم تقويمي.
• قسّم النطاقات الطويلة. يغطي طلب /timeframe الواحد حتى 365 يومًا في الخطط المدفوعة، لذا كرّر الطلب سنة بسنة للسجلات الأطول الممتدة حتى عام 2000.
• تحقّق قبل الإرسال. الطلبات المرفوضة بسبب تواريخ أو رموز أو وحدات غير صالحة تُحتسب من حصتك، لذا تحقّق منها في شيفرتك أولًا. أما الرفض بسبب حد المعدل وأخطاء الخادم فلا يُحتسب.

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