كيف تربط واجهة API لمورّد السلع الرقمية

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

البنية — ثلاث طبقات لا اثنتان

الشكل الوحيد الذي يصمد في الإنتاج هو:

واجهة المورّد ← طبقتك الوسيطة ← المتجر.

الطبقة الوسيطة هي خدمتك الخاصة (أو مجموعة مهام خلفية ونقاط نهاية داخلية) تحتفظ بمفتاح المورّد، وتحفظ نسخة محلية من الكتالوج، وتنشئ الطلبات، وتستطلع حالتها، ولا تسلّم المتجر سوى بيانات موحّدة الشكل.

ثلاثة أمور ممنوعة تماماً:

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

الخطوة 1. المفاتيح والبيئات

أول ما تحصل عليه هو المفتاح. حدّد ثلاث حقائق عنه قبل كتابة أي شيفرة:

1. أي ترويسة مصادقة. قد تكون X-API-Key، وقد تكون Authorization: Bearer، وقد تكون توقيعاً للطلب. يستخدم FoxReload الترويسة X-API-Key: YOUR_API_KEY — بلا رموز Bearer ولا OAuth ولا زوج client_id/client_secret.
2. هل يمكن استرجاع المفتاح لاحقاً. لدى أغلب المورّدين، لا. يعرض FoxReload المفتاح مرة واحدة فقط، لذا ينتقل مباشرة إلى مدير أسرار (Vault أو AWS Secrets Manager أو Doppler) لا إلى ملف .env في المستودع.
3. هل توجد قائمة IP مسموح بها. إن وُجدت فعّلها. يمكن تقييد مفتاح FoxReload بعنوان IP أو نطاق CIDR بحد أقصى عشرة مدخلات؛ والطلب من عنوان غير مدرج يعيد HTTP 403، وهي نتيجة أفضل بكثير من مفتاح مسرَّب يعمل من أي مكان.

مسألة بيئة الاختبار

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

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

الخطوة 2. مزامنة الكتالوج والأسعار

الكتالوج مهمة خلفية لا طلباً عند الحاجة.

curl "https://public-api.foxreload.com/api/categories/?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

ثم اسحب المنتجات لكل فئة:

curl "https://public-api.foxreload.com/api/products/?category_id_or_slug=gift-cards&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

يحمل كل منتج الحقول id وname وprice. والحقل id هو ما ستمرّره لاحقاً بوصفه itemId عند إنشاء الطلب، فاحفظه في جدولك مفتاحاً خارجياً للمورّد.

قواعد عملية للمزامنة:

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

الخطوة 3. فحص الرصيد

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

ما ينبغي بناؤه:

• اقرأ الرصيد قبل إنشاء الطلب متى كان المبلغ معتبراً.
• شغّل مراقبة خلفية للرصيد بعتبتين — تحذير وحرج — مع تنبيه إلى قناة يقرأها أحدهم فعلاً في الثالثة فجراً.
• عالج خطأ نقص الرصيد بشكل صحيح. في FoxReload يظهر باسم BalanceNotEnough، والشحن يتم عبر POST /api/topups/crypto/. اسأل مورّدك عن وسائل الشحن المتاحة ومدة القيد، فهذا الرقم يحدّد مباشرة حجم السيولة التي عليك الاحتفاظ بها.

فكّر في الجانب المواجه للعميل أيضاً. إذا نفد رصيدك فلا يصح أن يرى المشتري خطأ 500، بل رفضاً واضحاً — والأفضل ألا يتمكن أصلاً من إتمام شراء صنف لا تستطيع توفيره الآن.

الخطوة 4. إنشاء الطلب

الطلب طلب POST يحمل مصفوفة بنود:

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": false
  }'

الاستجابة كائن طلب يحمل id وprice وstatus وcreatedAt وpaymentExpiresAt ومصفوفة items[].

تنبيه ضروري حول عدم التأثير التكراري

بعض الواجهات تقبل ترويسة Idempotency-Key كي لا يؤدي إعادة إرسال الطلب نفسه إلى إنشاء طلب ثانٍ. تحقق بنفسك مما إذا كان مورّدك يطبّق ذلك فعلاً — فكثيرون لا يفعلون. أما FoxReload فلا يدعم ترويسة Idempotency-Key.

وحين لا يوجد دعم، تبني الحماية من التكرار بنفسك:

