واجهة سعر الذهب البرمجية على 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_. لست بحاجة صارمة إلى مفتاح للبدء, الاستدعاءات المجهولة تعمل لكنها محدودة بـ 30 طلباً في الدقيقة و100 في الساعة و1,000 في الشهر لكل عنوان IP، فلأي استخدام يتجاوز اختباراً سريعاً، صادِق.

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

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

# خطأ, 400 invalid_symbolcurl "https://api.goldprice.dev/v1/prices?symbol=XAU"# صحيحcurl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

سعر الفضة الفوري هو XAG-USD-SPOT والنحاس الفوري هو HG-USD-SPOT. تتوفر الأسعار الفورية للذهب والفضة والنحاس على كل الخطط. لا تشمل الخطط الجديدة العقود الآجلة. حذف symbol يعيد الصفوف الافتراضية المسموح بها لمستواك.

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

تحمل كل استجابة X-RateLimit-Remaining. اقرأها وتباطأ قبل الوصول إلى الصفر. حدود الطلبات في الدقيقة هي Free 10، وBasic 60، وPlus 120، وPro 300. يقلل التخزين المؤقت القصير عدد الاستدعاءات.

"خطأ 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 وcomputed_at وis_stale. الحقلان bid وask اختياريان للخطط المدفوعة فقط، ويتطلبان عرضاً متسقاً للجانبين. كل ما هو أغنى اختياري عبر ?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 آخر سنة، وPlus وPro السجل الكامل. لذا إذا عاد استعلام تاريخي أقصر مما توقعت، فذلك نافذة مستواك، لا خطأ مصادقة.

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

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

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

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