البدء كمطوّر

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

خطوات البدء

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

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

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

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

الشبكة التجريبية

ابنِ تكاملك على الشبكة التجريبية أولًا — الواجهة نفسها، والتطبيق المصغّر نفسه، وعملات تجريبية بلا قيمة حقيقية:

	الشبكة الرئيسية	الشبكة التجريبية
البوت	@tgpaycryptobot	@tgpaycrypto_testnet_bot
العنوان الأساسي للواجهة	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
خادم MCP	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

والتطبيقات والرموز منفصلة: فرمز الشبكة التجريبية لا يعمل على الشبكة الرئيسية، والعكس صحيح. وللحصول على العملات التجريبية افتح التطبيق المصغّر للشبكة التجريبية واضغط الحصول على عملات تجريبية في الشاشة الرئيسية. تُضاف حزمة تجريبية كإيداعات عادية، مع تجاوز العملات على الشبكات المعطّلة. يعرض التطبيق ما أُضيف ومتى يمكنك الطلب مجددًا. يمكنك استخدام حساب تيليجرام ثانٍ كعميل يدفع فواتيرك التجريبية.

تستخدم الإيداعات والسحوبات محاكاة لحفظ الأموال، دون معاملات بلوكشين حقيقية. لا ترسل أموالًا حقيقية إلى عنوان إيداع تجريبي. قواعد الواجهة مشتركة، لكن الميزات والأسعار والحدود المتاحة قد تختلف عن الشبكة الرئيسية. عندما تنتهي، أنشئ تطبيق إنتاج في @tgpaycryptobot وغيّر العنوان الأساسي.

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

افتح تطبيقًا في واجهة التجار لترى معرّفه ورصيده. ومن هناك يمكنك:

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

الويب هوك

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

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

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

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

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

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

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