الانتقال إلى المحتوى الرئيسي
x402 هو بروتوكول دفع على السلسلة يعتمد على معيار HTTP 402 Payment Required، مما يسمح للجهات المستدعية بإجراء التسوية على السلسلة أثناء تقديم طلب API، وهو مثالي لسيناريوهات الفوترة حسب الطلب بين البرامج الآلية، ووكيل الذكاء الاصطناعي، والخدمات الصغيرة. من خلال هذا الدليل، يمكنك إتمام دفع طلبات AceDataCloud برمجيًا في نظامك، مما يحقق تجربة “طلب وادفع”. المراجع الرسمية: تستهدف هذه الوثيقة المطورين الذين يحتاجون إلى دمج قدرة الدفع x402 من منصة AceDataCloud في أعمالهم، وتقدم العملية الكاملة من إعداد البيئة إلى إتمام استدعاء الدفع، مع توفير أمثلة على Axios وFetch وPython requests وhttpx. النقاط الأساسية:
  • يتم إكمال رابط الدفع على شبكة 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. إنشاء رمز المنصة

يستخدم رمز المنصة لاستدعاء واجهات برمجة التطبيقات الخاصة بالمنصة، ويعمل بشكل مشابه لرمز المستخدم الذي يتم استخدامه بعد تسجيل الدخول في المتصفح، ولكنه لا ينتهي صلاحيته. يرجى اتباع الخطوات التالية لإنشائه:
  1. افتح صفحة وحدة التحكم https://platform.acedata.cloud/console/platform-tokens؛
  2. انقر على “إنشاء رمز”، واملأ معلومات الملاحظات حسب التعليمات ثم قم بإنشائه؛
  3. انسخ الرمز الذي تم إنشاؤه (مثل platform-v1-xxxx)، واحفظه بشكل آمن كـ platform_token.
platform-token يجب أن يتضمن رأس جميع استدعاءات واجهة برمجة التطبيقات اللاحقة:
Authorization: Bearer {platform_token}

4. طلب المعلومات الأساسية

  • اسم النطاق الأساسي لواجهة برمجة التطبيقات: https://platform.acedata.cloud
  • مسار طلب الدفع: /api/v1/orders/{order_id}/pay/
  • يتم استخدام JSON لكل من الطلب والاستجابة، والترميز هو UTF-8.

ثانياً، نظرة عامة على عملية الدفع

  1. بدء طلب الدفع: طلب POST أولي بدون رأس X-PAYMENT، مما يؤدي إلى استجابة 402 Payment Required من المنصة؛
  2. قراءة متطلبات الدفع: تحليل مصفوفة accepts في استجابة 402، تأكيد أن network هو base، وasset هو USDC، وpayTo يتطابق مع صفحة الطلب؛
  3. إنشاء X-PAYMENT: استخدام المفتاح الخاص لمحفظة الدفع، ومتطلبات جسم الاستجابة، ومعلومات مجال EIP-712 التي تم إرجاعها من Facilitator لإنشاء التوقيع (عادةً ما يتم ذلك بمساعدة SDK الرسمي)؛
  4. إعادة المحاولة مع التوقيع: إضافة رأس X-PAYMENT إلى طلب بنفس المسار، بعد التحقق الناجح من المنصة، يتم إرجاع 200؛
  5. تحليل النتيجة: قراءة رأس الاستجابة X-PAYMENT-RESPONSE، يمكن الحصول على تجزئة المعاملة على السلسلة، ومبلغ الخصم الفعلي، وما إلى ذلك، لاستخدامه في التسوية.

ثالثاً، أمثلة على التكامل

1. الطلب الأول (تحفيز 402)

POST https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json

{
  "pay_way": "X402"
}
استجابة 402 نموذجية (قد يختلف ترتيب الحقول قليلاً):
{
  "error": "Payment required for this order.",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54b268aa0e",
      "maxAmountRequired": "1250000",
      "payTo": "0x302afdd980aaefca3afa8df7222a6002774f6724",
      "extra": {
        "eip712": { "...": "..." }
      }
    }
  ],
  "paywall": { ... }
}
شرح الحقول الرئيسية:
  • 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، إلخ):
  1. تحويل المفتاح الخاص لمحفظة الدفع إلى كائن حساب؛
  2. تسجيل بيانات accepts من استجابة 402، واختيار خيار الدفع حيث network == "base"؛
  3. استدعاء دالة التوقيع التي يوفرها SDK لإنشاء سلسلة X-PAYMENT مشفرة بـ Base64 (لا حاجة للاتصال المباشر بـ facilitator من العميل؛ سيتولى backend للمنصة استدعاء facilitator لإكمال verify/settle)؛
  4. يُنصح بالتحقق مما إذا كان maxAmountRequired ضمن النطاق المقبول، وإذا تجاوز ذلك، يُنصح المستخدم بإعادة الشحن.
إذا كنت بحاجة إلى تنفيذ يدوي، يرجى الرجوع إلى الوثائق الرسمية لـ x402، وفقًا لمعلومات المجال المقدمة في extra.eip712 لبناء هيكل EIP-712 ثم إجراء التوقيع.

3. إعادة المحاولة مع التوقيع

POST https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/
Authorization: Bearer {platform_token}
Content-Type: application/json
X-PAYMENT: {base64_signed_payload}

