Domande frequenti

Questa sezione risponde alle domande comuni sulla registrazione degli sviluppatori per l'API Merchant.

Registrazione generale

Domande frequenti sulla procedura di registrazione:

La registrazione dello sviluppatore è obbligatoria per utilizzare l'API Merchant?

Sì. Devi registrare i tuoi dati di contatto per sviluppatori in modo che Google possa inviare aggiornamenti importanti specifici per l'API, come annunci di servizio e informazioni sulle nuove funzionalità.

Se vuoi solo esplorare e testare l'API Merchant, puoi utilizzare strumenti come Google OAuth Playground ed Explorer API, che non richiedono la registrazione.

Con quale frequenza devo registrarmi?

La registrazione è una configurazione una tantum per ogni progetto Google Cloud. Indipendentemente dal fatto che tu stia lavorando con più account commerciante o meno, esegui l'operazione di registrazione una sola volta e questa si applica a tutti gli utenti e i service account all'interno del progetto Google Cloud collegato.

Una volta registrato correttamente un progetto Google Cloud, il link rimane attivo, a meno che non venga rimosso esplicitamente chiamando il metodo unregisterGcp. Non puoi registrare progetti condivisi di proprietà di Google, come Explorer API o OAuth Playground.

Quale indirizzo email devo fornire come contatto per gli sviluppatori?

Ti consigliamo di utilizzare l'indirizzo email aziendale di un privato. In alternativa, puoi utilizzare alias di gruppo generici. Non puoi utilizzare gli indirizzi email dei service account, poiché le comunicazioni sono destinate a destinatari umani. Google invia aggiornamenti importanti specifici per l'API, come annunci di servizio e informazioni sulle nuove funzionalità.

Se l'indirizzo email appartiene a un utente esistente nell'account Merchant Center, gli viene concesso automaticamente il ruolo API developer. In caso contrario, viene inviato un invito a quell'indirizzo.

Il campo dell'indirizzo email di contatto dello sviluppatore è facoltativo nel metodo registerGcp. Se non fornisci un valore per questo campo al momento della registrazione, devi creare un utente con il ruolo API developer nell'interfaccia utente di Merchant Center o chiamando il metodo accounts.users.create.

L'indirizzo email di contatto dello sviluppatore deve essere un Account Google?

Sì. Per utilizzare un'email non Google esistente, puoi associarla a un Account Google scegliendo l'opzione Usa il tuo indirizzo email esistente nella procedura di registrazione Crea un Account Google. Non puoi utilizzare gli indirizzi email dei service account, poiché questi ultimi non possono ricevere email.

Come faccio a eseguire l'autenticazione e l'autorizzazione per la chiamata di registrazione?

Sono disponibili due scenari di autenticazione distinti per l'autenticazione e l'autorizzazione della chiamata di registrazione, a seconda del caso d'uso:

• OAuth 2.0: per fornitori di terze parti o agenzie che gestiscono più account commerciante
• Service account: per l'accesso al tuo account Merchant Center

Il diagramma precedente mostra i due flussi di autenticazione e autorizzazione per la chiamata di registrazione. Puoi scegliere tra:

• Utilizzo di OAuth con un indirizzo email come [e-mail] associato a un Account Google
• Utilizza un service account come [e-mail]

Se decidi di utilizzare OAuth:

• Crea le credenziali OAuth nel tuo progetto Google Cloud per l'email
• Assicurati che l'indirizzo email autorizzante esista nel tuo account Merchant Center e che disponga del tipo di accesso ADMIN

Se decidi di utilizzare un service account:

• Assicurati che il service account esista nel tuo progetto Google Cloud
• Assicurati che l'indirizzo email associato al service account esista nel tuo Merchant Center e che abbia il tipo di accesso ADMIN.

Esegui la chiamata di registrazione nel contesto di sicurezza dell'identità di autenticazione, utilizzando chiamate API dirette o librerie client. Fornisci un indirizzo email per il contatto dello sviluppatore, ad esempio [e-mail].

Se la chiamata di registrazione va a buon fine, in Merchant Center esiste un utente con l'indirizzo email dello sviluppatore fornito e il ruolo API developer. Ricevi come risposta una risorsa DeveloperRegistration.

Qual è la differenza tra l'email di autenticazione e l'email di contatto dello sviluppatore?

I due indirizzi email hanno scopi diversi all'interno dell'ecosistema dell'API Merchant:

• Email di autenticazione: in genere utilizzi un'email associata al tuo Account Google o a un service account come identità per autorizzare le richieste all'API Merchant, a condizione che:
  • Esiste nel tuo account Merchant Center e ha il ruolo ADMIN.
  • Un progetto Google Cloud con l'API Merchant abilitata ospita il client OAuth o il service account associato all'indirizzo email che autorizza le chiamate API.
