دليل البدء السريع لـ API في FoxReload 2026 — أول استدعاء لك في 10 دقائق

كُتب دليل البدء السريع هذا لـ API في FoxReload للمطوّرين الخلفيين ومهندسي المشتريات الذين يحتاجون إلى تكامل كتالوج سلع رقمية بالجملة داخل متجرهم أو بوتهم أو أدواتهم الداخلية. بنهاية هذا المقال ستكون قد أجريت طلبًا حقيقيًا مُصادَقًا عليه مقابل https://public-api.foxreload.com وأنشأت طلبًا وهميًا.

1. احصل على مفتاح الـ API الخاص بك

افتح لوحة تحكّم FoxReload، واذهب إلى Dashboard ← API ← Create New Key. يُعرض المفتاح مرة واحدة بالضبط — انسخه فورًا إلى مدير الأسرار لديك. اختياريًا قيّده بقائمة عناوين IP مسموح بها (حتى 10 عناوين أو نطاقات CIDR). لا توجد بادئات مفاتيح test_ أو live_؛ فالمفتاح نفسه يعمل مقابل واجهة الإنتاج.

لا تُودِع المفاتيح في git أبدًا. خزّنها في مدير الأسرار لديك (AWS Secrets Manager أو Doppler أو Vault) وحقنها وقت التشغيل.

2. ترويسة المصادقة

يستخدم FoxReload ترويسة مفتاح API واحدة. يجب أن يتضمن كل طلب —

X-API-Key: YOUR_API_KEY
Content-Type: application/json

تعيد الطلبات بدون الترويسة الرمز HTTP 401 Unauthorized. وتعيد الطلبات من عنوان IP غير المدرَج في قائمتك الرمز HTTP 403 Forbidden. لا يُقبل سوى HTTPS.

3. تحقّق من مفتاحك

أبسط اختبار هو GET /api/access/me، الذي يعيد تفاصيل حسابك:

curl -X GET "https://public-api.foxreload.com/api/access/me" \
  -H "X-API-Key: YOUR_API_KEY"

يعيد الاستدعاء الناجح الرمز HTTP 200 مع:

{
  "email": "you@example.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "isActive": true,
  "isSuper": false
}

4. تصفّح الكتالوج

اسرد الفئات، ثم اسرد المنتجات داخل فئة. معرّف المنتج id هو الـ itemId الذي ستستخدمه عند إنشاء الطلبات.

# سرد الفئات
curl "https://public-api.foxreload.com/api/categories/?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

# سرد المنتجات داخل فئة (category_id_or_slug مطلوب)
curl "https://public-api.foxreload.com/api/products/?category_id_or_slug=gift-cards&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

لكل منتج في الاستجابة id وname وprice. المعرّف id (وهو TypeID مثل product_01k...) هو ما تمرّره كـ itemId عند إنشاء الطلب.

يمكنك أيضًا البحث:

curl "https://public-api.foxreload.com/api/products/search?query=Steam&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

5. أنشئ طلبًا اختباريًا

استخدم isMock: true لتلقّي أكواد وهمية دون إنفاق رصيد:

curl -X POST "https://public-api.foxreload.com/api/orders" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "product_01krgfgww8eth9xvvysd6y7r4j",
        "quantity": 1
      }
    ],
    "isMock": true
  }'

الاستجابة هي HTTP 201 مع كائن طلب. لاحظ حقل id.

6. استطلِع للحصول على النتائج

لا يرسل FoxReload أي webhooks. استطلِع GET /api/orders/{order_id} حتى تصبح الحالة completed:

curl "https://public-api.foxreload.com/api/orders/{order_id}" \
  -H "X-API-Key: YOUR_API_KEY"

عندما تكون status == "completed"، تحتوي كل مصفوفة items[].externalData على الأكواد المُسلَّمة. ينتهي الطلب الملغى أو الفاشل بالحالة status: "cancelled" أو status: "failed".

7. حدود المعدّل والأخطاء

تعيد واجهة الـ API الرمز HTTP 429 عند تجاوز حد المعدّل. طبّق تراجعًا أُسّيًا (ابدأ عند 500 مللي ثانية، ضاعف في كل محاولة، وأضف تشويشًا) ولا تُعِد المحاولة أبدًا على أخطاء 4xx خلاف 429. بالنسبة لمهلات POST /api/orders، تحقّق من حالة الطلب عبر GET /api/orders/{id} قبل إعادة المحاولة — إذ لا توجد مفاتيح idempotency، فإعادة المحاولة تُنشئ طلبًا جديدًا.

هل أنت جاهز لربط هذا بمنظومتك؟ مفاتيح الـ API مجانية مع حساب FoxReload — اطلب الوصول عبر foxreload.com وابدأ شراء السلع الرقمية بهوامش الجملة هذا الأسبوع.