{
  "pay_way": "X402"
}
إذا كانت عملية الدفع ناجحة، سيكون حالة الاستجابة 200، وستعود جسم الاستجابة بمعلومات الطلب المحدثة، مع إرفاق:
X-PAYMENT-RESPONSE: eyJ0cmFuc2FjdGlvbiI6IjB4...==
يمكن استخدام دالة فك التشفير من SDK للحصول على تجزئة المعاملة على السلسلة، وشبكة الدفع، وعنوان الدافع، وما إلى ذلك، لاستخدامها في المحاسبة أو العرض.

رابعاً، أمثلة على التعليمات البرمجية متعددة اللغات

تُفترض الأمثلة التالية أنه تم حقنها من خلال متغيرات البيئة أو ملفات التكوين:
  • ACE_PLATFORM_TOKEN:رمز المنصة؛
  • ACE_X402_ORDER_ID:معرف الطلب؛
  • ACE_X402_PRIVATE_KEY:المفتاح الخاص لمحفظة الدفع (مع بادئة 0x).

1. Axios (TypeScript)

import axios from "axios";
import { Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { buildPaymentHeader, decodePaymentResponse } from "x402-js";

const baseURL = "https://platform.acedata.cloud";
const orderId = process.env.ACE_X402_ORDER_ID!;
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const privateKey = process.env.ACE_X402_PRIVATE_KEY as Hex;

const account = privateKeyToAccount(privateKey);
const api = axios.create({
  baseURL,
  headers: {
    Authorization: `Bearer ${platformToken}`,
    "Content-Type": "application/json",
  },
});

async function payOrder() {
  const payPath = `/api/v1/orders/${orderId}/pay/`;

  const initial = await api.post(
    payPath,
    { pay_way: "X402" },
    { validateStatus: () => true }
  );
  if (initial.status !== 402) {
    throw new Error(`حالة غير متوقعة ${initial.status}`);
  }

  const requirement = initial.data.accepts.find(
    (item: any) => item.network === "base"
  );
  if (!requirement) {
    throw new Error("لم يتم إرجاع متطلبات أساسية");
  }

  const paymentHeader = await buildPaymentHeader({
    account,
    requirement,
  });

  const final = await api.post(
    payPath,
    { pay_way: "X402" },
    { headers: { "X-PAYMENT": paymentHeader } }
  );

  if (final.status >= 400) {
    throw new Error(`فشل الدفع x402: ${final.status} ${final.statusText}`);
  }
  const receipt = decodePaymentResponse(final.headers["x-payment-response"]);
  console.log("إيصال x402", receipt);
}

payOrder().catch(console.error);

2. Fetch (JavaScript)

import { wrapFetchWithPayment, decodePaymentResponse } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.ACE_X402_PRIVATE_KEY!);
const platformToken = process.env.ACE_PLATFORM_TOKEN!;
const orderId = process.env.ACE_X402_ORDER_ID!;
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

async function payOrder() {
  const url = `https://platform.acedata.cloud/api/v1/orders/${orderId}/pay/`;

  const response = await fetchWithPayment(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${platformToken}`,
    },
    body: JSON.stringify({ pay_way: "X402" }),
  });

  if (!response.ok) {
    const errorBody = await response.text();
    throw new Error(`فشل الدفع x402: ${response.status} ${errorBody}`);
  }

  const receipt = decodePaymentResponse(
    response.headers.get("x-payment-response")!
  );
  console.log("إيصال x402", receipt);
}

payOrder().catch(console.error);

3. Python requests

import os
from eth_account import Account
from x402.clients.requests import x402_requests
from x402.clients.base import decode_x_payment_response

order_id = os.environ["ACE_X402_ORDER_ID"]
platform_token = os.environ["ACE_PLATFORM_TOKEN"]
account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

session = x402_requests(
    account,
    payment_requirements_selector=lambda accepts, **_: next(
        req for req in accepts if req.network == "base" and req.scheme == "exact"
    ),
)

response = session.post(
    f"https://platform.acedata.cloud/api/v1/orders/{order_id}/pay/",
    json={"pay_way": "X402"},
    headers={"Authorization": f"Bearer {platform_token}"},
)

response.raise_for_status()
receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
if receipt_header:
    print("إيصال x402:", decode_x_payment_response(receipt_header))

4. Python httpx (غير متزامن)

import asyncio
import os
from eth_account import Account
from x402.clients.httpx import x402HttpxClient
from x402.clients.base import decode_x_payment_response

async def pay_order() -> None:
    order_id = os.environ["ACE_X402_ORDER_ID"]
    platform_token = os.environ["ACE_PLATFORM_TOKEN"]
    account = Account.from_key(os.environ["ACE_X402_PRIVATE_KEY"])

    async with x402HttpxClient(
        account=account,
        base_url="https://platform.acedata.cloud",
        headers={"Authorization": f"Bearer {platform_token}"},
        payment_requirements_selector=lambda accepts, **_: next(
            req for req in accepts if req.network == "base"
        ),
    ) as client:
        response = await client.post(
            f"/api/v1/orders/{order_id}/pay/",
            json={"pay_way": "X402"},
        )
        response.raise_for_status()
        receipt_header = response.headers.get("X-PAYMENT-RESPONSE")
        if receipt_header:
            print("إيصال x402:", decode_x_payment_response(receipt_header))

asyncio.run(pay_order())
المثال يعرض فقط الاستدعاءات الرئيسية، يرجى إضافة معالجة الاستثناءات، استراتيجيات إعادة المحاولة، السجلات والتحكم في الأمان في بيئة الإنتاج.

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.
  • ملاحظات واقتراحات: نرحب بإخبارنا بمتطلبات التحسين من خلال أي من القنوات المذكورة أعلاه.