واجهة بطاقات الهدايا البرمجية للمتاجر الإلكترونية — كيف تعمل

الإجابة المختصرة

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

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

الخلاصة الأساسية — تزيل واجهة بطاقات الهدايا المدمَجة جيدًا أكبر أربعة اختناقات في إعادة بيع السلع الرقمية — إدارة المخزون اليدوية، وتأخّر تسليم الرمز، وأخطاء التسوية، وعبء دعم العملاء للرموز المفقودة. يُنجَز عمل التكامل مرة واحدة؛ أما الفائدة التشغيلية فدائمة.

لمن هذا الدليل

هذا الدليل موجّه لـ —

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

ما هي واجهة بطاقات الهدايا البرمجية

واجهة بطاقات الهدايا البرمجية هي مجموعة من نقاط نهاية HTTP تصل متجرك بنظام مخزون المورّد وتسعيره وتنفيذه. فبدلًا من شراء الرموز مسبقًا وتخزينها في جدول بيانات وإرسالها يدويًا بالبريد للعملاء، تتولّى API السلسلة كاملةً —

1. يقدّم العميل طلبًا في متجرك
2. يستدعي متجرك نقطة نهاية إنشاء الطلب لدى المورّد
3. يُعيد المورّد الرمز فورًا
4. يسلّم متجرك الرمز إلى العميل

تحدث العملية خلال ثوانٍ. ولا يعرف العميل الفرق بين رمز اشتريته مسبقًا وآخر سُلّم عبر استدعاء API.

البديل دون API

بدون تكامل API، يكون سير العمل اليدوي النموذجي —

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

ينجح هذا عند 10 طلبات يوميًا. ولا ينجح عند 500.

المزايا الأساسية في API وما تفعله

نظرة عامة على مزايا API

نقطة نهاية كتالوج المنتجات

تُعيد نقطة نهاية الكتالوج قائمة بالمنتجات المتاحة مع بيانات وصفية — اسم المنتج، والفئة، ومنطقة التفعيل، والعملة، وحالة التوفّر الحالية.

وبالنسبة للمتجر الإلكتروني، يشغّل هذا —

• استيراد المنتجات آليًا (بلا نسخ ولصق من جداول البيانات)
• مزامنة الكتالوج (تظهر المنتجات الجديدة تلقائيًا)
• التصفية الإقليمية (إظهار المنتجات ذات الصلة بعملائك فقط)

ما يجب التحقق منه —

• هل يتضمّن الكتالوج تسميات المنطقة لكل SKU؟
• هل الفئات مُدرجة بدقة (مثل $10 و$25 و$50 و$100)؟
• هل يُحدَّث الكتالوج في الوقت الفعلي أم وفق جدول؟

نقطة نهاية التحقق من المخزون

قبل قبول دفع العميل، ينبغي لمتجرك التحقق من توفّر المخزون لـ SKU المطلوب. ويُعيد استدعاء التحقق من المخزون ما إذا كانت الرموز متاحة وفي أي نطاق كمي.

بدون هذا التحقق —

• يدفع العميل
• يفشل استدعاء طلبك لأن SKU نفد من المخزون
• يجب عليك إصدار استرداد وشرح المشكلة للعميل

مع هذا التحقق —

• تُظهر صفحة منتجك حالة التوفّر الصحيحة
• يحجب سدادك شراء العناصر النافدة قبل تحصيل الدفع

نقطة نهاية السعر

تُعيد نقطة نهاية السعر تكلفة الجملة الحالية لكل SKU. ولأن أسعار المورّد قد تتغيّر — خاصةً للبطاقات الخاصة بمنطقة الخاضعة لتحرّكات الصرف — فإن الاستعلام عن السعر وقت الطلب (بدلًا من تخزينه مؤقتًا) يضمن دقة حساب هامشك.

نموذجان للتسعير —

نقطة نهاية إنشاء الطلب

