پیاده‌سازی API سبد خرید، پیاده‌سازی API سبد خرید

این راهنما مرجع فنی API و طرحواره‌های بار مفید برای ادغام API سبد خرید پروتکل تجارت جهانی (UCP) در نسخه 2026-04-08 را ارائه می‌دهد.

قبل از ساخت نقاط پایانی خود، مطمئن شوید که مرور کلی Cart API را برای مفاهیم سطح بالا و پیش‌نیازها مرور کرده‌اید.

ایجاد سبد خرید

این نقطه پایانی امکان ایجاد یک جلسه سبد خرید جدید را فراهم می‌کند. برای ادغام، نقطه پایانی CreateCart ( POST /carts ) را پیاده‌سازی کنید. وقتی کاربری تصمیم به انتقال سبد خرید خود می‌گیرد، گوگل این نقطه پایانی را با تمام جزئیات اقلام خطی فراخوانی می‌کند. سیستم شما باید با یک continue_url پاسخ دهد که کاربر را به سبد خرید از پیش پر شده در سایت شما هدایت می‌کند.

• نقطه پایانی: POST /carts
• فعال‌کننده: یک درخواست CreateCart ( POST /carts ) تنها زمانی فعال می‌شود که کاربر روی دکمه انتقال (مثلاً پرداخت در فروشگاه ) کلیک کند تا سبد خرید خود را به فروشگاه شما منتقل کند.

جریان سبد خرید

جریان سبد خرید و وضعیت آن به شرح زیر است:

• انباشت در گوگل: وقتی کاربری اقلامی را به سبد خرید خود اضافه می‌کند، گوگل آن اقلام را به صورت محلی جمع‌آوری می‌کند. گوگل هنگام افزودن اقلام، چندین فراخوانی API انجام نمی‌دهد.
• بار مفید: درخواست POST /carts شامل آرایه کاملی از تمام line_items انباشته شده به طور همزمان خواهد بود.
• تغییر مسیر و وضعیت: بخش مدیریت فروشنده با یک continue_url پاسخ می‌دهد که به سبد خرید از پیش پر شده در وب‌سایت آنها اشاره دارد.

درخواست: گوگل آرایه‌ای از 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"
}

مدیریت خطا

برای راهنمایی‌های کامل در مورد نحوه قالب‌بندی پیام‌های خطا و تمایز بین خطاهای پروتکل و منطق کسب‌وکار، به کدهای خطا مراجعه کنید.