كيفية أتمتة تسليم الرموز الرقمية

إجابة موجزة

أتمتة تسليم الرموز الرقمية تعني استبدال المعالجة اليدوية للطلبات بمسار آلي — دفعة العميل تُطلق استدعاء API لمورّدك، فيعيد المورّد الرمز، ويسلّمه نظامك للعميل خلال ثوانٍ. المكوّنات الستة هي — مستمع حدث الدفع، واستدعاء طلب API للمورّد، وتحليل الرمز من الاستجابة، والتسليم للعميل (بريد/صفحة/رسالة)، ومعالجة الإتمام غير المتزامن (استطلاع GET /orders/{id} لـ FoxReload؛ أو webhooks إن دعمها مورّدك)، ومعالجة الأخطاء للطلبات الفاشلة. وتعالج الأتمتة الفعّالة عدداً غير محدود من الطلبات دون خطوات يدوية.

التعريف: التسليم الآلي للرموز الرقمية هو مسار تنفيذ يربط دفعة العميل بتسليم الرمز دون تدخّل بشري — باستخدام إنشاء الطلب عبر API وأحداث webhook وتوزيع الرموز برمجياً.

الخلاصة الرئيسية: التسليم اليدوي للرموز يفشل عند التوسّع — فهو يُدخل تأخيرات وأخطاء بشرية وأعباء دعم. الأتمتة تزيل الثلاثة جميعاً. ويمكن لمطوّر واحد بناء نظام يتعامل مع آلاف الطلبات اليومية بالجهد ذاته الذي تتطلّبه عشرة طلبات.

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

• المطوّرون الذين يبنون متاجر سلع رقمية ويحتاجون لتطبيق مسار التسليم
• مشغّلو المتاجر الذين يسلّمون الرموز يدوياً حالياً ويرغبون في الأتمتة
• مطوّرو بوتات Telegram الراغبون في تسليم آلي للشحن وبطاقات الهدايا

لماذا يفشل التسليم اليدوي عند التوسّع

عند 20 طلباً يومياً، يعمل اليدوي. وعند 200، يصبح عنق زجاجة. وعند 2,000، ينهار.

مسار التسليم الآلي

[العميل يدفع]
      │
      ▼
[webhook/callback بوّابة الدفع يُطلق]
      │
      ▼
[معالج الطلب — تحقّق من الدفع، ابنِ طلب الأمر]
      │
      ▼
[POST /api/orders/ إلى API المورّد]
      │
      ├─[نجاح]──▶ [تحليل الرمز من الاستجابة]
      │                      │
      │                      ▼
      │              [تسليم الرمز للعميل]
      │              (بريد / صفحة الطلب / رسالة البوت)
      │
      └─[خطأ]───▶ [سجّل الخطأ، نبّه العمليات، استردّ إن لزم]

المكوّن 1 — مستمع حدث الدفع

يبدأ مسار التنفيذ لديك عند تأكيد الدفع — لا عند بدئه.

القواعد:

• أطلق التنفيذ فقط عند حدث دفع مؤكّد (لا عند إنشاء الطلب)
• عالج التكرار — إذا أُطلق حدث الدفع نفسه مرّتين، فلا تنشئ طلبين
• تحقّق من أنّ مبلغ الدفع يطابق تكلفة المنتج المتوقّعة

ترسل معظم بوّابات الدفع (Stripe وPayPal وغيرها) حدث webhook عند تأكيد الدفع. اشترك في نوع الحدث الصحيح:

• Stripe — payment_intent.succeeded
• PayPal — PAYMENT.CAPTURE.COMPLETED

لا تُطلق أبداً استدعاء API للمورّد من جهة العميل (المتصفّح). افعل ذلك دائماً من خادمك.

المكوّن 2 — استدعاء طلب API للمورّد

بعد تأكيد الدفع، استدعِ نقطة نهاية إنشاء الطلب لدى المورّد:

POST https://public-api.foxreload.com/api/orders/
Content-Type: application/json
X-API-Key: {api_key}

{
  "items": [
    { "itemId": "product_01krgfgww8eth9xvvysd6y7r4j", "quantity": 1 }
  ]
}

