Przenoszenie zarządzania kontem

Interfejs Accounts API jest podzielony na zbiór zasobów, które umożliwiają wydajniejsze zarządzanie kontami Merchant Center i precyzyjniejszą kontrolę nad różnymi aspektami konta.

Z tego przewodnika dowiesz się o najważniejszych zmianach i uzyskasz pomoc w migracji obecnej integracji zarządzania kontem z Content API for Shopping do Merchant API.

Z jednego zasobu do wielu

W interfejsie Content API for Shopping zasób Account był obiektem monolitycznym zawierającym wszystko, od nazwy konta i adresu URL witryny po listy użytkowników i informacje o firmie.

Interfejs Merchant API dzieli to na kilka mniejszych, bardziej wyspecjalizowanych zasobów. Ta zmiana umożliwia bardziej precyzyjne i wydajne wywołania interfejsu API. Jeśli np. chcesz zaktualizować tylko adres firmy, wysyłasz żądanie PATCH do zasobu BusinessInfo zamiast aktualizować cały obiekt Account.

Poniżej znajdziesz podsumowanie, jak pojęcia z dokumentacji Content API for Shopping Account odnoszą się do nowych zasobów w Merchant API:

• Podstawowe informacje o koncie (identyfikator, nazwa, ustawienia treści dla dorosłych) pozostają w zasobie Account.
• Informacje o firmie (adres, numer telefonu, obsługa klienta) są teraz zarządzane przez zasób BusinessInfo.
• Adres URL witryny i zgłaszanie do niego praw są obsługiwane przez zasób Homepage.
• Zarządzanie użytkownikami odbywa się za pomocą zasobu User.
• Relacje między kontami (połączenia z kontami zaawansowanymi, dostawcami zewnętrznymi i innymi usługami Google) są zarządzane przez zasoby AccountRelationship i AccountService.
• Atrybutami tożsamości firmy (np. firma należąca do osoby czarnoskórej lub do kobiety) zarządza zasób BusinessIdentity.
• Umowy dotyczące warunków korzystania z usługi to nowa funkcja zarządzana przez zasoby TermsOfService i TermsOfServiceAgreementState.

Nowe możliwości

Interfejs Merchant API wprowadza też nowe funkcje zarządzania kontem, które nie były dostępne w Content API for Shopping:

• Warunki korzystania z usługi: programowe pobieranie i akceptowanie Warunków korzystania z usługi za pomocą zasobów TermsOfService i TermsOfServiceAgreementState.
• Tworzenie kont: metoda accounts.createAndConfigure umożliwia teraz tworzenie kont z relacjami (np. accountManagement), ustawianie alias i pomijanie weryfikacji adresu e-mail za pomocą pola user.verificationMailSettings.verificationMailMode na rzecz weryfikacji opartej na interfejsie API za pomocą nowej metody accounts.verifySelf.
• Dostęp do konta za pomocą aliasu: dostęp do konta w formacie providerId~accountAlias, co zapewnia firmom zarządzającym wieloma kontami spójny sposób używania własnych identyfikatorów kont.

Żądania

Ta tabela zawiera zbiorcze porównanie adresów URL żądań dotyczących typowych zadań związanych z zarządzaniem kontem w interfejsach Content API for Shopping i Merchant API.

Opis prośby	Content API for Shopping	Merchant API
Pobierz konto	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Pobieranie konta według aliasu	Niedostępne bezpośrednio	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
Wyświetlanie listy subkont	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts
Tworzenie subkonta	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure
Aktualizowanie danych konta	PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	PATCH przy odpowiednim zasobie. Aby na przykład zaktualizować nazwę konta: PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Usuwanie subkonta	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Zgłaszanie praw do witryny	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim
Łączenie kont	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose

Zarządzanie podstawowymi informacjami o koncie

Zasób Account w Merchant API zawiera podstawowe informacje o koncie Merchant Center, takie jak nazwa, identyfikator i ustawienia podstawowe.

Porównanie żądań

Opis prośby	Content API for Shopping	Merchant API
Pobieranie szczegółów konta	GET /content/v2.1/{merchantId}/accounts/{accountId} (dostęp do podstawowych atrybutów, takich jak name, adult_content)	GET /accounts/v1/accounts/{account}
Tworzenie subkonta	POST /content/v2.1/{merchantId}/accounts	POST /accounts/v1/accounts:createAndConfigure
Aktualizowanie szczegółów konta	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aktualizowanie podstawowych atrybutów)	PATCH /accounts/v1/accounts/{account}
Usuwanie subkonta	DELETE /content/v2.1/{merchantId}/accounts/{accountId}	DELETE /accounts/v1/accounts/{account}

