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

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

تعمل واجهة API لبطاقات الهدايا داخل بوت تيليجرام تمامًا كما تعمل في متجر إلكتروني — الفارق هو قناة التسليم فقط. يستقبل البوت اختيار المنتج والدفع، يستدعي نقطة إنشاء الطلب لدى المورّد، يستلم الكود ويرسله للمستخدم في المحادثة. لا حاجة لأي واجهة ويب. خطوات التطبيق الأساسية هي — قائمة المنتجات، مُحفّز الدفع، استدعاء الـ API، تسليم الكود عبر sendMessage، ومعالجة الأخطاء.

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

الخلاصة الأساسية: واجهة API لبطاقات الهدايا مستقلّة عن القناة. سواء استدعيتها من خادم متجر إلكتروني أو من خادم بوت تيليجرام، فلا فرق بالنسبة للـ API. التطبيق الوحيد الخاص بالبوت هو استبدال التسليم عبر البريد أو صفحة الطلب باستدعاء bot.sendMessage().

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

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

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

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

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

/start
  → Bot: "Select a product category"
      [Gaming] [Retail] [Mobile]

[Gaming]
  → Bot: "Select a product"
      [Steam $10] [Steam $20] [PSN $10] [Xbox $15]

[Steam $20]
  → Bot: "Steam $20 (US) — $21.99. Pay now?"
      [Pay with Stars] [Pay with Crypto]

[Pay with Stars — Telegram payment]
  → Telegram native payment flow
  → On successful_payment event:
      Bot calls supplier API: POST /api/orders/ { "items": [{ "itemId": "product_01k...", "quantity": 1 }] }
      Polls GET /api/orders/{order_id} until status=="completed"; code in items[].externalData
      Bot.sendMessage: "Your Steam code: XXXXX-YYYYY-ZZZZZ
                        Redeem at: store.steampowered.com"

تكامل الدفع لبوتات بطاقات الهدايا

ملاحظة بشأن Telegram Stars: يقتطع تيليجرام نحو 30% من مدفوعات Stars. لمنتج بقيمة 10$، يكون إيرادك الفعلي من دفعة Stars نحو 7$. يتطلّب هذا سعر تجزئة أعلى أو خصم جملة أعلى للحفاظ على الهامش. اعمل النمذجة بعناية قبل تفعيل Stars كطريقة الدفع الوحيدة لديك.

صيغة رسالة تسليم الكود

عند إرسال الكود إلى المستخدم، أدرِج دائمًا:

✅ Order complete

Product: Steam Gift Card $20 (US Region)
Code: XXXXX-YYYYY-ZZZZZ

Redeem at: store.steampowered.com/account/redeemwalletcode
Region: US Steam accounts only

Need help? /support

نسّق الكود في كتلة أحادية المسافة ليسهل نسخه:

`XXXXX-YYYYY-ZZZZZ`

يعرض تيليجرام النص بين العلامتين الماثلتين (backticks) بخط أحادي المسافة، وهو مريح للنسخ على الجوال.

معالجة الأخطاء

لا ترسل أبدًا كودًا فارغًا أو نائبًا (placeholder) إلى المستخدم. إذا أعاد الـ API خطأ، عالِجه بسلاسة.

تسجيل الطلبات

لكل طلب بطاقة هدية مكتمل في بوتك، سجّل:

• معرّف مستخدم تيليجرام (وليس اسم المستخدم — المعرّفات ثابتة بينما أسماء المستخدمين قد تتغيّر)
• رمز المنتج SKU
• معرّف الطلب لدى المورّد
• الكود (مُجزّأ hashed، وليس نصًا صريحًا في قاعدة بياناتك)
• الطابع الزمني
• معرّف تأكيد الدفع

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

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

• إعداد كتالوج المنتجات في البوت (مع تسمية صريحة للمنطقة)
• دمج طريقة الدفع واختبارها
• معالِج حدث الدفع — تشغيل استدعاء الـ API فقط عند تأكيد الدفع
• استدعاء إنشاء الطلب عبر API المورّد مع معالجة الأخطاء
• تسليم الكود عبر sendMessage مع تعليمات كاملة
• الكود بصيغة أحادية المسافة لتسهيل النسخ
• أمر /support مع معلومات التواصل
• تسجيل المعاملات لكل طلب
• مراقبة الرصيد مع تنبيه
• إبلاغ سياسة الاسترداد (/terms أو في رسالة /start)