البدء كمطوّر

أنشئ تطبيقًا داخل التطبيق المصغّر، وانسخ رمز API مرة واحدة، وابدأ استدعاء الواجهة. وكل الإعداد يجري في المزيد ← واجهة التجار.

خطوات البدء

1. افتح المزيد ← واجهة التجار.
2. أدخل اسم التطبيق (مثلًا «متجري»)، ورابط الويب هوك إن شئت.
3. اضغط إنشاء تطبيق.
4. انسخ رمز API فورًا. فهو يُعرض مرة واحدة لا غير — ولا نحتفظ نحن إلا بهاشٍ له.
5. أرسل أول طلب لك، والرمز في الترويسة TgCryptoPay-API-Token.

أول استدعاء لك

وجّه عميلك إلى العنوان الأساسي https://crypto.tgpaybot.com/pay/api واستدعِ getMe للتأكد من أن الرمز يعمل. وتعيد getBalance أرصدة تطبيقك، و getCurrencies العملات التي تستطيع استعمالها.

طرق القراءة تُستدعى بـ GET. أما الطرق التي تحرّك الأموال — createInvoice و transfer و createCheck ونظائرها في الحذف — فهي بـ POST حصرًا، عن قصد: فالمبالغ ومفاتيح منع التكرار لا مكان لها في سجلات الوصول. ويمكن إرسال الوسائط في جسم JSON، أو بترميز form-urlencoded، أو في سلسلة الاستعلام.

إدارة التطبيق

تعرض بطاقة كل تطبيق في واجهة التجار معرّفه ورصيده، وتتيح لك:

• ضبط رابط الويب هوك أو تغييره ثم حفظه.
• اختيار أحداث ويب هوك إضافية — بعد ضبط رابط الويب هوك تظهر مفاتيح أحداث ويب هوك إضافية لتشترك بها في أنواع تتجاوز invoice_paid (راجع مرجع الويب هوك).
• إنشاء رموز محدودة الصلاحيات — رموز API إضافية تجدها تحت رموز محدودة الصلاحيات، كل رمز مقصور على ما تختاره من صلاحيات (راجع مرجع الواجهة).
• تدوير الرمز — يُصدر رمزًا جديدًا ويُبطل القديم في اللحظة نفسها. استعمله إذا تسرّب رمزك؛ ويُعرض الجديد مرة واحدة كما عند الإنشاء.
• حذف — يتوقف التطبيق عن المصادقة، ويبقى رصيده وسجل مدفوعاته كما هما. وحذف التطبيق لا يُضيّع أمواله أبدًا.

الويب هوك

إذا ضبطت رابط ويب هوك، فسنرسل إليه جسم JSON موقّعًا عبر POST:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

ويأتي التوقيع في الترويسة TgCryptoPay-API-Signature (ومعها Crypto-Pay-API-Signature كاسم بديل متوافق): HMAC-SHA256 على الجسم الخام، بمفتاح هو SHA-256 لرمز API لديك. تحقّق منه قبل أن تثق بشيء في الحمولة.

وتُعاد محاولات التسليم بفواصل تتضاعف على مدى فترة طويلة، ويبقى update_id نفسه عبر المحاولات — فاعتمد عليه في استبعاد المكرّر، واجعل معالجك يحتمل التكرار.

ويُسلَّم invoice_paid دائمًا. أما بقية الأنواع — الفواتير المنتهية والشيكات المستلَمة والاستردادات وأحداث الاشتراكات — فتشترك بها اختياريًا عبر مفاتيح أحداث ويب هوك إضافية. والقائمة الكاملة وأشكال الحمولات وجدول إعادة المحاولة في مرجع الويب هوك.

⚠️ احرس الرمز كما تحرس مفتاحًا خاصًا

فهو يخوّل صرف الأموال من رصيد تطبيقك. أبقِه على خادمك، ولا تضعه في تطبيق جوال ولا في حزمة واجهة أمامية ولا في ملف إعداد مرفوع إلى المستودع. وإن ساورك شك في تسربه فدوّره — فالتدوير فوري ولا يكلّف شيئًا. وأعطِ كل خادم قدر حاجته فقط: فالرمز المحدود بلا صلاحية payouts يستطيع إنشاء الفواتير، ولا يستطيع إخراج رصيدك أبدًا.