- وثيقة نظرة عامة على x402: https://docs.cdp.coinbase.com/x402/docs/overview
- أمثلة مفتوحة المصدر على x402: https://github.com/coinbase/x402
- يتم إكمال رابط الدفع على شبكة Base الرئيسية، وتستخدم الأصول USDC؛
- يجب استخدام المفتاح الخاص EVM لمحفظة العملات لإنشاء رأس توقيع
X-PAYMENT؛ - جميع واجهات برمجة التطبيقات موجودة تحت اسم النطاق
https://platform.acedata.cloud، ويجب أن يتضمن رأسAuthorizationرمز المنصة.
أولاً، التحضيرات
1. عرض الطلب وتسجيل معلومات الدفع
قم بتسجيل الدخول إلى وحدة التحكم https://platform.acedata.cloud، في قائمة الطلبات أو صفحة تفاصيل الطلب يمكنك رؤية الطلبات التي تحتاج إلى دفع. ستظهر تفاصيل الطلب:- معرف الطلب (مثل
7744945e-5e77-4dcc-a9c4-528692d17b34)؛ - عنوان الدفع
pay_to(سيتم إرجاعه أيضًا في استجابة 402، يُنصح بالاعتماد على معلومات الصفحة).
pay_to، حيث يجب ضمان إرسال الأموال إلى هذا العنوان عند التوقيع لاحقًا.
2. إعداد محفظة الدفع والأموال
- قم بإعداد محفظة EVM تدعم شبكة Base الرئيسية، وقم بتصدير المفتاح الخاص الذي سيتم استخدامه؛
- قم بشحن شبكة Base الرئيسية بمبلغ كافٍ من USDC (وحدة مبلغ الدفع هي 6 أرقام عشرية كحد أدنى)؛
- سيتولى x402 Facilitator دفع رسوم الشبكة، ويجب أن تحتفظ محفظة الدفع بمبلغ كافٍ من USDC؛
- يُستخدم المفتاح الخاص فقط للتوقيع المحلي، يرجى الحفاظ عليه بشكل آمن، وتجنب الكشف عنه في المتصفح أو في بيئات غير موثوقة.
3. إنشاء رمز المنصة
يستخدم رمز المنصة لاستدعاء واجهات برمجة التطبيقات الخاصة بالمنصة، ويعمل بشكل مشابه لرمز المستخدم الذي يتم استخدامه بعد تسجيل الدخول في المتصفح، ولكنه لا ينتهي صلاحيته. يرجى اتباع الخطوات التالية لإنشائه:- افتح صفحة وحدة التحكم https://platform.acedata.cloud/console/platform-tokens؛
- انقر على “إنشاء رمز”، واملأ معلومات الملاحظات حسب التعليمات ثم قم بإنشائه؛
- انسخ الرمز الذي تم إنشاؤه (مثل
platform-v1-xxxx)، واحفظه بشكل آمن كـplatform_token.
يجب أن يتضمن رأس جميع استدعاءات واجهة برمجة التطبيقات اللاحقة:
4. طلب المعلومات الأساسية
- اسم النطاق الأساسي لواجهة برمجة التطبيقات:
https://platform.acedata.cloud - مسار طلب الدفع:
/api/v1/orders/{order_id}/pay/ - يتم استخدام JSON لكل من الطلب والاستجابة، والترميز هو UTF-8.
ثانياً، نظرة عامة على عملية الدفع
- بدء طلب الدفع: طلب
POSTأولي بدون رأسX-PAYMENT، مما يؤدي إلى استجابة 402 Payment Required من المنصة؛ - قراءة متطلبات الدفع: تحليل مصفوفة
acceptsفي استجابة 402، تأكيد أنnetworkهوbase، وassetهو USDC، وpayToيتطابق مع صفحة الطلب؛ - إنشاء
X-PAYMENT: استخدام المفتاح الخاص لمحفظة الدفع، ومتطلبات جسم الاستجابة، ومعلومات مجال EIP-712 التي تم إرجاعها من Facilitator لإنشاء التوقيع (عادةً ما يتم ذلك بمساعدة SDK الرسمي)؛ - إعادة المحاولة مع التوقيع: إضافة رأس
X-PAYMENTإلى طلب بنفس المسار، بعد التحقق الناجح من المنصة، يتم إرجاع 200؛ - تحليل النتيجة: قراءة رأس الاستجابة
X-PAYMENT-RESPONSE، يمكن الحصول على تجزئة المعاملة على السلسلة، ومبلغ الخصم الفعلي، وما إلى ذلك، لاستخدامه في التسوية.
ثالثاً، أمثلة على التكامل
1. الطلب الأول (تحفيز 402)
network: يجب أن يكونbase(شبكة Base الرئيسية)؛asset: عنوان عقد USDC على Base (مثال على عقد الشبكة الرئيسية الرسمي)؛maxAmountRequired: وحدة USDC المطلوبة للدفع (1 USDC = 1,000,000 وحدة ذرية)؛payTo: عنوان استلام المنصة، يجب أن يتطابق مع صفحة تفاصيل الطلب؛extra: معلومات مجال EIP-712 المطلوبة للتوقيع وما إلى ذلك.
2. إنشاء X-PAYMENT
الطريقة الشائعة هي استخدام SDK الرسمي (مثل x402-js، x402-fetch، x402.clients، إلخ):
- تحويل المفتاح الخاص لمحفظة الدفع إلى كائن حساب؛
- تسجيل بيانات
acceptsمن استجابة 402، واختيار خيار الدفع حيثnetwork == "base"؛ - استدعاء دالة التوقيع التي يوفرها SDK لإنشاء سلسلة
X-PAYMENTمشفرة بـ Base64 (لا حاجة للاتصال المباشر بـ facilitator من العميل؛ سيتولى backend للمنصة استدعاء facilitator لإكمال verify/settle)؛ - يُنصح بالتحقق مما إذا كان
maxAmountRequiredضمن النطاق المقبول، وإذا تجاوز ذلك، يُنصح المستخدم بإعادة الشحن.
extra.eip712 لبناء هيكل EIP-712 ثم إجراء التوقيع.
3. إعادة المحاولة مع التوقيع
رابعاً، أمثلة على التعليمات البرمجية متعددة اللغات
تُفترض الأمثلة التالية أنه تم حقنها من خلال متغيرات البيئة أو ملفات التكوين:ACE_PLATFORM_TOKEN:رمز المنصة؛ACE_X402_ORDER_ID:معرف الطلب؛ACE_X402_PRIVATE_KEY:المفتاح الخاص لمحفظة الدفع (مع بادئة0x).
1. Axios (TypeScript)
2. Fetch (JavaScript)
3. Python requests
4. Python httpx (غير متزامن)
المثال يعرض فقط الاستدعاءات الرئيسية، يرجى إضافة معالجة الاستثناءات، استراتيجيات إعادة المحاولة، السجلات والتحكم في الأمان في بيئة الإنتاج.
5. التحقق بعد نجاح الدفع
- التحقق من وحدة التحكم: زيارة صفحة تفاصيل الطلب
https://platform.acedata.cloud/console/orders/{order_id}، إذا كانت الصفحة تعرض “نجح الدفع” أو تغيرت حالة الطلب إلى مدفوعة/مكتملة، فهذا يعني أن التسوية على السلسلة قد اكتملت. - التحقق من API: استدعاء
GET https://platform.acedata.cloud/api/v1/orders/{order_id}/مع تضمينAuthorization: Bearer {platform_token}، تحقق من حقلstateفي الاستجابة (PAIDأوFINISHEDتعني نجاح الدفع). - رأس الإرجاع: قراءة
X-PAYMENT-RESPONSEفي استجابة نجاح الدفع، يمكن تحليلها للحصول على تجزئة المعاملة على السلسلة كإثبات نهائي؛ يُنصح بحفظ هذه المعلومات في سجلات النظام لتسهيل التسوية.
6. استكشاف الأخطاء الشائعة
- لا يزال يرجع 402: تأكد من أن عنوان الدفع لديه ما يكفي من USDC على شبكة Base، تحقق مما إذا كان
maxAmountRequiredيتجاوز رصيد المحفظة أو الحد المخصص. - فشل التوقيع: تأكد من أن المفتاح الخاص يحمل بادئة
0x؛ استخدم بدقةextra(مجال EIP-712) وpayToفي الاستجابة، لا تغير ترتيب الحقول. - عدم تطابق الشبكة: قد توجد متطلبات متعددة في
accepts، يرجى اختيار الخيار الذيnetwork === "base". - عدم وجود
X-PAYMENT-RESPONSE: يشير إلى أن الدفع لم يتم خصمه فعليًا، يمكنك إعادة المحاولة بناءً على الخطأ في جسم الاستجابة؛ إذا واجهت ازدحامًا على السلسلة، يرجى المحاولة لاحقًا. - رمز المنصة غير صالح: تأكد من أن الرمز لم يتم حذفه، ويبدأ بـ
platform-v1-؛ إذا كانت الواجهة ترجع 401، يمكنك إعادة إنشائه في وحدة التحكم.
7. المزيد من المساعدة
- الوثائق عبر الإنترنت والأسئلة الشائعة: “الوثائق” في شريط التنقل العلوي في وحدة التحكم.
- تقديم تذكرة ودعم العملاء: https://platform.acedata.cloud/support
- التواصل المجتمعي: Discord https://discord.gg/f9GRuKCmRc، X (Twitter) https://x.com/acedatacloud
- قنوات أخرى: البريد الإلكتروني
office@acedata.cloud،office@germey.tech؛ عنوان الشركة 651 N Broad St, Suite 201, Middletown, Delaware, USA؛ يرجى مراجعة صفحة الدعم للحصول على أحدث رمز QR لخدمة WeChat. - ملاحظات واقتراحات: نرحب بإخبارنا بمتطلبات التحسين من خلال أي من القنوات المذكورة أعلاه.

