การใช้งาน Cart API

คู่มือนี้มีเอกสารอ้างอิง API ทางเทคนิคและสคีมาเพย์โหลดสำหรับการ ผสานรวม API รถเข็นของ Universal Commerce Protocol (UCP) ในเวอร์ชัน 2026-04-08

ก่อนสร้างปลายทาง โปรดอ่านภาพรวมของ Cart API เพื่อดูแนวคิดและข้อกำหนดเบื้องต้นระดับสูง

สร้างรถเข็น

ปลายทางนี้ช่วยให้สร้างเซสชันรถเข็นใหม่ได้ หากต้องการผสานรวม ให้ใช้CreateCartปลายทาง (POST /carts) เมื่อผู้ใช้เลือกโอนรถเข็น Google จะเรียกปลายทางนี้พร้อมรายละเอียดสินค้าในบรรทัดทั้งหมด ระบบของคุณ ต้องตอบกลับด้วย continue_url โดยนำผู้ใช้ไปยังรถเข็นที่กรอกข้อมูลไว้ล่วงหน้า ในเว็บไซต์ของคุณ

• ปลายทาง: POST /carts
• ทริกเกอร์: ระบบจะทริกเกอร์คำขอ CreateCart (POST /carts) รายการเดียวก็ต่อเมื่อ ผู้ใช้คลิกปุ่มโอน (เช่น ชำระเงินในร้านค้า) เพื่อโอนรถเข็นไปยังร้านค้าของคุณ

ขั้นตอนการชำระเงิน

ขั้นตอนการชำระเงินและสถานะการชำระเงินมีดังนี้

• การสะสมใน Google: เมื่อผู้ใช้เพิ่มสินค้าลงในรถเข็น Google จะสะสมสินค้าเหล่านั้นไว้ในเครื่อง Google จะไม่ทริกเกอร์ การเรียก API หลายครั้งเมื่อมีการเพิ่มรายการ
• เพย์โหลด: คำขอ 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"
}

การจัดการข้อผิดพลาด

ดูหลักเกณฑ์ทั้งหมดเกี่ยวกับวิธีจัดรูปแบบข้อความแสดงข้อผิดพลาดและความแตกต่างระหว่างข้อผิดพลาดของโปรโตคอลและข้อผิดพลาดของตรรกะทางธุรกิจได้ที่รหัสข้อผิดพลาด