اربط بوتك بخدماتنا في دقائق
شحن نجوم وبريميوم تيليجرام، اشتراكات البرامج، وأرقام التفعيل. الدفع من رصيدك المسبق عندنا، والنتيجة توصلك في الرد أو على الـ webhook.
البداية
المصادقة
كل طلب لازم يحمل مفتاحك في الهيدر. المفتاح بتستلمه مرة واحدة من الإدارة، فاحفظه في متغير بيئة ولا تحطه في كود الواجهة أو في مستودع عام.
Authorization: Bearer tge_live_xxxxxxxxxxxxxxxx
بديل مقبول: X-API-Key: tge_live_...
منع تكرار الخصم (Idempotency-Key)
كل طلب شراء (POST .../orders) لازم يحمل هيدر Idempotency-Key فريد من 8 إلى 64 حرف، مثل UUID. لو الشبكة قطعت وأعدت نفس الطلب بنفس المفتاح، هترجع لك نفس النتيجة بدون خصم تاني. استخدام نفس المفتاح مع طلب مختلف يرجع 409 idempotency_conflict.
دورة حياة الطلب
| الحالة | المعنى | الإجراء |
|---|---|---|
completed | تم التنفيذ والتسليم | لا شيء |
processing | الطلب اتحجز وبيتنفذ (أرقام واشتراكات) | انتظر الـ webhook أو اسأل عن الطلب كل 5–10 ثواني |
failed | فشل، وتم رد المبلغ كاملًا لرصيدك | صحّح المدخلات وأعد بمفتاح جديد |
under_review | الرد من المزوّد لم يكن واضحًا (مثلًا انتهت المهلة). المبلغ محجوز لحد ما نراجع | لا تعد الطلب بمفتاح جديد. هتوصلك النتيجة على الـ webhook |
نجوم وبريميوم بيرجعوا 201 وcompleted في نفس الرد. الأرقام والاشتراكات بترجع 202 وprocessing.
completed وفيه result.code وresult.password. لو الكود ما وصلش، مفيش إلغاء يدوي؛ الطلب بيتفشل ويتردّ تلقائيًا لو المزوّد ألغاه.حدود الاستخدام
الافتراضي 60 طلب في الدقيقة لكل مفتاح. عند التجاوز: 429 rate_limited مع هيدر Retry-After. الأسعار بالدولار الأمريكي كنصوص عشرية (مثل "0.9") عشان تتجنب أخطاء الفاصلة العائمة.
Webhooks
اضبط رابطك بـ PUT /v1/webhook (HTTPS فقط، ولا يقبل عناوين داخلية). هنرسل POST بصيغة JSON عند كل تغيّر نهائي للطلب:
| الحدث | متى |
|---|---|
order.completed | اكتمل التسليم |
order.failed | فشل الطلب وتم الرد |
order.under_review | الطلب اتحجز للمراجعة أو اتأخر |
webhook.test | من POST /v1/webhook/test |
{
"id": "evt_3b9f0c1d2a4e5f6a7b8c",
"type": "order.completed",
"created": 1792000000,
"data": { "order": { "id": "ord_...", "status": "completed", "client_ref": "order-1042", "result": { ... } } }
}
التحقق من التوقيع
كل إرسال بيحمل X-TgElon-Signature: t=الوقت,v1=التوقيع. التوقيع هو HMAC-SHA256 بالـ secret بتاعك على النص {t}.{الجسم الخام}. تحقق منه دائمًا، وارفض أي إرسال أقدم من 5 دقائق. ردّ بـ 2xx خلال 10 ثواني، وإلا هنعيد المحاولة بعد 30 ثانية، 2 دقيقة، 10 دقائق، ساعة، 6 ساعات ثم 24 ساعة. قد يصلك نفس الحدث أكثر من مرة، فتعامل مع id الحدث كمفتاح لمنع التكرار.
الأخطاء
كل خطأ بيرجع بنفس الشكل، وrequest_id هو اللي تبعته للدعم:
{ "error": { "code": "insufficient_balance", "message": "رصيدك غير كافٍ", "request_id": "req_a1b2c3d4e5f6", "balance": "0.5", "required": "0.9" } }
| HTTP | الكود | المعنى |
|---|---|---|
| 400 | idempotency_key_required | هيدر Idempotency-Key مفقود أو غير صالح |
| 401 | unauthorized | مفتاح مفقود أو خطأ |
| 402 | insufficient_balance | رصيدك لا يكفي (balance وrequired في الرد) |
| 403 | account_disabled / ip_not_allowed | الحساب موقوف أو الـ IP خارج القائمة المسموحة |
| 404 | not_found / product_not_found / country_not_found | غير موجود |
| 409 | out_of_stock / idempotency_conflict | نفد المخزون، أو مفتاح تكرار مستخدم لطلب مختلف |
| 422 | invalid_request / invalid_username / invalid_duration / provider_rejected | مدخلات غير صالحة أو رفضها المزوّد (تم الرد) |
| 429 | rate_limited | انتظر Retry-After ثانية |
| 502 / 503 | provider_failed / service_unavailable | الخدمة متوقفة مؤقتًا، تم الرد، أعد المحاولة لاحقًا |
5xx وانتهاء المهلة عندك: أعد الطلب بنفس Idempotency-Key. مش هيتخصم مرتين.