واجهة سعر الذهب البرمجية على Stack Overflow: أخطاء المطورين، محلولة

عندما يتعطل تكامل ما، يلصق المطورون الخطأ في Stack Overflow. الأسئلة التي تتكرر مع واجهة سعر الذهب البرمجية هي دائماً تقريباً نفس الحفنة: رفض مصادقة، رمز مشوّه، جدار حدود معدل، أو خطأ CORS من المتصفح. تحل هذه المقالة كل واحدة منها مباشرة، مستخدمة goldprice.dev كمثال عملي. كل مقطع كود أدناه استدعاء حقيقي وعامل ضد https://api.goldprice.dev.

"401 Unauthorized" — مفتاح API الخاص بي مرفوض

يوضع المفتاح في ترويسة Authorization كرمز حامل (bearer token)، ويجب أن تكون كلمة Bearer (متبوعة بمسافة) موجودة:

curl https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT \
  -H "Authorization: Bearer ga_live_YOUR_KEY"

الأشياء الثلاثة التي تسبب فعلياً خطأ 401: غياب البادئة Bearer ، أو وجود سطر جديد أو علامة اقتباس زائدة في المفتاح من عملية نسخ ولصق، أو قراءة المفتاح من متغير بيئة غير محمّل. المفاتيح تبدأ بالبادئة ga_live_. لست بحاجة صارمة إلى مفتاح للبدء — الاستدعاءات المجهولة تعمل لكنها محدودة بـ 100 طلب في الساعة لكل عنوان IP، فلأي استخدام يتجاوز اختباراً سريعاً، صادِق.

"400 invalid_symbol" — الخطأ الأول الأكثر شيوعاً

معامل symbol ليس مجرد رمز معدن مجرد. إنه بالصيغة BASE-QUOTE-CONTRACT. تمرير symbol=XAU يعيد 400 invalid_symbol؛ القيمة الصحيحة لسعر الذهب الفوري الحي هي XAU-USD-SPOT:

# خطأ — 400 invalid_symbol
curl "https://api.goldprice.dev/v1/prices?symbol=XAU"

# صحيح
curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

سعر الفضة الفوري هو XAG-USD-SPOT والنحاس HG-USD-FUTURES. تستخدم العقود الآجلة عقد FUTURES، على سبيل المثال XAU-USD-FUTURES — لاحظ أن عقود الذهب الآجلة تحتاج مستوى Basic، والفضة والنحاس يحتاجان Pro، لذا في المستوى المجاني تعيد هذه الرموز 403 plan_gated. حذف symbol تماماً يعيد الصفوف الافتراضية المسموح بها لمستواك، وهذه أيضاً طريقة صحيحة لتفادي الخطأ.

"429 Too Many Requests" — التعامل مع حدود المعدل

تحمل كل استجابة ترويسة X-RateLimit-Remaining. اقرأها وتباطأ قبل الوصول إلى الصفر بدلاً من الاستطلاع الأعمى وتلقي أخطاء 429. المستوى المجاني هو 30 طلباً في الدقيقة؛ Physical هو 120؛ Pro وRealtime Pro هما 500. لمعظم التطبيقات، تكفي ذاكرة تخزين مؤقتة قصيرة من جهة العميل، بحجم يتناسب مع وتيرة تغيّر السعر فعلياً، لتبقى بعيداً بأمان عن الحد — فالسعر الفوري لا يتغيّر بشكل ملموس كل ثانية، لذا التخزين المؤقت لبضع ثوانٍ صحيح عادةً.

"خطأ CORS" — استدعاء الواجهة البرمجية من المتصفح

لا تستدعِ الواجهة البرمجية مباشرة من JavaScript في الواجهة الأمامية بمفتاحك. لسببين: يعرّض ذلك ga_live_... لأي شخص يفتح أدوات المطورين، وسيحظره CORS في المتصفح. مرّر الاستدعاء عبر الخادم الخلفي الخاص بك، وأبقِ المفتاح من جهة الخادم، واجعل المتصفح يستدعي نقطة نهايتك الخاصة:

// مسار الخادم الخلفي الخاص بك — المفتاح لا يصل إلى المتصفح أبداً
const r = await fetch(
  "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT",
  { headers: { Authorization: `Bearer ${process.env.GOLDPRICE_API_KEY}` } },
);
const data = await r.json();

إذا كان الهدف هو مجرد عرض سعر حي بدلاً من معالجة JSON، استخدم أداة سعر الذهب المجانية. إطار iframe المستضاف الخاص بها لا يحتاج مفتاح API ويتجنب مسار CORS في المتصفح كلياً.

"أي حقل هو السعر؟" — قراءة الاستجابة

الاستجابة الافتراضية، مجهولة كانت أم موثّقة، تعطيك price وَbid وَask وَcomputed_at وَis_stale — لا شيء آخر. كل ما هو أغنى اختياري عبر ?include=: يضيف ?include=sources مصفوفة sources[]، ويضيف ?include=karat تفصيلاً لكل غرام حسب القيراط، ويضيف ?include=stats (موثّق فقط) الحقول open_price وَhigh_price وَlow_price وَprev_close_price، وحقول التغيّر، وَdivergence_bps / divergence_flag. يعيد ?include=all كل ما يسمح به مستوى مصادقتك. حقلان مهمان للدقة:

• is_stale — يكون true عندما تكون القيمة أقدم من نافذة تحديثها المتوقعة. تحقق منه قبل عرض أي سعر.
• sources[] (مع ?include=sources) — صف واحد لكل مصدر أساسي (upstream)، لكل منها price وَtimestamp خاصان به. عندما تختلف المصادر، يخبرك divergence_bps (مع ?include=stats) بمقدار الاختلاف، كي تحدد تفاوتك الخاص بدلاً من الثقة برقم واحد مدمج.

"كيف أحصل على بيانات تاريخية / OHLC؟"

سجل الإغلاق اليومي متاح عبر GET /v1/prices/history، على كل مستوى — ما يتغيّر هو المدى الذي يمكنك الرجوع إليه. يعيد المستوى المجاني آخر 30 يوماً، وBasic آخر سنة، وPro السجل الكامل. لذا إذا عاد استعلام تاريخي أقصر مما توقعت، فذلك نافذة مستواك، لا خطأ مصادقة.

أقصر استدعاء يعمل

بلا مفتاح، برمز صحيح:

curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

يعيد ذلك سعر ذهب حياً وصادقاً بعلامة حداثة. أضف ?include=sources للمصادر المساهمة. عندما تريد الشكل الكامل للاستجابة وحدوداً أعلى، يستغرق مفتاح مجاني دقيقة واحدة. إذا كنت تفضل شرحاً خاصاً بلغة برمجة معينة، تغطي جلب أسعار الذهب الحية بلغة JavaScript مسار REST من البداية إلى النهاية، وتغطي تخزين أسعار الذهب مؤقتاً والبقاء ضمن حدود المعدل فعل ذلك عند الحجم الكبير.