1. ولّد مفتاح عملية فريداً لديك واحفظه في قاعدة بياناتك قبل استدعاء المورّد.
2. عند خطأ شبكي أو انتهاء مهلة، لا تعِد إنشاء الطلب على العمياء — اطلب أولاً قائمة الطلبات من المورّد وتحقق مما إذا كان قد أُنشئ فعلاً.
3. ولا تعِد المحاولة إلا بعد التأكد من عدم وجوده.

انتهاء المهلة عند الإنشاء غموض لا فشل. واعتباره فشلاً وإعادة المحاولة فوراً هو أغلى طريقة لتعلّم الفرق.

الخطوة 5. جلب الحالة — الاستطلاع كآلية أساسية

الاستطلاع هو الآلية التي تعمل دائماً. أما الويب هوك فميزة إضافية اختيارية.

تحقق مما إذا كان مورّدك يوفّر الويب هوك وما إذا كان يوقّعه (بـ HMAC أو غيرها). فإن وفّره فعامله مسرِّعاً، مع إبقاء الاستطلاع شبكة أمان، لأن التسليم غير مضمون أبداً وقد تكون نقطتك معطّلة في اللحظة الخاطئة تماماً. أما FoxReload فلا يوفّر ويب هوك إطلاقاً، وتُجلب نتائج الطلبات بالاستطلاع وحده.

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

جدول استطلاع عملي:

تنتقل طلبات FoxReload من active إلى paid إلى processing إلى completed، مع فرعين نهائيين هما cancelled (ومعه cancelReason) وfailed (وفيه خطأ لكل بند في items[].error). وعند completed تكون الأكواد في items[].externalData. الشرح الكامل للحالات في مقال مسار الطلب.

الخطوة 6. معالجة الأخطاء

قسّم الأخطاء إلى ثلاث فئات وتعامل مع كل منها على حدة:

• لا تعِد المحاولة أبداً. الأكواد HTTP 400 و401 و403 و404 خطؤك أنت أو خطأ في الإعداد. إعادة الإرسال ستعيد الجواب نفسه. سجّل وحقّق.
• أعِد المحاولة مع تراجع تدريجي. الكود HTTP 429 (حد المعدّل) والأكواد 5xx. تراجع أسّي مع تشويش عشوائي، وعدد محاولات محدود، وسقف للفاصل الزمني.
• تحقق قبل إعادة المحاولة. مهلات الشبكة على العمليات التي تغيّر الحالة. اعرف أولاً ما جرى عند المورّد، ثم تصرّف.

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

الخطوة 7. قائمة التحقق قبل الإطلاق

• المفتاح في مدير أسرار، وغائب عن git، وتاريخ المستودع فُحص.
• قائمة الـ IP المسموح بها مفعّلة إن كان المورّد يدعمها.
• طلبات تجريبية (أو اختبارية) نُفّذت على كل نوع منتج تبيعه.
• مزامنة الكتالوج مجدولة ولا تمسح البيانات عند استجابة ناقصة.
• الرصيد مراقَب بعتبتَي تنبيه.
• إنشاء الطلب محميّ من التكرار من جهتك.
• للاستطلاع مهلة قصوى وطابور للطلبات المعلّقة مع تنبيه.
• إعادة المحاولة تعمل فقط على 429 و5xx.
• كل طلب ورد من المورّد مسجّل مقابل معرّف الطلب الداخلي لديك — وهذا دليلك عند أي نزاع.
• يوجد دليل تشغيل يدوي: ماذا يفعل المشغّل حين يعلق طلب والعميل قد راسل الدعم بالفعل.

من أين تجلب البضاعة

يستحق بناء طبقة التكامل مرة واحدة، وأمام كتالوج واسع يغطي معظم تشكيلتك. FoxReload مورّد جملة للسلع الرقمية بأكثر من 900 صنف — مفاتيح ألعاب، بطاقات هدايا، شحن حسابات الألعاب، شرائح eSIM، ورخص برمجيات — كلها خلف واجهة REST واحدة مع تسليم آلي وأصناف متعددة المناطق. مفتاح واحد وبنية استجابة واحدة ونموذج طلب واحد للتشكيلة كلها، بدل خمسة تكاملات أمام خمس آليات مصادقة مختلفة.

اقرأ أيضاً

• البداية السريعة مع واجهة FoxReload لعام 2026
• شرح مسار الطلب
• الاستطلاع بدل الويب هوك
• إطلاق متجر سلع رقمية على واجهة API
• واجهة بطاقات الهدايا — جلب الكود والتسليم الآلي