هذا هو استدعاء API الأساسي. يقدّم متجرك طلبًا (SKU، الكمية، مرجع العميل) وتُعيد API بيانات التنفيذ — عادةً رمزًا أو أكثر، مع أي تعليمات تفعيل.

سير أساسي لإنشاء الطلب —

1. POST /api/orders/
   { "items": [{ "itemId": "product_01krgfgww8eth9xvvysd6y7r4j", "quantity": 1 }] }

2. تُعيد API:
   { "id": "order_01k...", "status": "completed",
     "items": [{ "externalData": ["XXXXX-YYYYY-ZZZZZ"] }] }

3. يسلّم متجرك الرمز إلى العميل

ما يجب التحقق منه في استجابة API —

• هل الحالة completed أم pending؟ تعني pending أن الرمز لم يُسلَّم بعد.
• هل صيغة الرمز صحيحة للمنتج (يتطلّب بعضها PIN منفصلًا)؟
• هل توجد رابط استرداد أو تعليمات مُضمَّنة؟

نقطة نهاية حالة الطلب

بالنسبة للطلبات التي لا تُنفَّذ فورًا (حالة المعالجة)، تتيح لك نقطة نهاية حالة الطلب التحقق متى يكتمل التنفيذ. وتُستخدَم لـ —

• رسائل "طلبك قيد المعالجة" المعروضة للعميل
• المراقبة الداخلية لاتفاقية مستوى خدمة التنفيذ
• التحقيق في تذاكر الدعم

الرصيد

يعمل حساب الموزّع لديك مع المورّد على رصيد مدفوع مسبقًا. ويُفرَض الرصيد وقت الطلب — لا يملك FoxReload نقطة نهاية GET /balance؛ وإذا كان رصيدك غير كافٍ، يُعيد POST /api/orders/ خطأ BalanceNotEnough. اشحن عبر POST /api/topups/crypto/. استخدم هذا لـ —

• مراقبة فشل الطلبات بحثًا عن أخطاء BalanceNotEnough وتنبيه العمليات استباقيًا
• إعداد تنبيهات آلية عند تكرار أخطاء الرصيد
• تضمين مراقبة الرصيد في لوحة عملياتك

طلب فاشل بسبب رصيد غير كافٍ يخلق تجربة عميل أسوأ من رسالة "نفاد المخزون" الواضحة.

تتبّع حالة الطلب (الاستطلاع أو Webhooks)

يتيح لك تتبّع حالة الطلب اكتشاف متى يكتمل التنفيذ وتسليم الرموز للعملاء. وتعتمد كيفية ذلك على مورّدك —

• FoxReload — يستخدم الاستطلاع فقط — استدعِ GET /api/orders/{order_id} على فترات حتى تكون status بحالة "completed" أو "cancelled" أو "failed". وعند الاكتمال، يحتوي items[].externalData على الرموز. ولا توجد webhooks ولا ترويسات توقيع ولا أحداث استدعاء.
• مورّدون آخرون — قد يرسلون إشعارات webhook دفعية إلى خادمك عند تغيّر حالة الطلب.

بالنسبة للمتاجر عالية الحجم التي تستخدم FoxReload، شغّل عامل استطلاع في الخلفية يفحص كل الطلبات المعلّقة وفق جدول ويشغّل تسليم الرمز عندما تبلغ الحالة "completed".

إذا كان مورّدك يدعم webhooks، يجب على خادمك —

• قبول طلب POST الخاص بـ webhook
• التحقق من التوقيع (يوقّع المورّد حمولات webhook)
• الاستجابة بـ HTTP 200 ضمن نافذة المهلة
• معالجة الحدث بشكل لامتزامن (لا تعالجه في معالِج webhook)

التسوية

يُعيد GET /api/orders/?statuses=completed&limit=200&offset=0 سجل طلباتك المكتملة مع الطوابع الزمنية ومعرّفات الطلبات والعناصر وحالة التسوية — رقّم الصفحات بـ offset لتغطية الفترة كاملةً. ويُستخدَم من قِبل —