• Email di contatto dello sviluppatore: anche l'email di contatto dello sviluppatore deve essere associata a un Account Google, ma funge da contatto principale per gli annunci di servizio critici e gli aggiornamenti delle API di Google. Può appartenere a un utente o a un gruppo di utenti. Per impostazione predefinita, riceve il ruolo API developer in Merchant Center.

Nota: puoi utilizzare l'indirizzo email di contatto dello sviluppatore per autorizzare le chiamate all'API Merchant tramite OAuth 2.0, a condizione che all'utente associato venga assegnato il ruolo ADMIN in Merchant Center.

Devo accettare l'invito ricevuto all'indirizzo email di contatto dello sviluppatore?

Sì. Il destinatario dell'email di contatto dello sviluppatore che fornisci ha 14 giorni di tempo per accettare l'invito. La registrazione è completa solo dopo che l'invito è stato accettato. Tuttavia, durante questo periodo puoi eseguire chiamate API.

Se l'invito non viene accettato entro il periodo di tempo specificato, il link di invito scade. Non puoi più eseguire chiamate API Merchant e devi riavviare la procedura di registrazione.

Perché la mia registrazione come sviluppatore non va a buon fine e viene visualizzato un errore relativo all'account di test?

La registrazione degli sviluppatori è limitata agli account di produzione (live) per garantire la stabilità dell'integrazione. Se utilizzi un account creato appositamente per i test e contrassegnato come "account di prova" in Merchant Center, la registrazione verrà rifiutata.

Posso registrare un subaccount che gestisco per un cliente?

Ti consigliamo vivamente di registrare l'account che rappresenta l'identità della tua attività. La registrazione di un subaccount di un cliente non è consentita ed è soggetta a errori; se il cliente abbandona il tuo servizio o elimina l'account, l'intera integrazione API potrebbe essere disattivata.

Il mio sito web deve essere rivendicato o solo verificato?

Per la registrazione degli sviluppatori, il sito web deve essere verificato. In questo modo dimostri di avere il controllo amministrativo sul sito associato all'account. Mentre la rivendicazione è obbligatoria per altre funzionalità, come gli annunci Shopping, la verifica è il requisito principale per la registrazione dell'API.

Gestione di account e progetti

Domande frequenti sulla gestione di account e progetti:

Lavoro con più account Merchant Center. Devo registrare ogni account Merchant Center che voglio utilizzare con l'API Merchant?

No. Se sei uno sviluppatore di terze parti o un'agenzia che gestisce più account di commercianti, devi registrare il tuo progetto Google Cloud con il tuo account Merchant Center principale, non con ciascuno degli account dei tuoi commercianti. In questo modo, rappresenti lo sviluppatore per tutto il lavoro relativo all'API che svolgi per i tuoi commercianti.

Lavoro con più account Merchant Center. Come faccio a scegliere il mio account Merchant Center principale?

La scelta dell'account principale da utilizzare dipende dal tipo di attività:

• Marketplace con un account avanzato esistente: se la tua attività opera come marketplace e dispone già di un account avanzato che rappresenta l'intera piattaforma, utilizza questo ID account esistente come account Merchant Center principale.
• Servizi di shopping comparativo (CSS): se sei un CSS, utilizza l'ID account CSS o l'ID account del gruppo di CSS univoco.
• Agenzie, sviluppatori e altre terze parti: se sei un'attività di terze parti, ad esempio un'agenzia o uno sviluppatore di terze parti che gestisce più account commerciante e non disponi di un unico ID Merchant Center che rappresenti la tua attività, devi creare un nuovo account Merchant Center principale e richiedere la conversione in un account avanzato.

Una volta registrato il progetto Google Cloud nel tuo account Merchant Center principale, puoi utilizzarlo per gestire qualsiasi altro account Merchant Center a cui hai accesso, senza dover registrare questi account singolarmente.

Utilizzo più progetti Google Cloud. Devo registrarli tutti?

Sì. Poiché la procedura di registrazione collega il progetto Google Cloud chiamante, devi eseguire la chiamata registerGcp da ogni progetto Google Cloud che utilizzi per effettuare chiamate API.

Un singolo progetto Google Cloud può essere registrato solo per un account Merchant Center alla volta. Tuttavia, a un singolo account Merchant Center possono essere registrati più progetti Google Cloud. Analogamente, puoi utilizzare lo stesso indirizzo email dello sviluppatore per eseguire più registrazioni in più progetti Google Cloud o più account Merchant Center.

Che cosa succede se registro un progetto Google Cloud con più account Merchant Center?

Se provi a registrare un progetto Google Cloud già registrato con un altro account Merchant Center, verrà generato un errore ALREADY_REGISTERED.

