Wdrożenie Universal Commerce Protocol (UCP) — poradnik dla właścicieli sklepów

Universal Commerce Protocol to otwarty standard stworzony przez Google i Shopify, który pozwala agentom AI (Gemini, ChatGPT, Copilot) realizować transakcje bezpośrednio z backendem sklepu — bez przekierowywania użytkownika na stronę. Protokół wystartował w styczniu 2026 na konferencji NRF, a w marcu 2026 Google opublikował oficjalną stronę pomocy z wymaganiami wdrożeniowymi. Ten poradnik przeprowadzi Cię przez architekturę protokołu, konfigurację Merchant Center, implementację endpointów i typowe pułapki integracyjne — niezależnie od tego, czy pracujesz na Shopify, WooCommerce, Magento czy własnym stosie technologicznym.

Architektura UCP — co implementujesz i na jakim poziomie?

Zanim zaczniesz kodować, musisz zrozumieć, jak UCP dzieli odpowiedzialności między warstwy. Shopify porównuje tę architekturę do modelu TCP/IP i to porównanie dobrze oddaje logikę: każda warstwa odpowiada za inny aspekt transakcji, można je rozwijać niezależnie, a sprzedawca implementuje tylko te elementy, których potrzebuje.

• Najniższa warstwa logiczna — Shopping Service — definiuje prymitywy transakcyjne: sesję checkout, pozycje koszyka (line items), podsumowania (totals), statusy i wiadomości. To rdzeń, który nie wie nic o dostawie, rabatach ani programach lojalnościowych. Rdzeń pozostaje stabilny niezależnie od tego, ile extensions dodasz.
• Nad rdzeniem siedzą Capabilities — moduły funkcjonalne, z których na start (marzec 2026) dostępne są trzy. Checkout obsługuje sesje z kalkulacją podatków i finalizacją zamówienia. Identity Linking łączy konta kupującego z systemem sprzedawcy przez OAuth 2.0, żeby agent miał dostęp do historii zamówień i rabatów członkowskich. Order Management zarządza cyklem życia zamówienia po zakupie przez webhookowe aktualizacje. Każda capability jest wersjonowana niezależnie — zmiana w Orders nie wymusza aktualizacji Checkout.
• Trzecia warstwa — Extensions — działa jak pluginy do capabilities. Przykład z repozytorium: dev.ucp.shopping.fulfillment dodaje obsługę opcji dostawy (shipping, pickup, local delivery) do sesji checkout, a dev.ucp.shopping.discount obsługę kodów rabatowych. Sprzedawcy z niestandardowymi wymaganiami mogą definiować własne extensions, a protokół ewoluuje w miarę dojrzewania wzorców.

Nie musisz implementować całego protokołu od razu. Zacznij od Checkout capability, dodaj Fulfillment extension, a Identity Linking i Order Management wdróż w drugiej iteracji.

Ścieżka wdrożenia UCP z Google

Google opublikował oficjalną ścieżkę integracji na developers.google.com/merchant/ucp/guides. Składa się z sześciu etapów, które przechodzisz sekwencyjnie. Pominięcie któregokolwiek zablokuje kolejne.

• Etap 1 — Merchant Center. Upewnij się, że Twoje konto Merchant Center jest aktywne, feed produktowy kompletny (tytuły 30+ znaków, opisy 500+ znaków, numery GTIN, zdjęcia min. 1500×1500 px) i polityki zwrotów zdefiniowane. Dodaj atrybut native_commerce do produktów, które mają być dostępne przez UCP — bez niego produkt nie wyświetli się z przyciskiem „Kup” w AI Mode i Gemini.
• Etap 2 — Google Pay & Wallet Console. Zarejestruj się, zanotuj swój Merchant ID (prawy górny róg konsoli) i sprawdź, czy Twój Payment Service Provider znajduje się na liście procesorów wspierających tokenizację Google Pay. Jeśli korzystasz z Adyen, Stripe, PayU czy Przelewy24 — sprawdź kompatybilność z Google Pay na stronie procesora.
• Etap 3 — Manifest /.well-known/ucp. Opublikuj na swojej domenie plik JSON pod adresem /.well-known/ucp. To jest profil Twojego serwisu — deklarujesz w nim obsługiwane services, capabilities, extensions, payment handlery i klucze publiczne do weryfikacji podpisów. Agent AI pobiera ten manifest przed każdą interakcją, żeby dynamicznie odkryć, co Twój sklep potrafi. Przykład z oficjalnego repozytorium pokazuje strukturę:

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specs/shopping",
        "rest": {
          "schema": "https://ucp.dev/services/shopping/openapi.json",
          "endpoint": "https://twojsklep.pl/ucp/"
        }
      }
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11",
        "spec": "https://ucp.dev/specs/shopping/checkout",
        "schema": "https://ucp.dev/schemas/shopping/checkout.json"
      },
      {
        "name": "dev.ucp.shopping.fulfillment",
        "version": "2026-01-11",
        "extends": "dev.ucp.shopping.checkout"
      }
    ]
  },
  "payment": {
    "handlers": [
      {
        "id": "google_pay",
        "name": "google.pay",
        "version": "2026-01-11"
      }
    ]
  }
}