تُوضع الطلبات بحسب itemId — معرّف المنتج من الكتالوج (GET /api/products/). لا تتضمّن واجهة API العامة عروضاً؛ فأنت تشتري المنتج مباشرةً. تعيد الاستجابة معرّف طلب id؛ خزّنه مقابل طلبك الخاص في قاعدة بياناتك — إذ لا يملك FoxReload حقل مرجع يوفّره العميل، لذا فإنّ المعرّف id المُعاد هو مفتاح المطابقة لديك، والقيمة التي تستطلع بها عبر GET /api/orders/{order_id}.

ما يجب فعله عند الاستجابة:

المكوّن 3 — تحليل الرمز

تحتوي استجابة API عادةً على الرمز بصيغة منظّمة. حلّله وتحقّق منه قبل التسليم:

{
  "order_id": "SUP-99887",
  "status": "completed",
  "items": [
    {
      "code": "XXXXX-YYYYY-ZZZZZ",
      "pin": null,
      "instructions": "Redeem at store.steampowered.com"
    }
  ]
}

تحقّق من:

• أنّ status هي completed (لا pending أو failed)
• أنّ حقل code ليس فارغاً أو null
• إذا كان المنتج يتطلّب رمز PIN، فإنّ حقل pin ليس null

بالنسبة لمنتجات الشحن، قد تحتوي الاستجابة على تأكيد تسليم بدلاً من رمز.

المكوّن 4 — التسليم للعميل

سلّم الرمز عبر القناة التي يستخدمها عملاؤك:

أرفق دائماً مع الرمز:

• الرمز نفسه (بصيغة سهلة النسخ)
• اسم المنتج والفئة
• تعليمات التفعيل أو الرابط
• جهة اتصال الدعم لديك

المكوّن 5 — معالجة إتمام الطلب غير المتزامن

بالنسبة للطلبات التي لا تُنفّذ فوراً (الحالة pending)، تحتاج إلى طريقة لاكتشاف اكتمال التنفيذ. وتعتمد آلية ذلك على مورّدك:

• FoxReload — لا توجد webhooks — استطلع GET /api/orders/{order_id} وفق جدول حتى تصبح الحالة نهائية.
• مورّدون آخرون — قد يقدّمون webhooks — يستقبل خادمك طلب POST عند تغيّر حالة الطلب.

إذا كان مورّدك يدعم webhooks فعلاً، فمتطلّبات المعالج هي:

متطلّبات معالج webhook:

1. اقبل طلب POST من عنوان IP/نطاق المورّد
2. تحقّق من توقيع webhook (HMAC أو ما شابه)
3. أعد HTTP 200 خلال 5 ثوانٍ
4. ضع الحدث في طابور للمعالجة غير المتزامنة
5. عالج — إذا كانت الحالة = completed ← سلّم الرمز للعميل

لا تفعل:

• معالجة منطق العمل داخل معالج webhook المتزامن
• إعادة استجابة غير 200 إلّا إذا أردت أن يعيد المورّد المحاولة
• افتراض أنّ ترتيب webhook يطابق ترتيب إنشاء الطلبات

المكوّن 6 — معالجة الأخطاء

تتطلّب مسارات الأخطاء قدراً من التصميم يماثل المسار الناجح.

المراقبة والتنبيه

أعدّ المراقبة على:

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

• تطبيق معالج webhook تأكيد الدفع واختباره
• منطق التكرار — الأحداث المكرّرة لا تنشئ طلبات مكرّرة
• تطبيق استدعاء طلب API المورّد مع ترويسة المصادقة
• معالجة جميع حالات الاستجابة — completed وpending وfailed
• تحليل الرمز يتحقّق من أنّ حقل الرمز غير فارغ
• تطبيق التسليم للعميل لقناتك الأساسية
• التسليم يتضمّن الرمز + اسم المنتج + تعليمات التفعيل + جهة اتصال الدعم
• تطبيق معالجة الإتمام غير المتزامن — حلقة استطلاع لـ FoxReload (GET /api/orders/{id})؛ ومستمع webhook إن دعم مورّدك ذلك
• مراقبة الطلبات المعلّقة — نبّه إذا علقت بعد اتفاقية مستوى الخدمة
• تسجيل الأخطاء مع التنبيه
• مراقبة الرصيد مع تنبيه انخفاضه
• اختبار الحمل عند حجم الذروة المتوقّع