Come faccio ad autenticare la chiamata API di registrazione dello sviluppatore?

Per autenticare la chiamata API di registrazione dello sviluppatore per l'API Merchant, utilizza le credenziali gestite tramite un progetto Google Cloud. Hai due opzioni principali per l'identità che esegue l'autenticazione:

• Account Google come Gmail che utilizza OAuth 2.0: questo metodo utilizza le credenziali client OAuth 2.0 generate all'interno del tuo progetto Google Cloud. La chiamata API è autorizzata per conto di un Account Google specifico a cui l'utente accede.
• Service account: questo metodo utilizza un service account Google Cloud, ovvero un tipo speciale di Account Google destinato alle applicazioni. Anche le credenziali per il service account vengono gestite all'interno del tuo progetto Google Cloud.

Per una registrazione corretta dello sviluppatore, l'identità di autenticazione (Account Google o account di servizio) deve soddisfare i seguenti criteri in Merchant Center:

• Esiste come utente in Merchant Center: l'indirizzo email associato all'Account Google di autenticazione o al service account deve essere aggiunto come utente nell'account Merchant Center che stai registrando.
• Ruolo di amministratore richiesto: a questo utente deve essere assegnato il ruolo ADMIN all'interno di quell'account Merchant Center specifico.

Quando effettui le chiamate API:

• Se utilizzi le chiamate API dirette, devi ottenere e fornire un token di accesso valido nell'intestazione Authorization. Questo token viene generato dal flusso OAuth 2.0 per un Account Google o dal flusso di autenticazione server-to-server per un service account.
• Le librerie client fornite da Google in genere gestiscono le complessità dell'acquisizione e dell'aggiornamento dei token di accesso per te nell'ambito della loro configurazione.

L'utente che esegue l'autenticazione potrebbe non essere lo stesso dell'utente di contatto dello sviluppatore. Per maggiori informazioni, consulta Qual è la differenza tra l'email di autenticazione e l'email di contatto per gli sviluppatori?

Con quale frequenza devo aggiornare i token di accesso?

I token di accesso per i service account e OAuth 2.0 in genere scadono dopo un'ora. Tuttavia, il meccanismo per ottenerne uno nuovo dipende dal metodo di autenticazione che utilizzi:

• I service account utilizzano una chiave privata o credenziali dell'ambiente per creare un nuovo token di accesso ogni volta che è necessario.
• I flussi OAuth 2.0 utilizzano un refresh_token per chiamare l'endpoint token Google OAuth2 e ricevere un nuovo token di accesso di un'ora.

Ti consigliamo vivamente di utilizzare le librerie di autenticazione Google ufficiali che gestiscono questa rotazione automaticamente, in modo che la tua applicazione non subisca mai tempi di inattività.

Utenti e ruoli

Domande frequenti su utenti e ruoli:

L'account email dello sviluppatore deve già esistere in Merchant Center?

No. Se l'account email di registrazione non esiste già in Merchant Center, l'API Merchant crea l'account in Merchant Center con l'indirizzo email specificato in stato In attesa. Se l'indirizzo email dello sviluppatore appartiene a un utente esistente nell'account Merchant Center, gli viene concesso automaticamente il ruolo API developer.

L'email di contatto dello sviluppatore deve disporre dei diritti di amministratore in Merchant Center?

No. L'utente di Merchant Center associato all'indirizzo email di contatto dello sviluppatore riceve per impostazione predefinita il ruolo API developer, necessario per ricevere notifiche importanti. Tuttavia, dispone di autorizzazioni minime all'interno di Merchant Center. Per consentire a questo utente di effettuare altre chiamate API o gestire le impostazioni nell'interfaccia utente di Merchant Center, devi concedergli ruoli aggiuntivi, ad esempio STANDARD o ADMIN. Per saperne di più sui ruoli di Merchant Center, consulta Tipi di accesso.

Quali autorizzazioni ha il ruolo "API developer"?

Il ruolo API developer è un ruolo con diritti minimi in Merchant Center. Se prevedi di utilizzare l'indirizzo email di contatto dello sviluppatore per autorizzare le chiamate all'API Merchant, ti consigliamo di aggiungere le autorizzazioni ADMIN o STANDARD per consentire all'utente di eseguire chiamate API.

Devo registrare ogni utente sviluppatore o account di servizio che chiama l'API?

No. La registrazione dello sviluppatore è legata al progetto Google Cloud utilizzato per effettuare le chiamate API, non ai singoli utenti o service account. Una volta registrato correttamente un progetto Google Cloud nel tuo account Merchant Center principale, puoi utilizzare qualsiasi identità gestita tramite il progetto Google Cloud collegato utilizzando le credenziali OAuth o gli account di servizio per autorizzare le chiamate all'API Merchant, a condizione che esistano nel tuo Merchant Center e che abbiano il ruolo ADMIN assegnato.