• فرق المالية لتقارير التسوية الشهرية
• أنظمة المحاسبة لتوثيق الضرائب
• المدققين الذين يتحققون من سجلات المعاملات

كيف تتناسب API مع بنية متجرك

متصفح العميل
      │
      ▼
متجرك الإلكتروني
  ├── صفحة المنتج: تستدعي واجهة الكتالوج/المخزون لإظهار التوفّر
  ├── السداد: يستدعي واجهة المخزون للتأكيد قبل الدفع
  ├── الدفع: يعالج دفع العميل عبر بوابتك
  ├── معالِج الطلب: يستدعي واجهة إنشاء الطلب لدى المورّد
  ├── التنفيذ: يسلّم الرمز من استجابة API إلى العميل
  └── مستطلِع حالة الطلب: يستطلع GET /api/orders/{order_id} حتى الحالة النهائية (أو مستمع webhook إن دعمه المورّد)

واجهة FoxReload البرمجية ──────────────────────────────────────────
  ├── GET /api/categories/
  ├── GET /api/products/          (معرّف المنتج = itemId؛ السعر مُضمَّن)
  ├── GET /api/products/search
  ├── POST /api/orders/
  ├── GET /api/orders/{id}        (الرموز في items[].externalData عند الاكتمال)
  └── POST /api/topups/crypto/    (شحن الرصيد؛ لا توجد GET /balance)

نماذج التكامل

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

ما يجب التحقق منه قبل ربط واجهة مورّد

أخطاء تكامل شائعة

1. عدم التحقق من المخزون قبل قبول الدفع — يؤدي إلى طلبات فاشلة واحتكاك في الاسترداد

2. تخزين الأسعار مؤقتًا بإفراط — سعر مخزَّن في التاسعة صباحًا قد يكون خاطئًا في الثالثة عصرًا للمنتجات الحساسة للصرف

3. تجاهل التحقق من توقيع webhook — يمكن لأي أحد إرسال POST إلى نقطة نهاية webhook لديك إن لم تتحقق من التواقيع

4. معالجة webhooks بشكل متزامن — سيعيد منطق إعادة محاولة المورّد الإرسال إن انتهت مهلة خادمك؛ عالِج بشكل لامتزامن

5. عدم معالجة التنفيذ الجزئي — للطلبات متعددة الوحدات، قد تُنفَّذ بعض العناصر وتفشل أخرى؛ عالِج كل رمز باستقلالية

6. عدم مراقبة الرصيد — يؤدي الرصيد الصفري إلى فشل كل الطلبات حتى تشحن؛ اضبط تنبيهات

7. استخدام مرجع طلب واحد لعدة طلبات عملاء — استخدم دائمًا مراجع فريدة لكل طلب عميل للتسوية

قائمة تحقق التكامل

• اقرأ توثيق API كاملًا قبل كتابة أي شيفرة
• احصل على بيانات اعتماد API واختبر كل نقاط النهاية (استخدم isMock: true لطلبات اختبار FoxReload)
• نفّذ مزامنة كتالوج المنتجات (نقطة نهاية الكتالوج)
• نفّذ التحقق من المخزون في الوقت الفعلي قبل السداد
• نفّذ إنشاء الطلب مع معالجة الأخطاء
• عالِج كل حالات الطلب — completed وpending وfailed
• نفّذ تسليم الرمز إلى العميل (بريد، صفحة طلب، رسالة Telegram)
• نفّذ استطلاع حالة الطلب (أو مستمع webhook إن دعم مورّدك webhooks)
• للاستطلاع — استخدم عاملًا في الخلفية؛ لـ webhooks — عالِج الأحداث بشكل لامتزامن
• أعدّ مراقبة الرصيد مع تنبيهات
• اختبر مسارات الفشل باستخدام طلبات isMock: true
• نفّذ تصدير التسوية للمالية
• أعدّ تسجيل أخطاء API والتنبيه
• أجرِ اختبار حمل للتكامل عند حجم طلباتك المتوقع
• أطلق مع تفعيل المراقبة