Niekompletna lub nieaktualna deklaracja nie obniża pozycji organicznych — sprawia, że agent w ogóle nie rozważy Twojego sklepu jako opcji transakcyjnej.

• Etap 4 — Implementacja Native Checkout. To rdzeń integracji — trzy endpointy REST, które opisuję szczegółowo w następnej sekcji.
• Etap 5 (opcjonalny) — Embedded Checkout. Dla sprzedawców z bardzo złożonymi flowami checkout (np. konfiguratory produktów, regulacje branżowe) Google oferuje ścieżkę embedded — checkout jest wyświetlany w iframe wewnątrz interfejsu AI. Wymaga osobnego zatwierdzenia przez Google i dodania obiektu embedded do manifestu /.well-known/ucp.
• Etap 6 — Identity Linking i Order Sync. Jeśli chcesz obsługiwać checkout zalogowanych użytkowników (z dostępem do programów lojalnościowych), wdrażasz OAuth 2.0 Authorization Code Flow (RFC 6749) z metadanymi pod /.well-known/oauth-authorization-server. Synchronizację statusu zamówień realizujesz przez wywoływanie webhooków Google.

Trzy endpointy checkout — implementacja serwera merchant

Serce integracji UCP to trzy endpointy REST, które Twój serwer musi udostępnić. Google wysyła do nich żądania, gdy agent AI inicjuje, aktualizuje lub finalizuje sesję zakupową. Każde żądanie zawiera nagłówki UCP-Agent (URL profilu agenta), request-signature, idempotency-key i request-id.

POST /checkout-sessions — tworzenie sesji

Agent inicjuje sesję, przesyłając pozycje koszyka (SKU, ilość), dane kupującego (imię, email) i konfigurację płatności (lista handlerów). Twój serwer odpowiada obiektem checkout z ID sesji, wyliczonymi podsumowaniami (totals), statusem i listą wiadomości.

Jeśli agent nie dostarczył wymaganych danych — np. adresu dostawy — zwracasz status incomplete z tablicą messages, gdzie każda wiadomość ma severity: recoverable i opisuje brakujące pole. Google spróbuje uzupełnić te dane samodzielnie (np. z Google Wallet). Jeśli brakujących danych nie da się zebrać standardowymi polami UCP (np. niestandardowe okno dostawy, weryfikacja wieku), zwracasz requires_escalation z continue_url, pod którym użytkownik dokończy checkout ręcznie.

Logika obsługi sesji musi być deterministyczna — to wymóg specyfikacji. Przy tych samych danych wejściowych serwer musi zwracać te same wyniki. Brak deterministyczności = odrzucenie przez Google podczas testów zgodności.

POST /checkout-sessions/{id} — aktualizacja i finalizacja sesji

Po utworzeniu sesji następują dwa rodzaje operacji na tym samym zasobie. Aktualizacja (update) — Google wysyła pełny obiekt checkout ze zmianami (nowy adres dostawy, inna metoda wysyłki, inny instrument płatniczy). Twój serwer przelicza dynamicznie podatki, koszty dostawy i dostępne opcje fulfillment, po czym zwraca zaktualizowany obiekt. Ten endpoint bywa wywoływany wielokrotnie w trakcie jednej sesji. Rekomendacja Google: monitoruj czasy odpowiedzi — agenty AI mają timeout, a zbyt wolny serwer zostanie oznaczony jako tymczasowo niedostępny.

