הטמעה של Cart API

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

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

יצירת עגלה

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

• נקודת קצה (endpoint): POST /carts
• טריגר: בקשה יחידה של CreateCart (POST /carts) מופעלת רק כשמשתמש לוחץ על לחצן ההעברה (לדוגמה, הפניה לדף התשלום באתר המוכר) כדי להעביר את עגלת הקניות לחנות שלכם.

תהליך עגלת הקניות

כך פועלים התהליך והסטטוס של עגלת הקניות:

• צבירה ב-Google: כשמשתמש מוסיף פריטים לעגלת הקניות, Google צוברת את הפריטים האלה באופן מקומי. ‫Google לא מפעילה כמה קריאות ל-API כשמוסיפים פריטים.
• המטען הייעודי (payload): בקשת POST /carts היחידה תכיל את המערך המלא של כל line_items שנצברו בבת אחת.
• הפניה אוטומטית ומצב: הקצה העורפי של המוכר מגיב עם continue_url שמפנה לעגלת קניות שאוכלסה מראש באתר שלו.

בקשה: 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"
}

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

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