Ważne: 18 sierpnia 2026 r. wyłączyliśmy Content API for Shopping.

Od 1 września 2026 r. żądania Content API for Shopping będą stopniowo generować błędy. Zapoznaj się z przewodnikiem dotyczącym wyłączania Content API.

Jeśli potrzebujesz więcej czasu na przejście na Merchant API, poproś o przedłużenie dostępu do Content API for Shopping.

Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Omówienie usługi kierowania na listę klientów w programie lojalnościowym

Z tego przewodnika dowiesz się, jak korzystać z usługi kierowania na listę klientów w programie lojalnościowym w interfejsie Merchant API. Ta usługa umożliwia sprzedawcom i zewnętrznym dostawcom programów lojalnościowych działającym w imieniu sprzedawców zarządzanie danymi o lojalności klientów, takimi jak identyfikatory użytkowników i informacje o poziomie, na potrzeby bezpłatnej personalizacji w wyszukiwarce Google, bez konieczności posiadania aktywnego konta Google Ads.

Przegląd

Używaj usługi kierowania na listę klientów w programie lojalnościowym, aby przesyłać dane dotyczące programu lojalnościowego, które są następnie używane do udostępniania bezpłatnych funkcji personalizacji programu lojalnościowego w wyszukiwarce Google, takich jak wyświetlanie cen dla uczestników programu. Używasz metody niestandardowej ManageLoyaltyCustomerMatch, aby powiązać klientów z poziomami programu lojalnościowego, co umożliwia wstawianie, aktualizowanie lub usuwanie ich statusu lojalnościowego na podstawie identyfikatorów użytkowników.

Kluczowe pojęcia

Ujednolicony interfejs: unikalny punkt końcowy do dodawania, aktualizowania i usuwania szczegółów poziomu lojalności klienta.
Projekt skoncentrowany na ochronie prywatności: aby chronić prywatność użytkowników i zapobiegać nieautoryzowanemu sprawdzaniu kont, interfejs API nie obsługuje operacji GET ani LIST, co zapewnia zarządzanie danymi bez ich pobierania i kontrolowania.
Elastyczna identyfikacja: dopasowywanie użytkowników za pomocą co najmniej jednego prawidłowego identyfikatora, takiego jak adres e-mail, adres pocztowy lub numer telefonu.
Przetwarzanie na podstawie zgody: usługa przechowuje i wykorzystuje dane klientów tylko wtedy, gdy użytkownik wyraził na to niezbędną zgodę. Aby chronić konto i zapobiegać sprawdzaniu jego istnienia lub stanu zgody, usługa zwraca komunikat o powodzeniu, jeśli nie znaleziono dopasowania lub nie udzielono zgody.

Wymagania wstępne

Aby korzystać z usługi kierowania na listę klientów w programie lojalnościowym, musisz spełniać te wymagania:

Konfiguracja konta: upewnij się, że masz aktywne konto Merchant Center (lub autoryzowany dostęp do konta sprzedawcy, jeśli jesteś zewnętrznym dostawcą programu lojalnościowego). Aby korzystać z usługi kierowania na listę klientów w programie lojalnościowym, nie musisz tworzyć konta Google Ads.
Konfiguracja programu lojalnościowego: włącz program lojalnościowy na koncie Merchant Center i upewnij się, że masz zdefiniowane poziomy lojalności.
Kolejność poziomów: zwróć uwagę na kolejność, w jakiej poziomy lojalnościowe są zdefiniowane w interfejsie Merchant Center. Interfejs API używa tej dokładnej sekwencji do mapowania typów wyliczeniowych.

Metoda: `ManageLoyaltyCustomerMatch`

Metoda ManageLoyaltyCustomerMatch służy jako centralny interfejs do zarządzania powiązaniami lojalnościowymi klientów. Na podstawie podanych danych usługa automatycznie określa, czy należy wstawić, zaktualizować czy usunąć status poziomu lojalności klienta. Operacja jest idempotentna: powtarzające się identyczne żądania mają taki sam efekt jak pojedyncze żądanie.

Poniższe żądanie pokazuje, jak zarządzać powiązaniami z programem lojalnościowym klienta za pomocą interfejsu API:

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

To żądanie definiuje te wymagane parametry ścieżki:

API_VERSION: wersja interfejsu API, np. v1.
ACCOUNT_ID: identyfikator konta Merchant Center.

W treści żądania uwzględnij obiekt loyaltyCustomer.

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

Pola loyaltyCustomer

userIdentifier: zestaw identyfikatorów używanych do dopasowywania klienta. Musisz podać co najmniej jedno prawidłowe pole w obiekcie userIdentifier.
loyaltyTier: poziom lojalności, który ma być powiązany z klientem. Odpowiada kolejności poziomów w konfiguracji Merchant Center. Szczegółowe informacje znajdziesz w artykule Omówienie mapowania loyaltyTier. Aby usunąć istniejące powiązanie, użyj wartości NON_MEMBER.
pointBalance: aktualne saldo punktów klienta.

Pola userIdentifier

Wypełnij co najmniej jedno z tych pól:

emailAddress: adres e-mail klienta.
address: adres pocztowy klienta. Kod pocztowy jest wymagany.
phoneNumber: numer telefonu klienta. Zalecamy format E.164.

Mapowanie `loyaltyTier`

