Domande frequenti

Questa sezione risponde alle domande frequenti sulla registrazione dello sviluppatore 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 dati di contatto dello sviluppatore 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. Che tu stia lavorando con più account commerciante o meno, esegui l'operazione di registrazione una sola volta e si applica a tutti gli utenti e i service account all'interno del progetto Google Cloud collegato.

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

Quale indirizzo email devo fornire come contatto dello sviluppatore?

Ti consigliamo di utilizzare l'indirizzo email aziendale di una persona. In alternativa, puoi utilizzare gli alias di gruppo generali. Non puoi utilizzare le email degli account di servizio, 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 automaticamente assegnato il ruolo API_DEVELOPER. In caso contrario, viene inviato un invito a questo indirizzo.

Il campo dell'indirizzo email del contatto dello sviluppatore è facoltativo nel metodo registerGcp. Se non fornisci un valore per questo campo durante la registrazione, devi creare un utente con il ruolo API_DEVELOPERnell'interfaccia utente di Merchant Center o chiamando il metodo accounts.users.create.

L'indirizzo email del 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 Utilizza la tua email esistente nella procedura di registrazione Crea un Account Google. Non puoi utilizzare le email degli account di servizio perché questi 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
• Account di servizio: 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 account@email.com associato a un Account Google
• Utilizzo di un account di servizio come sa@project.iam.gserviceaccount.com

Se decidi di utilizzare OAuth:

• Crea le credenziali OAuth nel tuo progetto Google Cloud per la tua email
• Assicurati che l'indirizzo email di autorizzazione esista in Merchant Center e che abbia il tipo di accesso ADMIN

Se decidi di utilizzare un account di servizio:

• Assicurati che l'account di servizio esista nel tuo progetto Google Cloud
• Assicurati che l'indirizzo email associato all'account di servizio esista in 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 developer@email.com.

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 del contatto dello sviluppatore?

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

• Autenticazione dell'email: in genere utilizzi un'email associata al tuo Account Google o a un account di servizio come identità per autorizzare le richieste all'API Merchant, a condizione che:
  • Esista in Merchant Center e abbia il ruolo ADMIN.
  • Un progetto Google Cloud con l'API Merchant abilitata ospita il client OAuth o l'account di servizio associato all'email che autorizza le chiamate API.
• Email del contatto dello sviluppatore: anche l'email del 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.

Devo accettare l'invito ricevuto dall'indirizzo email del contatto dello sviluppatore?

Sì. Il destinatario dell'indirizzo email del contatto dello sviluppatore fornito ha 14 giorni di tempo per accettare l'invito. La registrazione viene completata solo dopo che il destinatario ha accettato l'invito. Tuttavia, puoi effettuare chiamate API durante questo periodo.

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

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 gli account di più commercianti, registra il tuo progetto Google Cloud con il tuo account Merchant Center principale, non con gli account di ogni commerciante. In questo modo, rappresenti lo sviluppatore per tutto il lavoro 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 ha già un account avanzato che rappresenta l'intera piattaforma, utilizza questo ID account esistente come account Merchant Center principale.
• Servizi di confronto acquisti (CSS) : se sei un CSS, utilizza il tuo ID account CSS univoco o l'ID account gruppo di CSS.
• Agenzie, sviluppatori e altre terze parti: se sei un'attività di terze parti, come un' agenzia o uno sviluppatore di terze parti, che gestisce più account commerciante e non dispone di un singolo ID Merchant Center che rappresenta la tua attività, devi creare un nuovo account Merchant Center principale e richiedere la conversione in un account avanzato.

Una volta registrato il tuo progetto Google Cloud nel tuo account Merchant Center principale, puoi utilizzare lo stesso progetto per gestire qualsiasi altro account Merchant Center a cui hai accesso, senza dover registrare gli 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 in un solo account Merchant Center alla volta. Tuttavia, un singolo account Merchant Center può avere più progetti Google Cloud registrati. Allo stesso modo, puoi utilizzare lo stesso indirizzo email dello sviluppatore per eseguire più registrazioni in più progetti Google Cloud o più Merchant Center.

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

Se tenti di registrare un progetto Google Cloud già registrato con un altro account Merchant Center, viene 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, utilizzi le credenziali gestite tramite un progetto Google Cloud. Hai due opzioni principali per l'identità che esegue l'autenticazione:

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

Per una registrazione dello sviluppatore riuscita, 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 a l'Account Google o all'account di servizio di autenticazione deve essere aggiunto come utente nell'account Merchant Center che stai registrando.
• Ruolo Amministratore obbligatorio: a questo utente deve essere assegnato il ruolo ADMIN all'interno di questo account Merchant Center specifico.

Quando effettui le chiamate API:

• Se utilizzi 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 da server a server per un account di servizio.
• Le librerie client fornite da Google in genere gestiscono le complessità dell'ottenimento e dell'aggiornamento dei token di accesso come parte della loro configurazione.

L'utente di autenticazione potrebbe non essere lo stesso dell'utente del contatto dello sviluppatore. Per ulteriori informazioni, vedi Qual è la differenza tra l'email di autenticazione e l'email del contatto dello sviluppatore?

Con quale frequenza devo aggiornare i token di accesso?

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

• Gli account di servizio 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 del token Google OAuth2 per ricevere un nuovo token di accesso di 1 ora.

Ti consigliamo vivamente di utilizzare le librerie di autenticazione Google ufficiali che gestiscono automaticamente questa rotazione, 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'email specificata nello stato In attesa. Se l'indirizzo email dello sviluppatore appartiene a un utente esistente nell'account Merchant Center, gli viene automaticamente assegnato il ruolo API_DEVELOPER.

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

No. L'utente di Merchant Center associato all'indirizzo email del contatto dello sviluppatore riceve per impostazione predefinita il ruolo API_DEVELOPER necessario per ricevere notifiche importanti. Tuttavia, dispone di autorizzazioni minime in 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, come STANDARD o ADMIN. Per ulteriori informazioni sui ruoli di Merchant Center, vedi Tipi di accesso.

Quali autorizzazioni ha il ruolo "Sviluppatore API"?

Il ruolo API Developer è un ruolo con diritti minimi in Merchant Center. Se prevedi di utilizzare l'indirizzo email del contatto dello sviluppatore per autorizzare le chiamate all'API Merchant, ti consigliamo di aggiungere le autorizzazioni ADMIN o STANDARD per consentire all'utente di effettuare 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 account di servizio. Una volta registrato correttamente un progetto Google Cloud con il 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 in Merchant Center e che abbiano il ruolo ADMIN assegnato.

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

Per gestire o modificare i contatti, utilizza il servizio accounts.users standard 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 "Sviluppatore API" viene rimosso dall'account Merchant Center?

Viene attivato un periodo di tolleranza di 30 giorni per evitare interruzioni immediate 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 dello sviluppatore valido.

Che cosa succede se l'ID Merchant Center in 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ù effettuare chiamate API dal progetto Google Cloud associato.

Se devi eliminare l'account Merchant Center, devi prima chiamare il unregisterGcp per rimuovere in sicurezza il link e solo dopo 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 dopo procedi con l'eliminazione dell'ID Merchant Center.

Casi d'uso speciali

Domande frequenti 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 opzione?

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

Come funziona la registrazione per Google App Script?

Gli script delle app in genere vengono eseguiti su un progetto cloud predefinito. Devi registrare questo ID Google Cloud predefinito con il tuo account Merchant Center. L'ID Google Cloud viene ottenuto automaticamente dall'API, quindi non devi fornirlo come parametro.

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

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