Esegui la migrazione della gestione dell'account

L'API Accounts è suddivisa in una raccolta di risorse per consentire la gestione più efficiente degli account Merchant Center con un controllo più preciso su diversi aspetti del tuo account.

Questa guida spiega le modifiche chiave e ti aiuta a eseguire la migrazione dell'integrazione esistente per la gestione degli account dall'API Content for Shopping all'API Merchant.

Da una risorsa a molte

Nell'API Content per Shopping, la risorsa Account era un oggetto monolitico contenente tutto, dal nome dell'account e dall'URL del sito web agli elenchi utenti e alle informazioni sull'attività.

L'API Merchant suddivide questa operazione in diverse risorse più piccole e mirate. Questa modifica consente chiamate API più mirate ed efficienti. Ad esempio, per aggiornare solo l'indirizzo della tua attività, ora devi inviare una richiesta PATCH alla risorsa BusinessInfo anziché aggiornare l'intero oggetto Account.

Ecco un riepilogo di come i concetti della risorsa API Content for Shopping Account vengono mappati alle nuove risorse dell'API Merchant:

• I dettagli dell'account principale (ID, nome, impostazioni dei contenuti per adulti) rimangono nella risorsa Account.
• Le informazioni sull'attività (indirizzo, numero di telefono, assistenza clienti) ora sono gestite dalla risorsa BusinessInfo.
• L'URL del sito web e la rivendicazione sono gestiti dalla risorsa Homepage.
• La gestione utenti viene gestita dalla risorsa User.
• Le relazioni tra gli account (collegamenti ad account avanzati, fornitori di terze parti e altri servizi Google) sono gestite dalle risorse AccountRelationship e AccountService.
• Gli attributi riguardanti l'identità dell'attività (ad esempio, di proprietà di persone di colore, di proprietà di donne) sono gestiti dalla risorsa BusinessIdentity.
• I contratti relativi ai Termini di servizio (TdS), una nuova funzionalità, sono gestiti dalle risorse TermsOfService e TermsOfServiceAgreementState.

Le nuove funzionalità,

L'API Merchant introduce anche nuove funzionalità per la gestione degli account che non erano disponibili nell'API Content for Shopping:

• Termini di servizio:recupera e accetta i Termini di servizio in modo programmatico utilizzando le risorse TermsOfService e TermsOfServiceAgreementState.
• Accesso all'account tramite alias:accedi agli account utilizzando un formato providerId~accountAlias, fornendo un modo coerente per le attività che gestiscono più account di utilizzare i propri identificatori di account.

Richieste

Questa tabella fornisce un confronto consolidato degli URL delle richieste per le attività comuni di gestione dell'account tra l'API Content for Shopping e l'API Merchant.

Descrizione della richiesta	API Content per Shopping	API Merchant
Recupera l'account	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Recupera l'account per alias	Non disponibile direttamente	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
Elenco dei subaccount	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}:listSubaccounts
Crea subaccount	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts	POST https://merchantapi.googleapis.com/accounts/v1/accounts:createAndConfigure
Aggiornare i dati dell'account	PUT https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	PATCH sulla risorsa appropriata. Ad esempio, per aggiornare il nome dell'account: PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Eliminare un subaccount	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}	DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Rivendica sito web	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/homepage:claim
Collega account	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId}/link	POST https://merchantapi.googleapis.com/accounts/v1/accounts/{account}/services:propose

Gestire i dati principali dell'account

La risorsa Account nell'API Merchant contiene i dettagli essenziali di un account Merchant Center, come nome, ID e impostazioni di base.

Confronto delle richieste

Descrizione della richiesta	API Content per Shopping	API Merchant
Recuperare i dettagli dell'account	GET /content/v2.1/{merchantId}/accounts/{accountId} (accesso ad attributi principali come name, adult_content)	GET /accounts/v1/accounts/{account}
Creare un subaccount	POST /content/v2.1/{merchantId}/accounts	POST /accounts/v1/accounts:createAndConfigure
Aggiornare i dettagli dell'account	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento degli attributi principali)	PATCH /accounts/v1/accounts/{account}
Eliminare un subaccount	DELETE /content/v2.1/{merchantId}/accounts/{accountId}	DELETE /accounts/v1/accounts/{account}