Finalizacja (complete) — złożenie zamówienia. Google wywołuje POST /checkout-sessions/{id}/complete, gdy użytkownik zatwierdził płatność. Twój serwer musi zwrócić obiekt checkout ze statusem completed i polem order zawierającym id zamówienia oraz permalink_url do śledzenia statusu. Po finalizacji sesja jest niezmienna (immutable). Twój serwer musi wysłać email potwierdzający zamówienie — to wymóg specyfikacji UCP. Kolejne aktualizacje (wysyłka, dostawa, zwrot) przesyłasz przez webhookowe powiadomienia do Google.

Ścieżka integracji w zależności od platformy e-commerce

Czas i złożoność wdrożenia UCP radykalnie różnią się w zależności od platformy sklepowej. Tabela poniżej bazuje na danych z pierwszych 3 miesięcy od premiery protokołu (styczeń–marzec 2026).

Dla Shopify cały proces zaczyna się od instalacji aplikacji Universal Commerce Agent i konfiguracji Agent Policy — uprawnień określających, co agent AI może robić (na start ustawiasz Read-Only, po walidacji przechodzisz na Create Carts). Mapowanie metafieldów (Size, Color, Material) na standardowe pola UCP odbywa się w ustawieniach aplikacji.

Dla WooCommerce, Magento, PrestaShop i custom stacków — nie ma gotowych pluginów. Budujesz trzy endpointy checkout, hostujesz manifest /.well-known/ucp, implementujesz Identity Linking (OAuth 2.0) i Order Management (webhooks). Google udostępnia referencyjne implementacje serwera w Pythonie (FastAPI) i Node.js (Hono + Zod) w repozytorium github.com/Universal-Commerce-Protocol/samples — to dobry punkt wyjścia.

Płatności, bezpieczeństwo i Identity Linking — detale techniczne

Architektura płatności UCP rozdziela dwa pojęcia, które w tradycyjnym e-commerce są spłaszczone. Instrument to, czym płaci konsument (karta w Google Wallet, konto PayPal). Payment handler to procesor po stronie sprzedawcy (Stripe, Adyen, PayU). Obiekt checkout zawiera pole payment.handlers, w którym deklarujesz wspierane procesory, a Google wypełnia payment.instruments danymi instrumentu po zatwierdzeniu przez kupującego.

Ta separacja oznacza, że nie musisz zmieniać swojego PSP, żeby wdrożyć UCP. Jeśli Twój procesor wspiera tokenizację Google Pay — wystarczy zadeklarować go jako handler w manifeście i odpowiednio obsłużyć token w endpoincie /complete. Każda autoryzacja płatności jest wspierana kryptograficznym dowodem zgody użytkownika (verifiable credentials) — to element współpracy z Agent Payments Protocol (AP2).

Identity Linking — OAuth 2.0 dla zalogowanych sesji

Jeśli chcesz, żeby agent miał dostęp do konta kupującego (rabaty członkowskie, zapisane adresy, historia zamówień), wdrażasz Identity Linking przez OAuth 2.0 Authorization Code Flow. Wymagania techniczne:

• Implementacja /.well-known/oauth-authorization-server z metadanymi OAuth (issuer, authorization_endpoint, token_endpoint, scopes_supported)
• Obsługa scope ucp:scopes:checkout_session, który daje agentowi uprawnienia do operacji checkout
• Uwierzytelnianie klienta przez client_secret_basic na token endpoint
• Wsparcie dla authorization_code i refresh_token jako grant types

Jeśli nie implementujesz Identity Linking, musisz obsłużyć guest checkout — to jedyny obowiązkowy wariant. Opcja „zalogowany” jest opcjonalna, ale otwiera drogę do personalizacji i programów lojalnościowych w przyszłych wersjach UCP.

UCP vs ACP — który protokół wdrażać (i dlaczego oba)?

