فحص المدخل العام
إعلان قدرات Facilitator:facilitator وsupportedKinds ونقاط نهاية البروتوكول، فهذا يشير إلى أن بيانات تعريف القدرات سليمة. تم إيقاف اكتشاف موارد API؛ يُرجى استدعاء API المستهدف مباشرةً، والاعتماد على استجابة 402 الفورية.
القدرات المدعومة من Facilitator:
kinds، فهذا يشير إلى أن مدخل Facilitator يعمل بشكل سليم.
فحص accepts الخاص بـ 402
أرسل طلبًا غير موثّق لا يترتب عليه رسوم:
accepts المعادة تتضمن الشبكة التي تريد استخدامها. network هو معرّف CAIP-2:
eip155:8453+exact(Base)eip155:8453+upto(Base، قياس لاحق)solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp+exact(Solana)
تشغيل أدوات التحقق المتقدمة لـ X402Client
يوفر مستودع X402Client أدوات تحقق متقدمة يمكن استخدامها للتأكد من اختيار استجابة 402، وإنشاء التوقيع، وpaid retry، والتسوية على السلسلة. تتطلب هذه الأدوات محفظة ممولة وRPC ومفتاحًا خاصًا وتبعيات تطوير. بالنسبة للتكاملات التجارية العادية، يُوصى بإعطاء الأولوية لاستخدام SDK الخاص بـ TypeScript أو Python؛ ولا تشغّل هذه الأدوات إلا عند الحاجة إلى تحديد مشكلات التوقيع أو التسوية على السلسلة. عنوان المستودع: https://github.com/AceDataCloud/X402Client- استجابة 402 للطلب الأول.
- payment requirement المحدد.
- ملخص
PAYMENT-SIGNATUREبعد التوقيع. - حالة HTTP ونص الاستجابة بعد إعادة المحاولة.
- settlement transaction على السلسلة، أو سبب خطأ Facilitator عند الفشل.
PAYMENT-SIGNATURE الكامل إلى نظام السجلات أو التذاكر.
مثال على نتائج التحقق من API العام:
- أكملت كل من Base
exactوSolanaexactوBaseuptoعملية paid retry من HTTP 402 إلى HTTP 200. - يمكن التحقق من المعاملة على السلسلة لـ Base
exactفي BaseScan، ومبلغ التسوية هو95215atomic USDC. - الحد الأعلى للتوقيع في Base
uptoهو95215atomic USDC، لكن settlement الفعلي على السلسلة هو3atomic USDC، مما يشير إلى أن القياس اللاحق يخصم الرسوم حسب الاستخدام الفعلي. - تم تأكيد paid retry وإخراج النموذج لمسار Solana. قد يطبق RPC العام تحديدًا للمعدل؛ عند الحاجة إلى مطابقة صارمة على السلسلة، يُرجى استخدام Solana RPC خاص بك أو سجلات التسوية من جهة المنصة لتأكيد توقيع المعاملة.
اختبار SDK السريع
تُستخدم أدوات التحقق المتقدمة لفحص التوقيع والتسوية على السلسلة. ينبغي لجهة الأعمال أيضًا تنفيذ اختبار SDK سريع للتأكد من أن كود التطبيق يمكنه معالجة 402 تلقائيًا من خلال payment handler. فيما يلي لا تُعرض سوى المقاطع الأساسية، ويجب استكمال المحفظة وprovider وimport في الكود الكامل. TypeScript:exact، مع التسوية بالمبلغ الثابت المعروض في عرض سعر 402. تعد إكمالات المحادثة سيناريو يُقاس بحسب token، ويوصى عند التكامل الرسمي بتمرير preferScheme: 'upto' (وفي Python يكون prefer_scheme="upto") للتسوية حسب الاستخدام الفعلي.
كائن الإرجاع لـ Python SDK هو dict، ويمكن استخدام res["choices"][0]["message"]["content"] لقراءة المحتوى.
E2E لدفع الطلبات
يستخدم دفع الطلبات API المنصة الخاص بـplatform.acedata.cloud، ويتطلب رمز حساب المنصة. السلسلة الكاملة هي: إنشاء طلب Pending، ثم يقوم POST /api/v1/orders/{order_id}/pay/ بتشغيل 402، ثم إعادة المحاولة مع PAYMENT-SIGNATURE.
مثال على نتائج التحقق من دفع طلب صغير:
سجلات المعاملات التالية هي عينات اختبار تاريخية فعلية ضمن السياسة القديمة، وقد تم الاحتفاظ بالمبالغ وتجزئات المعاملات كما هي. لم تعد طلبات X402 الجديدة تتضمن خصومات على طريقة الدفع؛ يُرجى اعتماد amount في استجابة 402 لهذه المرة كأساس للتوقيع والدفع.
- بعد إنشاء الطلب، تكون حالة الطلب
Pending، والسعر هو1.26. - يعيد طلب
pay/الأول HTTP 402، ويوجد فيacceptsكل من BaseexactوSolanaexact، والمبالغ كلها1200000atomic USDC. - بعد إعادة المحاولة باستخدام Base
PAYMENT-SIGNATURE، يعيد HTTP 200، وتتغير حالة الطلب إلىFinished، ويكونpay_wayهوX402. - بعد فك ترميز
PAYMENT-RESPONSE، يظهرsuccess=Trueوnetwork=base، ويُعطى نفس هاش المعاملة. - حالة المعاملة على BaseScan هي
1، ومبلغ التحويل هو1200000atomic USDC، أي1.2USDC. - تم دفع سعر الإنشاء
1.26خلال فترة سياسة خصم الدفع القديمة لـ X402، وكان مبلغ التوقيع والتسوية النهائي هو1.2USDC.
Authorization: Bearer {platform_token}، أو إذا لم يكن الطلب تابعًا للحساب الحالي، فسيفشل في طبقة صلاحيات المنصة؛ وهذا يختلف عن واجهة X402 API بلا حساب عند استدعاء x402.acedata.cloud مباشرةً.
الأخطاء الشائعة
قائمة التحقق لـ Base upto
يُوفر upto حاليًا على Base فقط (eip155:8453). نظرًا لأن توقيع upto يربط المزيد من معلمات EVM typed data، ينبغي عند التكامل التأكد بشكل خاص من أن الحقول الفورية في استجابة 402 تتطابق تمامًا مع توقيع العميل.
upto القيمة invalid_upto_evm_payload_invalid_signature، فتحقق بالأولوية من:
extra.chainId(ينبغي أن يكون8453) في بندeip155:8453+uptoالذي أعادته API.extra.facilitatorAddressالذي أعادته API.- عنوان Base
uptofacilitator الذي يعيدهhttps://facilitator.acedata.cloud/supported. - Permit2 domain، وspender، وعقد USDC، وحساب التوقيع.
- ما إذا كانت المحفظة قد نفذت بالفعل approve Permit2 لـ Base USDC.
upto في الوقت نفسه Permit2 domain، ومعرّف السلسلة، وspender، وعنوان المستلم، وعنوان facilitator، وvalidAfter. إذا لم يتطابق أي بند، فسيستعيد Facilitator signer خاطئًا، ومن ثم يعيد invalid signature. إذا كانت هذه كلها متطابقة لكنه لا يزال يعيد 402، فتحقق في الخطوة التالية من Permit2 allowance؛ وعند عدم وجود تفويض يعيد PERMIT2_ALLOWANCE_REQUIRED.
حفظ معلومات التحقق
يجب أن تحفظ عملية تحقق كاملة واحدة على الأقل:- API path وملخص نص الطلب؛
- network وscheme المختاران؛
maxAmountRequired؛- عنوان محفظة payer؛
- حالة HTTP النهائية؛
- مخرجات النموذج أو معرّف المهمة في الاستجابة؛
- رابط settlement transaction؛
- Gateway trace ID أو معرّف سجل استخدام المنصة.
PAYMENT-SIGNATURE الكامل، أو EIP-712 signature الكامل، أو العبارة الاستذكارية.
أخطاء الدفع المنظمة
سيعيد فشل X402 بعد التوقيعcode ثابتًا، ومعلمات إدراج آمنة، ومرحلة، وعلامة إمكانية إعادة المحاولة في extensions.acedatacloud.paymentError. استخدم هذه البنية بالأولوية للتحقق، ولا تحلل error الإنجليزي في المستوى الأعلى، ولا تطلب من المستخدم تقديم توقيع المحفظة أو النص الأصلي للمحاكاة على السلسلة.
charged: false: تم رفض التحقق بوضوح قبل التسوية، ولم يتم بدء أي خصم هذه المرة.- بدون
charged: النتيجة غير معروفة أو دخلت بالفعل مرحلة التسوية، تحقق أولًا من الطلب وحالة السلسلة، ويُمنع تكرار الدفع مباشرةً. settlement_pending: لا تكرر الدفع مؤقتًا، حدّث الطلب أولًا أو تواصل مع الدعم.- code غير معروف: تعامل معه على أنه
payment_failed، واحتفظ بالرمز التقني العام ليتمكن دعم العملاء من البحث.

