دليل · PayStars

PayStars API للمطورين: المسار الكامل لبيع Stars وPremium في بوتك

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

تاريخ النشر: · تاريخ التحديث:

PayStars API للمطورين: المسار الكامل لبيع Stars وPremium في بوتك

هل تريد بيع 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 نفسه دائمًا.

قبل الإطلاق

  1. احتفظ بمفتاح API في متغير بيئة على الخادم، وليس في الشيفرة.
  2. نفّذ المسار كاملًا بطلب حقيقي صغير قدره 50 Stars.
  3. اعرض على العملاء 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%).

ابدأ الآن