Implementacja interfejsu API koszyka

Ten przewodnik zawiera techniczną dokumentację interfejsu API i schematy ładunków do integracji interfejsu Cart API protokołu Universal Commerce Protocol (UCP) w wersji 2026-04-08.

Zanim zaczniesz tworzyć punkty końcowe, zapoznaj się z omówieniem interfejsu Cart API, aby poznać ogólne koncepcje i wymagania wstępne.

Utwórz koszyk

Ten punkt końcowy umożliwia utworzenie nowej sesji koszyka. Aby przeprowadzić integrację, zaimplementuj punkt końcowy CreateCart (POST /carts). Gdy użytkownik zdecyduje się przenieść koszyk, Google wywoła ten punkt końcowy ze wszystkimi szczegółami dotyczącymi pozycji. Twój system musi odpowiedzieć continue_url, kierując użytkownika do wstępnie wypełnionego koszyka w Twojej witrynie.

  • Punkt końcowy: POST /carts
  • Reguła: pojedyncza prośba CreateCart (POST /carts) jest uruchamiana tylko wtedy, gdy użytkownik kliknie przycisk przenoszenia (np. Do kasy w sklepie), aby przenieść koszyk do Twojego sklepu.

Proces koszyka

Proces i stan koszyka działają w ten sposób:

  • Gromadzenie w Google: gdy użytkownik dodaje produkty do koszyka, Google gromadzi je lokalnie. Google nie wysyła wielu wywołań interfejsu API podczas dodawania produktów.
  • Ładunek: pojedyncze żądanie POST /carts będzie zawierać pełną tablicę wszystkich zgromadzonych wartości line_items.
  • Przekierowanie i stan: backend sprzedawcy odpowiada za pomocą kodu continue_url, który wskazuje wstępnie wypełniony koszyk w jego witrynie.

Żądanie: Google wysyła tablicę line_items do dodania do koszyka.

Przykładowe żądanie:

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

Odpowiedź: zwracasz zainicjowaną sesję koszyka, w tym szczegóły elementu zamówienia, sumy i continue_url. Pole continue_url w odpowiedzi musi kierować użytkownika z powrotem na stronę w Twojej witrynie, na której może on dalej zarządzać koszykiem. Zwykle prowadzi on do koszyka lub strony płatności z sesją zidentyfikowaną przez wstępnie wczytany parametr id.

Przykład odpowiedzi:

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

Obsługa błędów

Pełne wytyczne dotyczące formatowania komunikatów o błędach oraz różnic między błędami protokołu a błędami logiki biznesowej znajdziesz w artykule Kody błędów.

Dalej
Kody promocyjne i zniżki