الانتقال إلى المحتوى الرئيسي
يتضمن X402 بروتوكول HTTP وSDK والتوقيع وFacilitator والمعاملات على السلسلة. عند استكشاف مشكلات التوقيع أو التسوية وإصلاحها، يُوصى بالتأكد طبقةً بطبقة وفق الترتيب «المدخل العام -> استجابة 402 -> معالج دفع SDK -> التسوية على السلسلة». يوضح هذا الدليل طرق الفحص لكل طبقة، ويسرد الأخطاء الشائعة.

فحص المدخل العام

إعلان قدرات 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)
إذا لم تكن الشبكة المستهدفة موجودة، فهذا يشير إلى أن API هذا أو البيئة الحالية لا يملك طريقة تحصيل X402 المقابلة مهيأة.

تشغيل أدوات التحقق المتقدمة لـ X402Client

يوفر مستودع X402Client أدوات تحقق متقدمة يمكن استخدامها للتأكد من اختيار استجابة 402، وإنشاء التوقيع، وpaid retry، والتسوية على السلسلة. تتطلب هذه الأدوات محفظة ممولة وRPC ومفتاحًا خاصًا وتبعيات تطوير. بالنسبة للتكاملات التجارية العادية، يُوصى بإعطاء الأولوية لاستخدام SDK الخاص بـ TypeScript أو Python؛ ولا تشغّل هذه الأدوات إلا عند الحاجة إلى تحديد مشكلات التوقيع أو التسوية على السلسلة. عنوان المستودع: https://github.com/AceDataCloud/X402Client
Base:
Solana:
تطبع أدوات التحقق عادةً:
  1. استجابة 402 للطلب الأول.
  2. payment requirement المحدد.
  3. ملخص PAYMENT-SIGNATURE بعد التوقيع.
  4. حالة HTTP ونص الاستجابة بعد إعادة المحاولة.
  5. settlement transaction على السلسلة، أو سبب خطأ Facilitator عند الفشل.
لا ترسل المفتاح الخاص أو PAYMENT-SIGNATURE الكامل إلى نظام السجلات أو التذاكر. مثال على نتائج التحقق من API العام:
توضيح:
  • أكملت كل من Base exact وSolana exact وBase upto عملية paid retry من HTTP 402 إلى HTTP 200.
  • يمكن التحقق من المعاملة على السلسلة لـ Base exact في BaseScan، ومبلغ التسوية هو 95215 atomic USDC.
  • الحد الأعلى للتوقيع في Base upto هو 95215 atomic USDC، لكن settlement الفعلي على السلسلة هو 3 atomic USDC، مما يشير إلى أن القياس اللاحق يخصم الرسوم حسب الاستخدام الفعلي.
  • تم تأكيد paid retry وإخراج النموذج لمسار Solana. قد يطبق RPC العام تحديدًا للمعدل؛ عند الحاجة إلى مطابقة صارمة على السلسلة، يُرجى استخدام Solana RPC خاص بك أو سجلات التسوية من جهة المنصة لتأكيد توقيع المعاملة.

اختبار SDK السريع

تُستخدم أدوات التحقق المتقدمة لفحص التوقيع والتسوية على السلسلة. ينبغي لجهة الأعمال أيضًا تنفيذ اختبار SDK سريع للتأكد من أن كود التطبيق يمكنه معالجة 402 تلقائيًا من خلال payment handler. فيما يلي لا تُعرض سوى المقاطع الأساسية، ويجب استكمال المحفظة وprovider وimport في الكود الكامل. TypeScript:
Python:
إذا أعاد النموذج السلسلة الثابتة كما هو مطلوب، فهذا يشير إلى أن SDK وpayment handler وGateway وFacilitator وAPI المستهدف متصلة معًا. يستخدم اختبارا smoke test أعلاه Base 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 كل من Base exact وSolana exact، والمبالغ كلها 1200000 atomic USDC.
  • بعد إعادة المحاولة باستخدام Base PAYMENT-SIGNATURE، يعيد HTTP 200، وتتغير حالة الطلب إلى Finished، ويكون pay_way هو X402.
  • بعد فك ترميز PAYMENT-RESPONSE، يظهر success=True وnetwork=base، ويُعطى نفس هاش المعاملة.
  • حالة المعاملة على BaseScan هي 1، ومبلغ التحويل هو 1200000 atomic USDC، أي 1.2 USDC.
  • تم دفع سعر الإنشاء 1.26 خلال فترة سياسة خصم الدفع القديمة لـ X402، وكان مبلغ التوقيع والتسوية النهائي هو 1.2 USDC.
إذا لم يكن دفع الطلب يتضمن Authorization: Bearer {platform_token}، أو إذا لم يكن الطلب تابعًا للحساب الحالي، فسيفشل في طبقة صلاحيات المنصة؛ وهذا يختلف عن واجهة X402 API بلا حساب عند استدعاء x402.acedata.cloud مباشرةً.

الأخطاء الشائعة

قائمة التحقق لـ Base upto

يُوفر upto حاليًا على Base فقط (eip155:8453). نظرًا لأن توقيع upto يربط المزيد من معلمات EVM typed data، ينبغي عند التكامل التأكد بشكل خاص من أن الحقول الفورية في استجابة 402 تتطابق تمامًا مع توقيع العميل.
إذا أعاد Base upto القيمة invalid_upto_evm_payload_invalid_signature، فتحقق بالأولوية من:
  1. extra.chainId (ينبغي أن يكون 8453) في بند eip155:8453 + upto الذي أعادته API.
  2. extra.facilitatorAddress الذي أعادته API.
  3. عنوان Base upto facilitator الذي يعيده https://facilitator.acedata.cloud/supported.
  4. Permit2 domain، وspender، وعقد USDC، وحساب التوقيع.
  5. ما إذا كانت المحفظة قد نفذت بالفعل approve Permit2 لـ Base USDC.
يربط digest توقيع 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، واحتفظ بالرمز التقني العام ليتمكن دعم العملاء من البحث.