הטמעה של Cart API

במדריך הזה מפורטים מאמרי העזרה של ה-API הטכניים וסכימות המטען הייעודי (payload) לשילוב של Cart API של Universal Commerce Protocol‏ (UCP) בגרסה 2026-04-08.

לפני שיוצרים את נקודות הקצה, חשוב לעיין בסקירה הכללית של Cart API כדי להבין את המושגים והדרישות ברמה גבוהה.

יצירת עגלה

נקודת הקצה הזו מאפשרת ליצור סשן חדש של עגלת קניות. כדי לבצע שילוב, צריך להטמיע את נקודת הקצה CreateCart (POST /carts). כשמשתמש בוחר להעביר את עגלת הקניות שלו, Google קוראת לנקודת הקצה הזו עם נתוני הפריט. המערכת שלכם צריכה להגיב עם continue_url שמפנה את המשתמש לעגלת הקניות באתר שלכם, שמאוכלסת מראש.

• נקודת קצה (endpoint): 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"
}

טיפול בשגיאות

הנחיות מלאות לגבי הפורמט של הודעות שגיאה וההבדל בין שגיאות בפרוטוקול לבין שגיאות בלוגיקה העסקית מופיעות במאמר קודי שגיאה.