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 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 tất cả thông tin chi tiết về các 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
  • Trình kích hoạt: chỉ một yêu cầu CreateCart (POST /carts) được kích hoạt khi người dùng nhấp vào nút chuyển (ví dụ: Thanh toán trên trang web của người bán) để chuyển giỏ hàng của họ đến cửa hàng của bạn.

Luồng giỏ hàng

Luồng và trạng thái của giỏ hàng hoạt động như sau:

  • Tích luỹ trên Google: khi người dùng thêm mặt hàng vào giỏ hàng, Google sẽ tích luỹ những mặt hàng đó tại địa phương. Google không kích hoạt nhiều lệnh gọi API khi các mục được thêm.
  • Tải trọng: yêu cầu POST /carts duy nhất sẽ chứa toàn bộ mảng của tất cả line_items đã tích luỹ cùng một lúc.
  • Chuyển hướng và trạng thái: hệ thống phụ trợ của người bán phản hồi bằng một continue_url trỏ đến giỏ hàng được điền sẵn trên trang web của họ.

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