PayStars API للمطورين: المسار الكامل لبيع Stars وPremium في بوتك
كيف يعمل PayStars REST API من البداية إلى النهاية: X-API-Key، والتحقق من اسم المستخدم، وعروض أسعار USD مع max_usd، والطلبات المتماثلة، وخطأ 409 price_changed والتحقق من TxId، كخطة تكامل.
تاريخ النشر: · تاريخ التحديث:

هل تريد بيع Telegram Stars وPremium داخل بوتك أو متجرك أو تطبيقك؟ يمنحك PayStars API واجهة HTTPS واحدة ورصيد USD مشتركًا مع الموقع. بدلًا من تكرار مرجع API، يوضح هذا المقال كيفية بناء التكامل من البداية إلى النهاية.
نظرة سريعة على البنية
يقوم نظامك بثلاثة أمور: يموّل الرصيد بـ USDT، ويطلب السعر، وينشئ طلبًا. أما كل ما عدا ذلك، بما في ذلك التسليم عبر مسار الشراء الرسمي في Telegram، فيتم من جانب PayStars.
| الجزء | ما يفعله |
|---|---|
| الوصول | ترويسة X-API-Key؛ تُنشأ المفاتيح في لوحة التحكم |
| الرصيد | USD، يُشحن بـ USDT (TON أو BEP20 أو TRC20) |
| السعر | سعر Fragment × 1.05، مع التقريب إلى الأعلى لأقرب سنت |
| الحد | 10 طلبات في الثانية لكل مفتاح |
| الشفافية | TxId عام لكل طلب مكتمل |
المرحلة 1: تمويل الرصيد
يعيد POST /usd/invoice مع مبلغ وسلسلة ("ton" أو "bsc" أو "trc20") مبلغًا دقيقًا صالحًا لمدة 30 دقيقة. الحد الأدنى هو 0.1 USDT.
المرحلة 2: التحقق من المستلم
يتحقق POST /api/v1/check-username من المستلم ويعيد رمز تحقق قصير الأجل. يمنع ذلك الدفع إلى أسماء مستخدمين غير موجودة: إذا أخطأ العميل في الكتابة، تكتشف ذلك قبل خصم أي شيء.
المرحلة 3: الحصول على السعر وتحديد سقفه
يعيد POST /api/v1/usd/quote السعر الحالي (usd) والهامش (markup_percent: 5). يتبع السعر السوق، لذا:
- اطلب عرض سعر جديد قبل كل طلب؛
- مرّر max_usd مساويًا للمبلغ المعروض؛
- أرسل دائمًا currency: "USD"، وإلا يُستخدم التفضيل المحفوظ للحساب.
المرحلة 4: إنشاء الطلب
POST /api/v1/stars/buy أو /api/v1/premium/buy. يجب أن يحمل كل طلب Idempotency-Key، فإذا انقطع الاتصال وأعدت المحاولة، لن يُخصم منك مرتين. خزّن المفتاح إلى جانب معرّف الطلب في قاعدة بياناتك.
المرحلة 5: تتبّع الحالة
يمنحك GET /api/v1/order/{id} و/api/v1/orders الحالات والسجل. تُسلَّم معظم الطلبات خلال دقائق. يحصل الطلب المكتمل على TxId يمكنك أنت وعميلك التحقق منه في السجل العام لـ PayStars.
التعامل مع الأخطاء بشكل صحيح
- يعني 409 price_changed أن السعر تجاوز max_usd ولم يُخصم شيء. احصل على عرض سعر جديد واعرض على العميل السعر المحدَّث.
- حد المعدل: لا تتجاوز 10 طلبات في الثانية؛ أضف طابور انتظار أو تراجعًا تدريجيًا.
- إعادة المحاولة: أعد استخدام Idempotency-Key نفسه دائمًا.
قبل الإطلاق
- احتفظ بمفتاح API في متغير بيئة على الخادم، وليس في الشيفرة.
- نفّذ المسار كاملًا بطلب حقيقي صغير قدره 50 Stars.
- اعرض على العملاء TxId الخاص بهم، فهذا يبني الثقة.
الوثائق الكاملة والبدايات السريعة: PayStars Stars API وتسعير USD لـ API. للمدفوعات داخل البوت، انظر السلع الرقمية في البوتات تُدفع بـ Stars فقط.
الأسئلة الشائعة
هل توجد بيئة اختبار؟
لا توجد بيئة اختبار منفصلة؛ اختبر بطلبات حقيقية صغيرة (50 Stars) أثناء التكامل.
ما لغات البرمجة التي تعمل؟
أي لغة يمكنها إرسال طلبات HTTPS. تتوفر بدايات سريعة لـ Python وNode.js وPHP.
كيف أموّل الرصيد؟
باستخدام USDT على TON أو BEP20 أو TRC20، بحد أدنى 0.1 USDT؛ ولكل فاتورة مبلغ دقيق صالح لمدة 30 دقيقة.
المصادر
اشترِ Stars وPremium بالدولار الأمريكي (USDT)
عبر مفتاح API: سعر Fragment، 0% (الموقع: 5%).
More news
Telegram Stars وPremium في أوزبكستان: الدفع بالبطاقة أو بـ USDTشراء Telegram Stars أو Premium في أوزبكستان: Uzcard وHumo عبر @StarKerakBot، وUSDT على paystars.uz/uz/، ومسارات التطبيق الرسمي والقواعد المحلية التي ينبغي معرفتها.اقرأ →
كيفية مكافأة الفائزين في المسابقات بـ Telegram Stars أو Premium: دليل المنظمتسليم Telegram Stars أو Premium للفائزين في اختبارك أو مسابقتك أو ماراثونك البرمجي: الميزانية، وجمع @usernames، والتسليم عبر PayStars، وتقرير المتابعة.اقرأ →
الأسئلة الشائعة في PayStars: أسئلة شائعة حول تسجيل الدخول وشحن USDT وطلبات Stars وPremiumأكثر أسئلة PayStars شيوعًا في صفحة واحدة: تسجيل الدخول عبر Telegram، والشحن بـ USDT (TON أو BEP20 أو TRC20)، وطلب Stars وPremium، وأوقات التسليم، والأمان وAPI.اقرأ →