Szczegółowe porównanie pól

Content API for Shopping (Account)	Interfejs API sprzedawcy (Account)	Uwagi
id	account_id	Identyfikator numeryczny jest teraz polem tylko do odczytu. Podstawowym identyfikatorem jest zasób name.
name	account_name	Czytelna nazwa konta.
language	language_code	Nazwa pola to teraz language_code.

Zarządzanie informacjami o firmie

Użyj zasobu BusinessInfo do zarządzania publicznymi informacjami o firmie, takimi jak adres i dane kontaktowe obsługi klienta. Zastępuje on obiekt businessInformation w Content API for Shopping.

Porównanie żądań

Opis prośby	Content API for Shopping	Merchant API
Uzyskiwanie informacji o firmie	GET /content/v2.1/{merchantId}/accounts/{accountId} (dostęp do atrybutu business_information)	GET /accounts/v1/accounts/{account}/businessInfo
Aktualizowanie informacji o firmie	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aktualizacja atrybutu business_information)	PATCH /accounts/v1/accounts/{account}/businessInfo

Szczegółowe porównanie pól

Content API for Shopping (business_information)	Interfejs API sprzedawcy (BusinessInfo)	Uwagi
phone_number	phone	Pole ma teraz wartość phone i używa google.type.PhoneNumber.
customer_service.url	customer_service.uri	Nazwa pola to teraz uri.

Zarządzanie stroną główną

Aby zarządzać adresem URL witryny sklepu oraz przeprowadzać weryfikację i zgłaszanie praw, użyj zasobu Homepage. Zastępuje on pole websiteUrl i metodę accounts.claimwebsite z Content API for Shopping.

Porównanie żądań

Opis prośby	Content API for Shopping	Merchant API
Pobieranie adresu URL strony głównej	GET /content/v2.1/{merchantId}/accounts/{accountId} (dostęp do atrybutu website_url)	GET /accounts/v1/accounts/{account}/homepage
Aktualizacja adresu URL strony głównej	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aktualizacja atrybutu website_url)	PATCH /accounts/v1/accounts/{account}/homepage
Zgłaszanie praw do strony głównej	POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST /accounts/v1/accounts/{account}/homepage:claim
Usuwanie rezerwacji strony głównej	Niedostępne	POST /accounts/v1/accounts/{account}/homepage:unclaim

Szczegółowe porównanie pól

Content API for Shopping (Account)	Interfejs API sprzedawcy (Homepage)	Uwagi
website_url	uri	Adres URL strony głównej sklepu.
Niedostępne bezpośrednio	claimed	Pole logiczne, które przyjmuje wartość true, jeśli strona główna jest objęta roszczeniem.

Zarządzanie użytkownikami

Zasób User umożliwia zarządzanie tym, kto ma dostęp do konta Merchant Center. Zastępuje on tablicę users w zasobie Account. Kluczową różnicą jest proces tworzenia użytkownika. W Merchant API dodanie użytkownika powoduje wysłanie zaproszenia. Użytkownik musi zaakceptować zaproszenie, aby uzyskać dostęp do konta.

Porównanie żądań

Opis prośby	Content API for Shopping	Merchant API
Wyświetlenie użytkowników	GET /content/v2.1/{merchantId}/accounts/{accountId} (dostęp do atrybutu users)	GET /accounts/v1/accounts/{account}/users
Tworzenie konta użytkownika	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aktualizacja atrybutu users)	POST /accounts/v1/accounts/{account}/users
Aktualizowanie użytkownika	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aktualizacja atrybutu users)	PATCH /accounts/v1/accounts/{account}/users/{email}
Usuwanie użytkownika	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aktualizacja atrybutu users)	DELETE /accounts/v1/accounts/{account}/users/{email}

Szczegółowe porównanie pól

Content API for Shopping (users obiekt tablicy)	Interfejs Merchant API (User)	Uwagi
email_address	name (w formacie accounts/{account}/users/{email})	Adres e-mail użytkownika jest teraz częścią nazwy zasobu.
admin, order_manager, reporting_manager itp.	access_rights	Prawa dostępu są teraz scalone w powtarzane pole wyliczeniowe.
Niedostępne	state	Nowe pole tylko do odczytu wskazujące, czy użytkownik jest PENDING czy VERIFIED.

