Ten przewodnik zawiera techniczną dokumentację interfejsu API i schematy ładunku do integracji interfejsu Cart API w wersji 2026-04-08 z protokołem Universal Commerce Protocol (UCP).
Zanim zaczniesz tworzyć punkty końcowe, zapoznaj się z omówieniem interfejsu Cart API overview, aby poznać ogólne koncepcje i wymagania wstępne.
Tworzenie koszyka
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ę na przeniesienie koszyka, Google wywoła ten punkt końcowy ze szczegółami elementu. Twój system musi odpowiedzieć adresem continue_url, który przekieruje użytkownika do wstępnie wypełnionego koszyka w Twojej witrynie.
- Punkt końcowy:
POST /carts - Reguła: użytkownik klika „Dodaj do koszyka” przy produkcie i dodaje pierwszy produkt do koszyka sprzedawcy.
Żądanie: Google wysyła tablicę line_items, które mają zostać dodane do koszyka.
Przykład żądania:
{
"line_items": [
{
"item": {
"id": "item_123"
},
"quantity": 2
}
]
}
Odpowiedź: zwracasz zainicjowaną sesję koszyka, w tym informacje o pozycji, sumy i adres continue_url. Pole continue_url w odpowiedzi musi przekierowywać użytkownika z powrotem na stronę w Twojej witrynie, na której może on dalej zarządzać koszykiem. Zazwyczaj jest to link do koszyka lub strony płatności z wstępnie załadowaną sesją zidentyfikowaną przez 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.