Esegui la migrazione della gestione dell'account

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

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

Da una risorsa a molte

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

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

Di seguito è riportato un riepilogo della mappatura dei concetti della risorsa Account dell'API Content for Shopping alle nuove risorse dell'API Merchant:

Le nuove funzionalità,

L'API Merchant introduce anche nuove funzionalità per la gestione dell'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.
  • Creazione di account: il metodo accounts.createAndConfigure ora supporta la creazione di account con relazioni (come accountManagement), l'impostazione di un alias e la soppressione della verifica email utilizzando il campo user.verificationMailSettings.verificationMailMode a favore della verifica basata su API utilizzando il nuovo metodo accounts.verifySelf.
  • Accesso all'account tramite alias: accedi agli account utilizzando un formato providerId~accountAlias, che offre alle aziende che gestiscono più account un modo coerente per utilizzare i propri identificatori di account.

Richieste

Questa tabella fornisce un confronto consolidato degli URL di richiesta 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 tramite alias Non direttamente disponibile GET https://merchantapi.googleapis.com/accounts/v1/accounts/{provider}~{alias}
Elenca i 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
Aggiorna 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}
Elimina subaccount DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/accounts/{accountId} DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{account}
Rivendica il 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

Gestisci i dati principali dell'account

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

Richiedi un confronto

Descrizione della richiesta API Content per Shopping API Merchant
Recupera 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
Aggiorna i dettagli dell'account PUT /content/v2.1/{merchantId}/accounts/{accountId} (aggiornamento degli attributi principali) PATCH /accounts/v1/accounts/{account}
Elimina un subaccount DELETE /content/v2.1/{merchantId}/accounts/{accountId} DELETE /accounts/v1/accounts/{account}

Confronto dettagliato dei campi

API Content for Shopping (Account) API Merchant (Account) Note
id account_id L'ID numerico è ora un campo di solo 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.

Gestisci 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. Questo sostituisce l'oggetto businessInformation nell'API Content for Shopping.

Richiedi un confronto

Descrizione della richiesta API Content per Shopping API Merchant
Ottieni informazioni sull'attività GET /content/v2.1/{merchantId}/accounts/{accountId} (accesso all'attributo business_information) GET /accounts/v1/accounts/{account}/businessInfo
Aggiorna 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

API Content 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.

Gestisci la tua home page

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

Richiedi un confronto

Descrizione della richiesta API Content per Shopping API Merchant
Ottieni 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
Home page di rivendicazione POST /content/v2.1/{merchantId}/accounts/{accountId}/claimwebsite POST /accounts/v1/accounts/{account}/homepage:claim
Annulla la rivendicazione della home page Non disponibile POST /accounts/v1/accounts/{account}/homepage:unclaim

Confronto dettagliato dei campi

API Content for Shopping (Account) API Merchant (Homepage) Note
website_url uri L'URL della home page del negozio.
Non direttamente disponibile 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. In questo modo, l'array users viene sostituito all'interno della risorsa Account. Una differenza fondamentale è il processo di creazione degli utenti. Nell'API Merchant, l'aggiunta di un utente comporta l'invio di un invito. L'utente deve accettare l'invito prima di poter accedere all'account.

Richiedi un confronto

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
Aggiorna 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 (nel formato accounts/{account}/users/{email}) L'indirizzo 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 solo 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 le risorse AccountService e AccountRelationship, che richiede un processo di handshake (proposta e accettazione).

Richiedi un confronto

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
Elenco degli 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

API Content 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 link (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 saperne di più, consulta l'aggiornamento del 2025 alla specifica dei dati di prodotto di Merchant Center.

Gestisci l'identità dell'attività

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

Richiedi un confronto

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
Aggiorna 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

API Content 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 enum (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 enum più descrittivo (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 gli account 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 un filtro avanzato degli account.

Richiedi un confronto

Descrizione della richiesta API Content per Shopping API Merchant
Elenca gli account di un account avanzato 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 di richiesta)

API Content for Shopping (accounts.list) API Merchant (accounts.listSubaccounts) Note
merchant_id (parametro di percorso) provider (parametro di percorso) L'ID dell'account avanzato nel formato accounts/{account}.
max_results page_size Il numero massimo di account da restituire.
Indietro
Refactor code for concurrent requests
Avanti
Migrate accountstatuses to Account Issues