Zarządzanie relacjami między kontami i usługami

W Content API for Shopping relacje były zarządzane za pomocą znaku accounts.link. Merchant API wprowadza bardziej jednoznaczny model z zasobami AccountService i AccountRelationship, który wymaga procesu uzgadniania (proponowania i akceptowania).

Porównanie żądań

Opis prośby	Content API for Shopping	Merchant API
Łączenie kont	POST /content/v2.1/{merchantId}/accounts/{accountId}/link	POST /accounts/v1/accounts/{account}/services:propose
Wyświetlanie listy połączonych kont	GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks	GET /accounts/v1/accounts/{account}/relationships i GET /accounts/v1/accounts/{account}/services

Szczegółowe porównanie pól

Content API for Shopping (AccountLink)	Interfejs API sprzedawcy (AccountService, AccountRelationship)	Uwagi
linked_account_id	provider (w: AccountService)	Identyfikator konta, które świadczy usługę.
service	service_type (w: AccountService)	rodzaj świadczonej usługi (np. ACCOUNT_AGGREGATION).
status	handshake.approval_state (w: AccountService)	Stan linku (np. PENDING, ESTABLISHED).

Ustawienia podatkowe konta

Usługa accounttax z Content API for Shopping nie jest dostępna w Merchant API. Nie musisz już podawać podatku od sprzedaży w Stanach Zjednoczonych. Więcej informacji znajdziesz w artykule Aktualizacja specyfikacji danych produktów w Merchant Center (2025 r.).

Zarządzanie tożsamością firmy

Użyj zasobu BusinessIdentity , aby samodzielnie zadeklarować atrybuty dotyczące Twojej firmy. Zastępuje on obiekt businessIdentity w Content API for Shopping.

Porównanie żądań

Opis prośby	Content API for Shopping	Merchant API
Pobieranie tożsamości firmy	GET /content/v2.1/{merchantId}/accounts/{accountId} (dostęp do atrybutu business_identity)	GET /accounts/v1/accounts/{account}/businessIdentity
Aktualizowanie tożsamości firmy	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aktualizacja atrybutu business_identity)	PATCH /accounts/v1/accounts/{account}/businessIdentity

Szczegółowe porównanie pól

Content API for Shopping (business_identity)	Interfejs API sprzedawcy (BusinessIdentity)	Uwagi
black_owned.self_identified (wartość logiczna)	black_owned.identity_declaration (wyliczenie)	Wartość logiczna została zastąpiona wyliczeniem (SELF_IDENTIFIES_AS, DOES_NOT_SELF_IDENTIFY_AS), aby deklaracja była bardziej jednoznaczna. Dotyczy to wszystkich atrybutów tożsamości.
include_for_promotions (wartość logiczna)	promotions_consent (wyliczenie)	Globalna wartość logiczna została zastąpiona bardziej opisowym wyliczeniem (PROMOTIONS_CONSENT_GIVEN, PROMOTIONS_CONSENT_DENIED).

Wyświetlanie listy kont

W Content API for Shopping jedynym typem konta zaawansowanego było „Multikonto klientów (MCA)”, które udostępniało metodę accounts.list do wyświetlania listy kont danego multikonta klientów. Zaawansowane konta w interfejsie Merchant API są znacznie bardziej rozbudowane, co pozwala na korzystanie z szerszego zakresu typów kont i relacji. Aby umożliwić prostą migrację zaawansowanych kont, Merchant API udostępnia bezpośredni odpowiednik metody accounts.listaccounts.listSubaccounts interfejsu Content API for Shopping. Wprowadzamy nową, bardziej zaawansowaną metodę accounts.list, która umożliwia zaawansowane filtrowanie kont.

Porównanie żądań

Opis prośby	Content API for Shopping	Merchant API
Wyświetlanie listy kont na koncie zaawansowanym	GET /content/v2.1/{merchantId}/accounts	GET /accounts/v1/accounts/{providerId}:listSubaccounts
Wyświetlanie listy wszystkich dostępnych kont	Niedostępne	GET /accounts/v1/accounts

Szczegółowe porównanie pól (parametry żądania)

Content API for Shopping (accounts.list)	Interfejs API sprzedawcy (accounts.listSubaccounts)	Uwagi
merchant_id (parametr ścieżki)	provider (parametr ścieżki)	Identyfikator konta zaawansowanego w formacie accounts/{account}.
max_results	page_size	Maksymalna liczba kont do zwrócenia.