Triển khai Cart API

Hướng dẫn này cung cấp Tài liệu tham khảo API kỹ thuật và lược đồ tải trọng để tích hợp Cart API theo Giao thức thương mại toàn cầu (UCP) ở phiên bản 2026-04-08.

Trước khi tạo các điểm cuối, hãy đảm bảo rằng bạn đã xem Tổng quan về Cart API để nắm được các khái niệm và điều kiện tiên quyết cấp cao.

Tạo giỏ hàng

Điểm cuối này cho phép tạo một phiên giỏ hàng mới. Để tích hợp, hãy triển khai điểm cuối CreateCart (POST /carts). Khi người dùng chọn chuyển giỏ hàng, Google sẽ gọi điểm cuối này bằng thông tin chi tiết về mặt hàng. Hệ thống của bạn phải phản hồi bằng một continue_url để chuyển người dùng đến giỏ hàng được điền sẵn thông tin trên trang web của bạn.

  • Điểm cuối: POST /carts
  • Điều kiện kích hoạt: Người dùng nhấp vào "Thêm vào giỏ hàng" trên một sản phẩm và thêm mặt hàng đầu tiên vào giỏ hàng cho người bán.

Yêu cầu: Google gửi mảng line_items cần thêm vào giỏ hàng.

Ví dụ về yêu cầu:

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

Phản hồi: Bạn trả về phiên giỏ hàng đã khởi tạo, bao gồm cả thông tin chi tiết về mục hàng, tổng số tiền và continue_url. Trường continue_url trong phản hồi phải chuyển hướng người dùng quay lại một trang trên trang web của bạn để họ có thể tiếp tục quản lý giỏ hàng. Thông thường, đường liên kết này sẽ dẫn đến trang giỏ hàng hoặc trang thanh toán của bạn, trong đó phiên được xác định bằng id đã tải trước.

Ví dụ về phản hồi:

{
  "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"
}

Xử lý lỗi

Để biết nguyên tắc đầy đủ về cách định dạng thông báo lỗi và sự khác biệt giữa lỗi giao thức và lỗi logic nghiệp vụ, hãy xem phần Mã lỗi.

Tiếp
Mã khuyến mãi và chiết khấu