تنفيذ Cart API

يوفّر هذا الدليل المرجع الفني لواجهة برمجة التطبيقات (API) ومخططات حمولة البيانات لدمج Cart API في Universal Commerce Protocol (UCP) بالإصدار 2026-04-08.

قبل إنشاء نقاط النهاية، تأكَّد من مراجعة نظرة عامة على Cart API للاطّلاع على المفاهيم والمتطلبات الأساسية.

إنشاء سلة تسوّق

تتيح نقطة النهاية هذه إنشاء جلسة سلة تسوّق جديدة. لدمجها، عليك تنفيذ نقطة نهاية CreateCart (POST /carts). عندما يختار المستخدم نقل سلة التسوّق، تتصل Google بنقطة النهاية هذه مع تفاصيل بنود الطلب. على نظامك الردّ باستخدام continue_url لتوجيه المستخدم إلى سلة التسوّق التي تم ملؤها مسبقًا على موقعك الإلكتروني.

• نقطة النهاية: POST /carts
• الحدث المشغِّل: ينقر المستخدم على "إضافة إلى سلة التسوّق" على منتج ويضيف أول سلعة إلى سلة التسوّق لدى التاجر.

الطلب: ترسل Google مصفوفة line_items التي ستتم إضافتها إلى سلة التسوّق.

مثال على الطلب:

{
  "line_items": [
    {
      "item": {
        "id": "item_123"
      },
      "quantity": 2
    }
  ]
}

الردّ: يمكنك عرض جلسة سلة التسوّق التي تم إعدادها، بما في ذلك تفاصيل بنود الطلب والمجاميع وcontinue_url. يجب أن يوجّه الحقل continue_url في الردّ المستخدم إلى صفحة على موقعك الإلكتروني حيث يمكنه مواصلة إدارة سلة التسوّق. يرتبط هذا الحقل عادةً بسلة التسوّق أو صفحة الدفع مع تحميل الجلسة المحدّدة مسبقًا من خلال id.

مثال على الردّ:

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.cart": [{"version": "2026-04-08"}]
    }
  },
  "id": "cart_abc123",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 5000
    },
    {
      "type": "total",
      "amount": 5000,
      "display_text": "Estimated total (taxes calculated at checkout)"
    }
  ],
  // Used for redirecting the user back to the merchant's cart experience from Google surfaces.
  "continue_url": "https://business.example.com/checkout?cart=cart_abc123",
  // Indicate the timestamp at which the cart session will expire and become invalid.
  "expires_at": "2026-01-16T12:00:00Z"
}

معالجة الأخطاء

للاطّلاع على الإرشادات الكاملة حول كيفية تنسيق رسائل الخطأ والتمييز بين أخطاء البروتوكول وأخطاء منطق النشاط التجاري، يُرجى الانتقال إلى رموز الخطأ.