Jeśli śledzisz rynek agentic commerce, wiesz, że równolegle do UCP rozwija się Agentic Commerce Protocol (ACP) od OpenAI i Stripe. Z perspektywy wdrożeniowej — to nie są konkurujące alternatywy, lecz protokoły operujące na różnych interfejsach AI.

UCP obsługuje AI Mode w Google Search i aplikację Gemini. ACP obsługuje ChatGPT (Instant Checkout). Etsy wspiera oba protokoły jednocześnie. Shopify współtworzył UCP z Google, ale równocześnie umożliwia ponad milionowi sprzedawców korzystanie z ChatGPT Instant Checkout przez ACP. Walmart zintegrował się z oboma ekosystemami.

Rekomendacja w marcu 2026 jest jednoznaczna: wdrażaj oba. Dane z pierwszych tygodni działania pokazują, że sprzedawcy z podwójną implementacją (UCP + ACP) notują ok. 40% więcej ruchu agentowego niż ci z jednym protokołem. Implementacje w dużej mierze się pokrywają — feed produktowy, endpointy checkout, dane strukturalne — więc koszt dodania drugiego protokołu jest ułamkiem kosztu pierwszego.

Architektonicznie największa różnica leży w modelu discovery. UCP jest zdecentralizowany — manifest /.well-known/ucp hostujesz na swojej domenie, a każdy agent może go odczytać. ACP jest scentralizowany — aplikujesz do OpenAI, dostarczasz feed produktowy, a OpenAI decyduje, co surfacować. Z perspektywy kontroli nad danymi UCP daje Ci więcej autonomii. Z perspektywy szybkości wdrożenia ACP bywa prostszy (szczególnie jeśli już korzystasz ze Stripe).

Typowe błędy i jak ich uniknąć przy wdrożeniu UCP

Obserwując pierwsze miesiące wdrożeń UCP w ekosystemie, można wskazać powtarzające się pułapki, które blokują sprzedawców.

• Niespójność danych między stroną a feedem. Google porównuje dane z Merchant Center z informacjami na Twojej stronie produktowej. Rozbieżność ceny, dostępności czy opisu sprawia, że agent oznaczy Twoje dane jako niewiarygodne i pominie produkt. Trzy źródła danych — strona, feed MC, manifest UCP — muszą mówić to samo.
• Brak deterministyczności w endpointach checkout. Specyfikacja UCP wymaga, żeby logika checkout była deterministyczna. Przy tych samych danych wejściowych serwer musi zwracać identyczne wyniki. Jeśli Twój system losowo zmienia ceny, opcje dostawy lub dostępność między wywołaniami — testy zgodności Google nie przejdą.
• Zbyt wolne odpowiedzi serwera. Agent AI ma ograniczony czas na interakcję. Jeśli Twój endpoint odpowiada dłużej niż kilka sekund, agent może oznaczyć sklep jako tymczasowo niedostępny. Przy utrzymującym się wskaźniku błędów powyżej 5% w ciągu 24 godzin grozi trwałe obniżenie „trust score” i redukcja częstotliwości rekomendacji. Monitoruj logi w pierwszych 30 dniach po wdrożeniu.
• Nieobsłużenie stanu requires_escalation. Jeśli Twój checkout wymaga danych, których agent nie może zebrać standardowymi polami UCP, musisz zwrócić status requires_escalation z poprawnym continue_url i co najmniej jedną wiadomością z severity: escalation. Brak continue_url w odpowiedzi z tym statusem to błąd walidacji.
• Brak emaila potwierdzającego. Specyfikacja wymaga, żeby po statusie completed Twój serwer wysłał kupującemu email z potwierdzeniem zamówienia. Automatyzacja tego kroku musi być gotowa przed wyjściem na produkcję.

Dla programistów rozpoczynających wdrożenie — najlepsza ścieżka to sklonowanie referencyjnej implementacji z github.com/Universal-Commerce-Protocol/samples (serwer w Pythonie/FastAPI lub Node.js/Hono), uruchomienie lokalne, przejście scenariusza „happy path” (discovery → checkout → payment) i dopiero potem mapowanie na własny backend. Google udostępnia też testy zgodności (conformance tests) w repozytorium, które walidują Twoje endpointy przed zgłoszeniem do przeglądu. Start od tych testów zaoszczędzi tygodnie debugowania.