Come faccio a modificare l'indirizzo email di contatto dello sviluppatore dopo la registrazione iniziale?

Per gestire o modificare i contatti, utilizza il servizio standard accounts.users o la pagina "Accesso e servizi" nell'interfaccia utente di Merchant Center per aggiungere o rimuovere utenti con il ruolo API developer.

Che cosa succede se l'ultimo utente "API developer" viene rimosso dall'account Merchant Center?

Viene attivato un periodo di tolleranza di 30 giorni per evitare l'interruzione immediata del servizio. Durante questo periodo:

• Gli amministratori riceveranno tre annunci di servizio obbligatori via email (di solito circa 30, 17 e 4 giorni prima del blocco).
• Le chiamate API continueranno a funzionare normalmente.
• Se non viene aggiunto un nuovo API developer prima della scadenza del periodo di tolleranza, le chiamate API dai progetti Google Cloud associati verranno bloccate con un errore AUTH_GCP_NOT_REGISTERED.

Al termine del periodo di tolleranza di 30 giorni, le chiamate API dai progetti Google Cloud associati vengono bloccate e viene visualizzato un errore AUTH_GCP_NOT_REGISTERED finché non viene ripristinato un contatto sviluppatore valido.

Che cosa succede se l'ID Merchant Center con cui viene eseguita la registrazione dello sviluppatore viene eliminato?

Non eliminare l'account Merchant Center utilizzato per la registrazione dello sviluppatore mentre l'integrazione è attiva. L'eliminazione di questo account interrompe immediatamente l'integrazione e non potrai più eseguire chiamate API dal progetto Google Cloud associato.

Se devi eliminare l'account Merchant Center, devi prima chiamare il metodo unregisterGcp per rimuovere il collegamento in modo sicuro e solo successivamente procedere con l'eliminazione dell'ID Merchant Center. Se vuoi continuare a utilizzare l'API Merchant, devi registrarti con un altro ID Merchant Center subito dopo aver annullato la registrazione di quello attuale. Solo allora procedi con l'eliminazione dell'ID Merchant Center.

Perché non riesco a visualizzare il ruolo "API developer" in Merchant Center?

Il ruolo API developer è visibile nell'interfaccia utente di Merchant Center solo dopo che è stata eseguita la registrazione dello sviluppatore per l'account Merchant Center in questione. Gli account Merchant Center senza registrazioni non vedono il ruolo API developer.

Casi d'uso speciali

Domande comuni sui casi d'uso speciali:

Sono un'agenzia o uno sviluppatore di terze parti che gestisce più account commerciante. Qual è il modo migliore per configurare questa soluzione?

Gli sviluppatori e le agenzie di terze parti devono mantenere il proprio account Merchant Center principale e registrare tutti i propri progetti Google Cloud in questo singolo account centralizzato. Non registrare il tuo progetto Google Cloud con l'account di ogni singolo commerciante.

Come funziona la registrazione per Google Apps Script?

Gli script di app vengono solitamente eseguiti su un progetto Google Cloud predefinito. Devi registrare questo ID Google Cloud predefinito nel tuo account Merchant Center. L'ID Google Cloud viene ottenuto automaticamente dall'API, quindi non è necessario fornirlo come parametro.

Posso verificare se un ID Merchant Center è registrato per un ID progetto Google Cloud specifico?

Sì. Puoi verificare quale ID Merchant Center è registrato per un progetto Google Cloud specifico utilizzando il metodo getAccountForGcpRegistration. Per rimuovere un link di un progetto Google Cloud al tuo account Merchant Center, utilizza il metodo unregisterGcp.

Migrazione dall'API Content all'API Merchant per gli utenti dell'app Google & YouTube su Shopify

Domande comuni sulla migrazione dall'API Content all'API Merchant per piattaforme e app di terze parti:

Devo fare qualcosa per eseguire la migrazione dall'API Content all'API Merchant?

Nessuna azione richiesta. Se utilizzi l'app Google & YouTube su Shopify per gestire i tuoi feed di Merchant Center, la migrazione dall'API Content all'API Merchant verrà gestita da Google.

La migrazione modificherà i miei ID prodotto?

No, la migrazione non modifica gli ID prodotto nei feed di Merchant Center.

Devo reinstallare l'app Google & YouTube su Shopify per completare la transizione?

Non è necessario alcun intervento da parte tua per completare la transizione. Non è necessario reinstallare l'app Google & YouTube.

Perché trovo ancora origini dati dell'API Content in Merchant Center?

Le origini dati dell'API Content potrebbero essere ancora visualizzate in Merchant Center durante la transizione all'API Merchant. Queste istanze sono previste e non richiedono alcun intervento da parte tua.