Confronto dettagliato dei campi

Content API for Shopping (Account)	API Merchant (Account)	Note
id	account_id	L'ID numerico è ora un campo di sola output. L'identificatore principale è la risorsa name.
name	account_name	Il nome leggibile dell'account.
language	language_code	Il nome del campo ora è language_code.

Gestire le informazioni sull'attività

Utilizza la risorsa BusinessInfo per gestire le informazioni pubbliche sulla tua attività, come l'indirizzo e i contatti dell'assistenza clienti. Sostituisce l'oggetto businessInformation nell'API Content for Shopping.

Confronto delle richieste

Descrizione della richiesta	API Content per Shopping	API Merchant
Ottenere informazioni sull'attività	GET /content/v2.1/{merchantId}/accounts/{accountId} (accesso all'attributo business_information)	GET /accounts/v1/accounts/{account}/businessInfo
Aggiornare le informazioni sull'attività	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento dell'attributo business_information)	PATCH /accounts/v1/accounts/{account}/businessInfo

Confronto dettagliato dei campi

Content API for Shopping (business_information)	API Merchant (BusinessInfo)	Note
phone_number	phone	Il campo ora è phone e utilizza google.type.PhoneNumber.
customer_service.url	customer_service.uri	Il nome del campo ora è uri.

Gestire la home page

Per gestire l'URL del sito web del tuo negozio ed eseguire la verifica e la rivendicazione, utilizza la risorsa Homepage. Questo campo sostituisce il campo websiteUrl e il metodo accounts.claimwebsite dell'API Content for Shopping.

Confronto delle richieste

Descrizione della richiesta	API Content per Shopping	API Merchant
Recuperare l'URL della home page	GET /content/v2.1/{merchantId}/accounts/{accountId} (accesso all'attributo website_url)	GET /accounts/v1/accounts/{account}/homepage
Aggiorna l'URL della home page	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento dell'attributo website_url)	PATCH /accounts/v1/accounts/{account}/homepage
Rivendica la home page	POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite	POST /accounts/v1/accounts/{account}/homepage:claim
Annulla rivendicazione della home page	Non disponibile	POST /accounts/v1/accounts/{account}/homepage:unclaim

Confronto dettagliato dei campi

Content API for Shopping (Account)	API Merchant (Homepage)	Note
website_url	uri	L'URL della home page del negozio.
Non disponibile direttamente	claimed	Un campo booleano che è true se la home page è rivendicata.

Gestisci utenti

La risorsa User ti consente di gestire chi può accedere a un account Merchant Center. Sostituisce l'array users all'interno della risorsa Account. Una differenza fondamentale è il processo di creazione degli utenti. Nell'API Merchant, l'aggiunta di un utente invia un invito. L'utente deve accettare l'invito prima di poter accedere all'account.

Confronto delle richieste