Interfejs API nie używa nazw niestandardowych. Wartości typu wyliczeniowego loyaltyTier (od TIER1 do TIER7) to etykiety semantyczne. Nie używają nazw niestandardowych (np. „Złote nagrody”) ani etykiet własnych (np. „gold_tier”) przypisanych w interfejsie Merchant Center. Zamiast tego są one ściśle powiązane z kolejnością, w jakiej poziomy zostały zdefiniowane w ustawieniach programu lojalnościowego w Merchant Center:

TIER1: odpowiada pierwszemu poziomowi podanemu w konfiguracji programu lojalnościowego w Merchant Center.
TIER2: odpowiada drugiemu poziomowi podanemu w konfiguracji programu lojalnościowego w Merchant Center.
TIER3 do TIER7: odpowiadają poziomom od 3 do 7 wymienionym w konfiguracji programu lojalnościowego w Merchant Center.

Przykład:

Jeśli program lojalnościowy w Merchant Center ma poziomy zdefiniowane w tej kolejności:

Nazwa poziomu: „Srebrny status”, etykieta poziomu: „srebrny”
Nazwa poziomu: „Złoty uczestnik”, etykieta poziomu: „złoty”
Nazwa poziomu: „Platynowy Elite”, etykieta poziomu: „platynowy”

Następnie w wywołaniach interfejsu API accounts.loyaltyCustomers.manage:

Aby przypisać klienta do „Srebrnego statusu”, musisz użyć loyaltyTier: TIER1.
Aby przypisać klienta do grupy „Gold Member”, musisz użyć wartości loyaltyTier: TIER2.
Aby przypisać klienta do poziomu „Platinum Elite”, musisz użyć loyaltyTier: TIER3.

Wartości typu wyliczeniowego LoyaltyTier

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (służy do sygnalizowania usunięcia powiązania klienta z programem lojalnościowym)

Informacje o treści odpowiedzi ManageLoyaltyCustomerMatch

Metoda ManageLoyaltyCustomerMatch zwraca obiekt ManageLoyaltyCustomerMatchResponse:

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

Ważne uwagi dotyczące odpowiedzi

Udane wstawienie lub aktualizacja (dane zapisane): aby zapisać lub zaktualizować powiązanie poziomu lojalności klienta, musisz spełnić te warunki:
- dopasowujesz użytkownika Google do podanego userIdentifier
- ustawisz w żądaniu prawidłową wartość loyaltyTier inną niż NON_MEMBER,
- dopasowany użytkownik wyraził zgodę na wykorzystanie danych o lojalności,

Odpowiedź zawiera obiekt loyaltyCustomer z żądania, co oznacza, że usługa pomyślnie przetworzyła i zapisała dane:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

Pomyślne usunięcie: aby usunąć istniejące powiązanie klienta z programem lojalnościowym tego sprzedawcy, muszą zostać spełnione te warunki:
- dopasowujesz użytkownika Google do podanego userIdentifier
- ustawiasz parametr loyaltyTier w żądaniu na NON_MEMBER,

Odpowiedzią jest pusty obiekt JSON:

{}

Brak dopasowania / brak zgody (cichy sukces): jeśli podany parametr userIdentifier nie pasuje do konta Google lub jeśli dopasowany użytkownik nie wyraził zgody na wykorzystanie danych lojalnościowych, interfejs API zwraca stan HTTP 200 OK z pustym obiektem JSON: {}. Dzieje się tak zarówno w przypadku prób aktualizacji, jak i usunięcia.

Przykłady

TIER1 odpowiada pierwszemu zdefiniowanemu poziomowi (np. 'Basic'), a TIER2 – drugiemu (np. 'Premium').

Aby dodać klienta do poziomu TIER2 lub zaktualizować jego stan za pomocą adresu e-mail, wyślij to żądanie:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

Gdy użytkownik zostanie dopasowany i wyrazi zgodę, interfejs API zwróci tę odpowiedź:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

Jeśli nie ma dopasowania lub użytkownik nie wyraził zgody, interfejs API zwraca tę odpowiedź:

{}

Aby usunąć powiązanie klienta z programem lojalnościowym za pomocą numeru telefonu, wyślij to żądanie:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

Niezależnie od tego, czy rekord istniał, interfejs API zwraca tę odpowiedź:

{}

Aby dodać lub zaktualizować klienta za pomocą wielu identyfikatorów, wyślij to żądanie:

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

Odpowiedź jest podobna do tej z pierwszego przykładu, w zależności od dopasowania i zgody.

Obsługa błędów

Interfejs API używa standardowych kodów HTTP. Typowe ciągi błędów:

Kod HTTP	Error String	Opis
400	INVALID_ARGUMENT	Brak parametru user_identifier lub loyalty_tier albo identyfikator jest pusty.
401	UNAUTHENTICATED	Nieprawidłowe lub brakujące dane logowania.
403	PERMISSION_DENIED	Uwierzytelniony użytkownik nie ma dostępu do określonego konta Merchant Center.
404	NOT_FOUND	Podana etykieta poziomu lojalności nie istnieje w Twojej konfiguracji.
412	FAILED_PRECONDITION	Na koncie nie skonfigurowano programu lojalnościowego.
429	RESOURCE_EXHAUSTED	Osiągnięto limit przydziału.

Przykłady błędów

Przykład błędu 404 NOT_FOUND:

Dowolne prawidłowe żądanie dotyczące identyfikatora konta, które nie ma skonfigurowanego programu lojalnościowego.