Domande frequenti

Questa sezione risponde alle domande frequenti relative alla 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 dati di contatto dello sviluppatore in modo che Google possa inviare aggiornamenti importanti specifici per le 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, esegui l'operazione di registrazione una sola volta e questa si applica a tutti gli utenti e ai service account all'interno del progetto Google Cloud collegato.

Una volta registrato correttamente un progetto Google Cloud, il collegamento 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 dello sviluppatore?

Ti consigliamo di utilizzare l'indirizzo email aziendale di una persona. In alternativa, puoi utilizzare alias di gruppo generici. Non puoi utilizzare le email dei service account, in quanto le comunicazioni sono destinate a destinatari umani. Google invia aggiornamenti importanti specifici per le API, ad esempio annunci di servizio e informazioni sulle nuove funzionalità.

Se l'indirizzo email appartiene a un utente esistente nell'account Merchant Center, gli viene assegnato 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 al momento della registrazione non fornisci un valore per questo campo, devi creare un utente con il ruolo API_DEVELOPER nell'interfaccia utente di Merchant Center o chiamando il metodo accounts.users.create.

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

Sì. Per utilizzare un indirizzo email non Google esistente, puoi associarlo a un Account Google scegliendo l'opzione Usa il tuo indirizzo email esistente nella procedura di registrazione Crea un Account Google. Non puoi utilizzare le email dei service account perché non possono ricevere email.

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

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

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

Testo alternativo per l'accessibilità

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 service account 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 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 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 ha esito positivo, in Merchant Center esiste un utente con l'indirizzo email dello sviluppatore fornito e il ruolo API_DEVELOPER. Come risposta ricevi una risorsa DeveloperRegistration.

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

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

  • Autenticazione 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:
    • Esiste in 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'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 annunci di servizio critici e aggiornamenti delle API da parte di Google. Può appartenere a un utente o a un gruppo di utenti. Per impostazione predefinita, ottiene il ruolo API developer in Merchant Center.

Devo accettare l'invito ricevuto dall'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 viene completata solo dopo che l'utente 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 relativo link scade. Non puoi più eseguire chiamate API Merchant e devi riavviare la procedura di registrazione.

Gestione di account e progetti

Domande frequenti sulla gestione dell'account e dei 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 commerciante, registra 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 con le 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 il tuo ID account CSS univoco o l'ID account gruppo CSS.
  • 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 dispone di un singolo 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 utilizzare lo stesso progetto 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 a 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 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?

Il tentativo di registrare un progetto Google Cloud già registrato con un altro account Merchant Center genererà un errore ALREADY_REGISTERED.

Come faccio ad autenticare la chiamata API di registrazione sviluppatore?

Per autenticare la chiamata API di registrazione 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 viene autorizzata per conto di un Account Google specifico a cui l'utente accede.
  • Service Account: questo metodo utilizza un service account Google Cloud, un tipo speciale di Account Google destinato alle applicazioni. Anche le credenziali del service account sono gestite all'interno del tuo progetto Google Cloud.

Per una registrazione 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 all'Account Google di autenticazione o al service account deve essere aggiunto come utente nell'account Merchant Center che stai registrando.
  • Ruolo amministrativo richiesto: a questo utente deve essere assegnato il ruolo ADMIN all'interno di questo specifico account Merchant Center.

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 account di servizio.
  • Le librerie client fornite da Google in genere gestiscono le complessità dell'ottenimento 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, vedi Qual è la differenza tra l'email di autenticazione e l'email di contatto dello sviluppatore?

Con quale frequenza devo aggiornare i token di accesso?

I token di accesso per i service account e OAuth 2.0 scadono in genere dopo 1 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 1 ora.

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

Utenti e ruoli

Domande comuni 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 con 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 Merchant Center associato all'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, come STANDARD o ADMIN. Per saperne di più sui ruoli di Merchant Center, consulta la sezione 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 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 service account che chiama l'API?

No. La registrazione dello sviluppatore è associata al progetto Google Cloud utilizzato per effettuare le chiamate API, non a singoli utenti o service account. 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 API Merchant, a condizione che esistano in 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 "Sviluppatore API" 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 a cui è stata 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 metodo unregisterGcp per rimuovere in sicurezza il collegamento 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 a questo punto procedi con l'eliminazione dell'ID Merchant Center.

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 configurarlo?

Gli sviluppatori e le agenzie di terze parti devono gestire il proprio account Merchant Center principale e registrare tutti i propri progetti Google Cloud in questo unico 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 app vengono in genere eseguiti su un progetto Google 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 è necessario fornirlo come parametro.

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

Sì. Puoi controllare quale ID Merchant Center è registrato a un progetto Google Cloud specifico utilizzando il metodo getAccountForGcpRegistration. Per rimuovere un collegamento del progetto Google Cloud al tuo account Merchant Center, utilizza il metodo unregisterGcp.