Descrizione della richiesta	API Content per Shopping	API Merchant
Elenca utenti	GET /content/v2.1/{merchantId}/accounts/{accountId} (accesso all'attributo users)	GET /accounts/v1/accounts/{account}/users
Crea un utente	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento dell'attributo users)	POST /accounts/v1/accounts/{account}/users
Aggiornare un utente	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento dell'attributo users)	PATCH /accounts/v1/accounts/{account}/users/{email}
Eliminazione di un utente	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento dell'attributo users)	DELETE /accounts/v1/accounts/{account}/users/{email}

Confronto dettagliato dei campi

API Content for Shopping (oggetto array users)	API Merchant (risorsa User)	Note
email_address	name (in formato accounts/{account}/users/{email})	L'email dell'utente ora fa parte del nome della risorsa.
admin, order_manager, reporting_manager e così via.	access_rights	I diritti di accesso sono ora consolidati in un campo enum ripetuto.
Non disponibile	state	Un nuovo campo di sola output che indica se l'utente è PENDING o VERIFIED.

Gestire le relazioni e i servizi dell'account

Nell'API Content for Shopping, le relazioni venivano gestite con accounts.link. L'API Merchant introduce un modello più esplicito con risorse AccountService e AccountRelationship, che richiede una procedura di handshake (proposta e accettazione).

Confronto delle richieste

Descrizione della richiesta	API Content per Shopping	API Merchant
Collega account	POST /content/v2.1/{merchantId}/accounts/{accountId}/link	POST /accounts/v1/accounts/{account}/services:propose
Elenca gli account collegati	GET /content/v2.1/{merchantId}/accounts/{accountId}/listlinks	GET /accounts/v1/accounts/{account}/relationships e GET /accounts/v1/accounts/{account}/services

Confronto dettagliato dei campi

Content API for Shopping (AccountLink)	API Merchant (AccountService, AccountRelationship)	Note
linked_account_id	provider (in AccountService)	L'ID dell'account che fornisce il servizio.
service	service_type (in AccountService)	Il tipo di servizio fornito (ad es. ACCOUNT_AGGREGATION).
status	handshake.approval_state (in AccountService)	Lo stato del collegamento (ad es. PENDING, ESTABLISHED).

Impostazioni fiscali dell'account

Il servizio accounttax dell'API Content for Shopping non è disponibile nell'API Merchant. Non è più necessario fornire l'imposta sulle vendite negli Stati Uniti. Per ulteriori informazioni, consulta l'aggiornamento del 2025 alla specifica dei dati di prodotto di Merchant Center.

Gestire l'identità aziendale

Utilizza la risorsa BusinessIdentity per dichiarare autonomamente gli attributi della tua attività. Questo sostituisce l'oggetto businessIdentity nell'API Content for Shopping.

Confronto delle richieste

Descrizione della richiesta	API Content per Shopping	API Merchant
Ottieni l'identità dell'attività	GET /content/v2.1/{merchantId}/accounts/{accountId} (accesso all'attributo business_identity)	GET /accounts/v1/accounts/{account}/businessIdentity
Aggiornare l'identità dell'attività	PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento dell'attributo business_identity)	PATCH /accounts/v1/accounts/{account}/businessIdentity

Confronto dettagliato dei campi

Content API for Shopping (business_identity)	API Merchant (BusinessIdentity)	Note
black_owned.self_identified (booleano)	black_owned.identity_declaration (enum)	Il valore booleano viene sostituito da un'enumerazione (SELF_IDENTIFIES_AS, DOES_NOT_SELF_IDENTIFY_AS) per una dichiarazione più esplicita. Questo vale per tutti gli attributi di identità.
include_for_promotions (booleano)	promotions_consent (enum)	Un valore booleano globale viene sostituito da un'enumerazione più descrittiva (PROMOTIONS_CONSENT_GIVEN, PROMOTIONS_CONSENT_DENIED).

Elenco account

Nell'API Content for Shopping l'unico tipo di account avanzato era un "account multi-cliente (AMC)" ed esponeva un metodo accounts.list per elencare i subaccount dell'account multi-cliente specificato. Gli account avanzati nell'API Merchant sono molto più potenti e consentono una gamma più ampia di tipi di account e relazioni. Per consentire una migrazione semplice per gli account avanzati, l'API Merchant fornisce un equivalente diretto di accounts.list dell'API Content for Shopping come metodo accounts.listSubaccounts. Stiamo introducendo un nuovo metodo accounts.list più efficace che consente il filtraggio avanzato degli account.

Confronto delle richieste

Descrizione della richiesta	API Content per Shopping	API Merchant
Elenco dei subaccount	GET /content/v2.1/{merchantId}/accounts	GET /accounts/v1/accounts/{providerId}:listSubaccounts
Elenca tutti gli account accessibili	Non disponibile	GET /accounts/v1/accounts

Confronto dettagliato dei campi (parametri della richiesta)

Content API for Shopping (accounts.list)	API Merchant (accounts.listSubaccounts)	Note
merchant_id (parametro percorso)	provider (parametro percorso)	L'ID dell'account avanzato nel formato accounts/{account}.
max_results	page_size	Il numero massimo di account da restituire.