Telegram Stars API للأعمال: بيع Stars وPremium
إذا كان لمنتجك عملاء، أو مسار لإتمام الدفع، أو جمهور على Telegram، فلست بحاجة إلى إنشاء عملية تنفيذ منفصلة لبيع منتجات Telegram الرقمية. تتيح MyStars Fulfilment API لخادومك الخلفي إنشاء طلبات Telegram Stars وTelegram Premium المرسلة إلى اسم مستخدم Telegram @username وتتبعها.
لذلك فهي مناسبة عمليًا للمتاجر التابعة للموزعين، وروبوتات Telegram وMini Apps، ومنصات صناع المحتوى، وخدمات الهدايا، وبرامج الولاء، والوكالات، والأسواق، والمنتجات التي تريد إضافة عملية شراء عبر Telegram من دون تمرير كل عميل عبر مسار دعم يدوي.
من ينبغي أن يستخدم Telegram Stars API؟
استخدم Telegram Stars API عندما تكون Stars أو Premium جزءًا من المنتج الذي تبيعه، لا عملية شراء يدوية لمرة واحدة لفريقك.
تشمل تطبيقات B2B الشائعة ما يلي:
- واجهات متاجر الموزعين التي تبيع حزم Stars أو مدد Premium إلى جانب منتجات رقمية أخرى؛
- روبوتات Telegram وMini Apps التي تجمع اسم المستخدم، وتعرض عرض السعر الحالي، وترسل الطلب إلى خادوم خلفي؛
- منصات صناع المحتوى والمجتمعات التي تساعد الجمهور على تعبئة الرصيد قبل منشور مدفوع أو إجراء في روبوت أو تجربة Premium؛
- منتجات الهدايا والولاء التي تحوّل مكافأة الحملة إلى Telegram Stars أو Premium لمستلم محدد بالاسم؛
- الوكالات والخدمات المُدارة التي تحتاج إلى مسار تنفيذ قابل للتكرار بدل معالجة كل طلب عميل يدويًا؛
- الأسواق التي تحتاج إلى سجل طلبات قابل للتدقيق وإشعار عند اكتمال التسليم.
واجهة API هي طبقة تنفيذ وليست أداة للواجهة الأمامية. يتولى منتجك تجربة العميل، وإتمام الدفع، والقواعد التجارية. ويستخدم خادومك MyStars لتقديم عرض السعر، والتحقق، وإنشاء طلب تنفيذ Telegram، وسداده، ومطابقته.
ما الذي يمكنك بيعه عبر MyStars API؟
يدعم الكتالوج الحالي نوعين من المنتجات:
- Telegram Stars — يستخدم الطلب كمية من Stars؛
- Telegram Premium — يستخدم الطلب مدة Premium بالأشهر.
تلبي Stars وPremium احتياجين مختلفين للمشتري، لذا اعرضهما بصورة منفصلة في واجهتك. Stars رصيد قابل للإنفاق داخل Telegram لصناع المحتوى والقنوات والروبوتات والمنتجات الرقمية. أما Premium فهي هدية اشتراك لحساب Telegram. إذا كان عميلك يقارن باقات Premium بدل دمج API، فوجهه إلى صفحة إتمام الدفع لـ Telegram Premium.
لا تضمن أحجام الحزم أو مدد الخطط أو العملات أو الأسعار مباشرةً في تطبيق العميل. تعرض وثائق MyStars API بيانات مباشرة عن المنتجات والعملات والأسعار لكي يتبع كتالوجك قواعد API الحالية.
كيفية بيع Telegram Stars عبر API: مسار تنفيذ B2B
يتبع التكامل الموثوق تسلسلًا قصيرًا لكنه مدروس. يُنشأ الطلب في خادومك الخلفي؛ ولا ينبغي للعميل أن يرى مفتاح API أو أن يتعامل مع تعليمات دفع على البلوكشين تخص خدمتك.
- حمّل الكتالوج الحالي وعملات الدفع. اقرأ المنتجات والعملات المتاحة عند بدء التكامل، وحدّثها وفق جدول مناسب. يمنع ذلك إصدارًا قديمًا من التطبيق من عرض خيار لم يعد متاحًا.
- اطلب عرض سعر مباشرًا. اطلب من نقطة نهاية التسعير عرضًا للمنتج المختار والكمية أو المدة وعملة الدفع. استخدم المبلغ المعاد باعتباره المبلغ الواجب سداده؛ ولا تنشئ سعرًا اعتمادًا على افتراضات أسعار مخزنة مؤقتًا.
- تحقق من المستلم قبل الخصم أو إنشاء الطلب. أرسل اسم مستخدم Telegram للمستلم
@usernameوالمنتج المختار إلى نقطة نهاية التحقق من المستلم. لا يمكن استبدال تحقق مستلم Stars بتحقق أهلية Premium أو العكس. - أنشئ طلبًا واحدًا قابلًا لإعادة الإرسال بأمان. أرسل المنتج المختار والمستلم وعملة الدفع وعنوان URL لاستدعاء راجع عند استخدام Webhooks ومفتاح
Idempotency-Keyثابتًا مولدًا من معرّف الطلب الداخلي لديك. - سدّد تعليمات الدفع المعادة كما هي. تتضمن استجابة الطلب عنوان الوجهة، والمبلغ، والمذكرة، والسلسلة، ووقت الانتهاء. يجب أن تستخدم خدمة الدفع هذه القيم كما هي، لا عنوان محفظة أو مذكرة مخزنة في إعدادات التطبيق.
- طابق حالة التسليم النهائية. استطلع نقطة نهاية حالة الطلب كخيار احتياطي، أو استقبل الحالة النهائية عبر Webhook. ولا تعتبر طلب العميل مكتملًا إلا بعد استيفاء قواعد المطابقة لديك.
هذا التسلسل هو ما يميز تكامل B2B لـ Telegram Stars API عن رابط شراء بسيط: إذ يمكن تخزين كل خطوة وإعادة محاولتها بأمان ومراقبتها ودعمها من فريق المنتج لديك.
البيانات التي ينبغي أن يحتفظ بها خادومك الخلفي
قاعدة بياناتك هي مصدر الحقيقة للطلب الذي يراه العميل. احتفظ بمعلومات كافية لشرح الطلب لفريق الدعم، وإعادة محاولة عملية آمنة، ومطابقة دفعة على البلوكشين من دون كشف أسرار.
احتفظ بالحد الأدنى مما يلي:
- معرّف الطلب الداخلي لديك ومعرّف طلب MyStars؛
- مفتاح عدم التكرار المستخدم لإنشاء ذلك الطلب؛
- نوع المنتج وكمية Stars أو مدة Premium واسم مستخدم المستلم؛
- العملة المسعّرة، والمبلغ، والسلسلة، ووقت الانتهاء، ومذكرة الدفع؛
- تجزئة معاملة البلوكشين بعد السداد؛
- حالة الدفع لديك، وحالة طلب MyStars، وبيانات Webhook أو طابعًا زمنيًا للاستطلاع، ونتيجة التنفيذ النهائية.
يُعد Idempotency-Key مهمًا لأن الأنظمة الحقيقية تعيد المحاولة. فمهلة الشبكة بعد POST /v1/orders ليست دليلًا على عدم حدوث شيء. وتسمح إعادة المحاولة بالمفتاح الثابت نفسه لخادومك الخلفي بالتعافي من دون إنشاء طلب تنفيذ ثانٍ لعملية شراء العميل نفسها.
Webhooks والاستطلاع ودورة حياة الطلب
قد يدفع العميل لمنتجك أولًا، ثم تسدّد خدمتك تعليمات MyStars لاحقًا. وينشئ ذلك ثلاث حالات تشغيلية ينبغي عدم الخلط بينها:
- دفع العميل مقابل منتج الخاص بك؛
- أرسلت خدمتك الدفعة على البلوكشين لطلب MyStars؛
- سلّمت MyStars Stars أو Premium إلى مستلم Telegram.
عند إنشاء الطلب، قد يُعاد بالحالة awaiting_payment مع قسم للدفع ووقت انتهاء. وعندما يتقدم السداد والتنفيذ، يحتاج نظامك إلى وسيلة موثوقة لتلقي النتيجة النهائية.
استخدم استدعاء Webhook راجعًا لتحديثات التسليم المعتادة، واحتفظ باستطلاع الحالة كمسار للتعافي. تحقق من أن طلبات Webhook الواردة يعالجها خادومك الخلفي، واربطها بمعرّف طلب MyStars، واجعل معالجة Webhook متكررة بأمان أيضًا. يجب ألا يؤدي استدعاء راجع مكرر إلى منح مكافأة مكررة أو إصدار إيصال ثانٍ أو بدء مسار استرداد ثانٍ.
تسوية الدفع: GRAM (TON) وUSDT على TON
يمكن تسوية طلبات MyStars API بعملة GRAM (TON) أو USDT (TON). وهذه عمليات دفع خلفية، وليست حقولًا ينبغي نسخها بلا تدقيق إلى مسار إتمام دفع على جانب العميل.
لكل طلب، اقرأ العملة والسلسلة والعنوان والمبلغ والمذكرة ووقت الانتهاء المعادة من استجابة API. لا تعِد استخدام تفاصيل الدفع لطلب سابق. فقد تفشل المطابقة عند الدفع بمبلغ أو تعليق أو شبكة غير صحيح، أو باستخدام تعليمات منتهية الصلاحية.
احتفظ بتوقيع المحفظة واستدعاءات API على جانب الخادوم فقط. ولا تضع X-Api-Key أو العبارة الأولية للمحفظة أو بيانات اعتماد التسوية المؤتمتة في حزمة متصفح أو Telegram Mini App أو مستودع عام أو سجل عميل.
لا KYC للمشتري: المعنى الدقيق في B2B
عبارة «لا KYC للمشتري» مصطلح بحث، لكنها تحتاج إلى صياغة دقيقة. في هذا المسار، لا تتطلب عملية إتمام الدفع لتنفيذ الطلب لدى MyStars من المشتري رفع مستندات هوية. وقد يقلل ذلك الاحتكاك في تجربة المنتج.
قائمة التحقق قبل الإطلاق لتكامل Telegram Stars API للموزعين
قبل إتاحة الميزة للعملاء، تحقق مما يلي:
- يُخزَّن مفتاح API في إدارة أسرار على جانب الخادوم فقط، ويمكن تدويره؛
- تأتي خيارات المنتجات والعملات من API المباشر، لا من قيم مكتوبة مباشرةً؛
- يجري التحقق من المستلم قبل إنشاء الطلب وقبل الخصم النهائي من العميل؛
- لكل طلب معرّف داخلي ثابت ومفتاح تكرار؛
- تستخدم الدفعة العنوان والمبلغ والمذكرة والسلسلة ووقت الانتهاء المعادة تحديدًا لذلك الطلب؛
- يُوسم USDT بعبارة TON فقط في كل موضع يظهر فيه؛
- تتحقق معالجة Webhook من الأحداث وتربطها وتسجلها وتزيل تكرارها بأمان؛
- يغطي الاستطلاع Webhook فائتًا أو متأخرًا؛
- يستطيع فريق الدعم العثور على الطلب بمعرّفك ومعرّف طلب MyStars والمستلم وتجزئة المعاملة؛
- تُحدد قواعد الاسترداد والاحتيال والامتثال والتواصل مع العملاء قبل الإطلاق.
لصيغ الطلبات وحقول الاستجابة وخيارات SDK وعقد API المباشر، استخدم وثائق MyStars API باعتبارها المصدر المرجعي للتنفيذ.
الأسئلة الشائعة
هل يمكنني بيع Telegram Stars عبر موقعي أو روبوتي أو Mini App؟
نعم. يمكن لمنتجك جمع اختيار العميل واسم مستخدم المستلم، بينما يستخدم خادومك الخلفي MyStars Fulfilment API لإنشاء طلب Stars وتتبع حالته. احتفظ بمفتاح API وعمليات التسوية على جانب الخادوم.
هل يمكنني بيع Telegram Premium عبر API نفسها؟
نعم. تدعم API تنفيذ Telegram Premium كنوع منتج مستقل بمدة Premium بالأشهر. تحقق من أهلية المستلم قبل إنشاء الطلب، لأن قيود هدايا Premium قد تختلف عن عمليات التحقق من مستلمي Stars.
هل توفر API قائمة أسعار ثابتة لـ Stars وPremium؟
استخدم نقطة نهاية التسعير للحصول على عرض مباشر بدل الاعتماد على قائمة ثابتة. تمثل استجابة API المصدر المناسب للمبلغ الحالي وعملة التسوية للطلب المختار.
كيف أتجنب طلبات Telegram Stars المكررة؟
أنشئ كل طلب بمفتاح Idempotency-Key ثابت مرتبط بمعرّف الطلب الداخلي لديك. وإذا أعاد عامل في الخادوم المحاولة بسبب مهلة زمنية، فأعد استخدام المفتاح نفسه بدل إنشاء مفتاح جديد.
ما شبكة USDT المدعومة؟
USDT على TON / The Open Network فقط. لا ترسل USDT على شبكة أخرى ولا تعرضه على أنه طريقة تسوية متوافقة.
هل عدم طلب KYC من المشتري يعني أن شركتي بلا التزامات امتثال؟
لا. يصف ذلك تجربة المشتري عند إتمام الدفع عبر MyStars، لا المسؤوليات القانونية والمالية والمتعلقة بالاحتيال والضرائب والعقوبات وحماية المستهلك واسترداد الأموال المترتبة على شركتك.
ابدأ تكامل تنفيذ Telegram للأعمال
إذا كان منتجك يحتاج إلى بيع Telegram Stars أو Premium على نطاق واسع، فابنِه حول دورة حياة طلب قابلة للتحقق: عرض سعر مباشر، والتحقق من المستلم، وإنشاء طلب متكرر بأمان، وتسوية دقيقة على البلوكشين، ثم Webhook نهائي أو مطابقة للحالة.
افتح وثائق MyStars API وابدأ التكامل →
المصادر والأدلة
- MyStars FaaS — وثائق Fulfilment API: كتالوج المنتجات، والتسعير المباشر، والتحقق من المستلمين، وإنشاء الطلبات، ومصادقة API، وتعليمات التسوية، وتتبع الحالة، وWebhooks.