أفضل الممارسات

اضبط وتيرة الاستطلاع وفق خطتك

تقدّم كل خطة الأسعار وفق فترة تحديث ثابتة: يوميًا في Free، وكل 30 دقيقة في Lite، وكل 10 دقائق في Standard، وكل 60 ثانية في Advanced وPro، وكل 15 ثانية في Ultra وBusiness، وكل 5 ثوانٍ في Enterprise. وطلب /latest بوتيرة أسرع من ذلك يُرجع الأسعار نفسها ويستهلك الحصة دون فائدة.

وكقاعدة عامة، خزّن /latest مؤقتًا طوال فترة التحديث في خطتك، وخزّن بيانات الأيام الماضية بشكل دائم.

اطلب رموزًا كثيرة دفعةً واحدة

يمكن لطلب واحد أن يُرجع أي عدد من الرموز، وتكلفته هي نفسها تكلفة طلب رمز واحد. اطلب كل ما تحتاجه في استدعاء واحد:

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XAU,XAG,XPT,XPD,EUR,GBP

الاستطلاع مرة كل 10 دقائق يستهلك نحو 4,500 طلب شهريًا، والاستطلاع مرة كل دقيقة يستهلك نحو 45,000 طلب. اختر خطتك بناءً على ذلك.

التخزين المؤقت من جهتك

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

const TTL = 10 * 60 * 1000; // Standard plan: 10-minute updates
let cache = { at: 0, data: null };

export async function getPrices() {
  if (cache.data && Date.now() - cache.at < TTL) return cache.data;

  const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG,XPT,XPD", {
    headers: { "X-API-Key": process.env.METALAPI_KEY },
  });
  const data = await res.json();

  if (!data.success) {
    if (cache.data) return cache.data; // serve the last good prices
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

البث بدلًا من الاستطلاع

للوحات المعلومات وأدوات التداول التي تحتاج إلى كل تحديث، استخدم /stream في خطة Pro وما فوقها. يوصل اتصال Server-Sent Events واحد طويل الأمد الأسعار الجديدة فور وصولها، دون حلقة استطلاع تحتاج إلى ضبط.

ولمنطق العتبات مثل «أخبرني عندما يتجاوز الذهب 4,000 دولار»، استخدم تنبيهات الأسعار وخطافات الويب واستغنِ عن الاستطلاع تمامًا.

تعامل مع الأخطاء بسلاسة

• تحقّق من success في كل استجابة، واعتمد على error.code في منطق المعالجة.
• أعد محاولة 104 و500 و503 مع تراجع تدريجي، ولا تُعِد محاولة أخطاء التحقق.
• إذا تعذّر الوصول إلى الواجهة، فاستمر في عرض آخر سعر سليم مع طابعه الزمني.
• راقب ترويسة X-RateLimit-Remaining وصفحة حالة النظام.

التفاصيل والشيفرة في دليل معالجة الأخطاء.

حافظ على أمان تكاملك

• خزّن المفاتيح في متغيرات البيئة أو في مدير أسرار، ولا تضعها أبدًا في Git أو في حزم الشيفرة الخاصة بجانب العميل.
• استخدم المفاتيح المقيّدة بالنطاق لأي استدعاءات من المتصفح.
• استخدم مفتاحًا واحدًا لكل تطبيق وبيئة، وبدّل المفاتيح عندما يغادر أحد أعضاء الفريق أو عند احتمال تسرّب مفتاح.
• تحقّق من ترويسة X-MetalAPI-Signature في كل خطاف ويب، وارفض الطوابع الزمنية القديمة.

نصائح للأداء

• أعد استخدام عميل HTTP واحد حتى تبقى الاتصالات مفتوحة بين الطلبات.
• اقبل الاستجابات المضغوطة (gzip أو br)، وهو ما تفعله معظم عملاء HTTP افتراضيًا.
• اضبط مهلة للطلب في حدود 10 ثوانٍ حتى لا تعطّل شبكة بطيئة تطبيقك أبدًا.
• حمّل /symbols مرة واحدة عند بدء التشغيل وتحقّق من مدخلات المستخدم بناءً عليها، بدلًا من ترك الرموز الخاطئة تُفشل الطلبات.
• استدعِ /usage من أدوات المراقبة لتنبيهك قبل نفاد حصتك، فهي مجانية.