Perguntas frequentes

Esta seção aborda perguntas comuns sobre o registro de desenvolvedor para a API Merchant.

Registro geral

Perguntas comuns sobre o processo de registro:

O registro de desenvolvedor é obrigatório para usar a API Merchant?

Sim. É necessário registrar as informações de contato do desenvolvedor para que o Google possa enviar atualizações importantes específicas da API, como anúncios de serviço e informações sobre novos recursos.

Se você quiser apenas explorar e testar a API Merchant, use ferramentas como o Google OAuth Playground e o API Explorer, que não exigem registro.

Com que frequência preciso me registrar?

O registro é uma configuração única para cada projeto do Google Cloud. Se você estiver trabalhando com várias contas de comerciante ou não, a operação de registro será realizada apenas uma vez e se aplicará a todos os usuários e contas de serviço no projeto do Google Cloud vinculado.

Depois que um projeto na nuvem do Google Cloud é registrado, o link permanece ativo, a menos que seja removido explicitamente chamando o unregisterGcp método. Não é possível registrar projetos compartilhados do Google, como o APIs Explorer ou o OAuth Playground.

Qual endereço de e-mail devo fornecer como contato do desenvolvedor?

Recomendamos o uso do endereço de e-mail corporativo de uma pessoa. Como alternativa, você pode usar aliases de grupo gerais. Não é possível usar e-mails de contas de serviço, já que as comunicações são destinadas a destinatários humanos. O Google envia atualizações importantes específicas da API, como anúncios de serviço e informações sobre novos recursos.

Se o endereço de e-mail pertencer a um usuário na conta do Merchant Center, ele receberá automaticamente o papel API_DEVELOPER. Caso contrário, um convite será enviado para esse endereço.

O campo de endereço de e-mail de contato do desenvolvedor é opcional no registerGcp método. Se você não fornecer um valor para esse campo ao se registrar, será necessário criar um usuário com o papel API_DEVELOPER na interface do Merchant Center ou chamando o método accounts.users.create.

O e-mail de contato do desenvolvedor precisa ser uma Conta do Google?

Sim. Para usar um e-mail que não seja do Google, associe-o a uma Conta do Google escolhendo a opção Usar seu e-mail atual no processo de inscrição para criar uma Conta do Google. Não é possível usar e-mails de contas de serviço, já que elas não podem receber e-mails.

Como faço a autenticação e a autorização para a chamada de registro?

Dois cenários de autenticação distintos estão disponíveis para a autenticação e autorização da chamada de registro, dependendo do seu caso de uso:

• OAuth 2.0: para provedores ou agências terceirizadas que gerenciam várias contas de comerciante
• Contas de serviço: para acesso à sua própria conta do Merchant Center

O diagrama anterior mostra os dois fluxos de autenticação e autorização para a chamada de registro. As opções são:

• Usar o OAuth com um endereço de e-mail, como account@email.com , associado a uma Conta do Google.
• Usar uma conta de serviço, como sa@project.iam.gserviceaccount.com.

Se você decidir usar o OAuth:

• Crie credenciais do OAuth no seu projeto na nuvem do Google Cloud para seu e-mail.
• Verifique se o endereço de e-mail de autorização existe no Merchant Center e se ele tem o tipo de acesso ADMIN.

Se você decidir usar uma conta de serviço:

• Verifique se a conta de serviço existe no seu projeto do Google Cloud.
• Verifique se o endereço de e-mail associado à conta de serviço existe no Merchant Center e se ele tem o tipo de acesso ADMIN.

Faça a chamada de registro no contexto de segurança da identidade de autenticação, usando chamadas diretas de API ou bibliotecas de cliente. Forneça um endereço de e-mail para o contato do desenvolvedor, por exemplo, developer@email.com.

Se a chamada de registro for bem-sucedida, um usuário vai existir no Merchant Center com o endereço de e-mail do desenvolvedor fornecido e o papel API_DEVELOPER. Você recebe um recurso DeveloperRegistration como resposta.

Qual é a diferença entre o e-mail de autenticação e o e-mail de contato do desenvolvedor?

Os dois endereços de e-mail têm propósitos distintos no ecossistema da API Merchant:

• E-mail de autenticação: normalmente, você usa um e-mail associado à sua Conta do Google ou a uma conta de serviço como uma identidade para autorizar solicitações à API Merchant, desde que:
  • Ele exista no Merchant Center e tenha o papel ADMIN.
  • Um projeto do Google Cloud com a API Merchant ativada hospede o cliente OAuth ou a conta de serviço associada ao e-mail que autoriza as chamadas de API.
• E-mail de contato do desenvolvedor: o e-mail de contato do desenvolvedor também precisa estar associado a uma Conta do Google, mas serve como o contato principal para anúncios de serviço críticos e atualizações de API do Google. Ele pode pertencer a um usuário ou a um grupo de usuários. Por padrão, ele recebe o papel API developer no Merchant Center.

Preciso aceitar o convite recebido pelo e-mail de contato do desenvolvedor?

Sim. O destinatário do e-mail de contato do desenvolvedor fornecido tem 14 dias para aceitar o convite. O registro só será concluído depois que ele aceitar o convite. No entanto, você pode fazer chamadas de API durante esse período.

Se o convite não for aceito no período especificado, o link do convite vai expirar. Não será mais possível fazer chamadas da API Merchant, e você terá que reiniciar o processo de registro.

Gerenciamento de contas e projetos

Perguntas comuns sobre o gerenciamento de contas e projetos:

Trabalho com várias contas do Merchant Center. Preciso registrar todas as contas do Merchant Center que quero usar com a API Merchant?

Não. Se você for um desenvolvedor terceirizado ou uma agência que gerencia várias contas de comerciantes, registre seu projeto do Google Cloud com sua conta principal do Merchant Center, não com cada uma das contas dos comerciantes. Dessa forma, você representa o desenvolvedor para todo o trabalho de API que faz para seus comerciantes.

Trabalho com várias contas do Merchant Center. Como escolho minha conta principal do Merchant Center?

A escolha da conta principal a ser usada depende do seu tipo de negócio:

• Marketplaces com uma conta avançada: se sua empresa opera como um marketplace e já tem uma conta avançada representando toda a plataforma, use esse ID da conta existente como a conta principal do Merchant Center.
• Serviços de comparação de preços (CSS) : se você for um CSS, use seu ID de conta CSS exclusivo ou o ID da conta do grupo de CSS.
• Agências, desenvolvedores e outras empresas terceirizadas: se você for uma empresa terceirizada, como uma agência ou um desenvolvedor terceirizado que gerencia várias contas de comerciante e não tem um único ID do Merchant Center representando sua empresa, crie uma nova conta principal do Merchant Center e solicite a conversão dela para uma conta avançada.

Depois que seu projeto na nuvem do Google Cloud for registrado na conta principal do Merchant Center, você poderá usar o mesmo projeto para gerenciar qualquer outra conta do Merchant Center a que tiver acesso, sem precisar registrar essas contas individualmente.

Uso vários projetos do Google Cloud. Preciso registrar cada um deles?

Sim. Como o processo de registro vincula o projeto do Google Cloud de chamada, é necessário fazer a chamada registerGcp de cada projeto do Google Cloud que você usa para fazer chamadas de API.

Um único projeto do Google Cloud só pode ser registrado em uma conta do Merchant Center por vez. No entanto, uma única conta do Merchant Center pode ter vários projetos do Google Cloud registrados nela. Da mesma forma, você pode usar o mesmo endereço de e-mail de desenvolvedor para fazer vários registros em vários projetos do Google Cloud ou em vários Merchant Centers.

O que acontece se eu registrar um projeto do Google Cloud com várias contas do Merchant Center?

A tentativa de registrar um projeto do Google Cloud que já está registrado em outra conta do Merchant Center resultará em um erro ALREADY_REGISTERED.

Como faço a autenticação da chamada de API de registro de desenvolvedor?

Para autenticar a chamada de API de registro de desenvolvedor para a API Merchant, use credenciais gerenciadas por um projeto do Google Cloud. Você tem duas opções principais para a identidade que realiza a autenticação:

• Conta do Google, como o Gmail, usando o OAuth 2.0: esse método usa credenciais de cliente do OAuth 2.0 geradas no seu projeto do Google Cloud. A chamada de API é autorizada em nome de uma Conta do Google específica em que o usuário faz login.
• Conta de serviço: esse método usa uma conta de serviço do Google Cloud, que é um tipo especial de Conta do Google destinada a aplicativos. As credenciais da conta de serviço também são gerenciadas no seu projeto do Google Cloud.

Para um registro de desenvolvedor bem-sucedido, a identidade de autenticação (Conta do Google ou conta de serviço) precisa atender aos seguintes critérios no Merchant Center:

• Existir como um usuário no Merchant Center: o endereço de e-mail associado à Conta do Google de autenticação ou à conta de serviço precisa ser adicionado como um usuário na conta do Merchant Center que você está registrando.
• Papel de administrador necessário: esse usuário precisa ter o papel ADMIN atribuído a ele nessa conta específica do Merchant Center.

Ao fazer as chamadas de API:

• Se você estiver usando chamadas diretas de API, será necessário receber e fornecer um token de acesso válido no cabeçalho Authorization. Esse token é gerado pelo fluxo do OAuth 2.0 para uma Conta do Google ou pelo fluxo de autenticação de servidor para servidor para uma conta de serviço.
• As bibliotecas de cliente fornecidas pelo Google geralmente processam as complexidades de receber e atualizar tokens de acesso como parte da configuração.

O usuário de autenticação pode não ser o mesmo que o usuário de contato do desenvolvedor. Para mais informações, consulte Qual é a diferença entre o e-mail de autenticação e o e-mail de contato do desenvolvedor?

Com que frequência preciso atualizar os tokens de acesso?

Os tokens de acesso para contas de serviço e OAuth 2.0 geralmente expiram após 1 hora. No entanto, o mecanismo para receber um novo depende do método de autenticação que você está usando:

• As contas de serviço usam uma chave privada ou credenciais de ambiente para criar um novo token de acesso sempre que necessário.
• Os fluxos do OAuth 2.0 usam um refresh_token para chamar o endpoint de token do Google OAuth2 para receber um novo token de acesso de 1 hora.

Recomendamos o uso das bibliotecas de autenticação oficiais do Google, que processam essa rotação automaticamente para que seu aplicativo nunca fique inativo.

Usuários e funções

Perguntas comuns sobre usuários e funções:

A conta de e-mail do desenvolvedor já precisa existir no Merchant Center?

Não. Se a conta de e-mail de registro ainda não existir no Merchant Center, a API Merchant vai criar a conta no Merchant Center com o e-mail especificado no status "Pendente". Se o endereço de e-mail do desenvolvedor pertencer a um usuário na conta do Merchant Center, ele receberá automaticamente o papel API_DEVELOPER.

O e-mail de contato do desenvolvedor precisa ter direitos de administrador no Merchant Center?

Não. O usuário do Merchant Center associado ao e-mail de contato do desenvolvedor recebe por padrão o papel API_DEVELOPER, que é necessário para receber notificações importantes. No entanto, ele tem permissões mínimas no Merchant Center. Para permitir que esse usuário faça outras chamadas de API ou gerencie configurações na interface do Merchant Center, conceda a ele outras funções, como STANDARD ou ADMIN. Para mais informações sobre as funções do Merchant Center, consulte Tipos de acesso.

Quais permissões a função "Desenvolvedor de API" tem?

A função API Developer é uma função com direitos mínimos no Merchant Center. Se você planeja usar o e-mail de contato do desenvolvedor para autorizar chamadas para a API Merchant, recomendamos adicionar permissões ADMIN ou STANDARD para permitir que o usuário faça chamadas de API.

Preciso registrar cada usuário de desenvolvedor ou conta de serviço que chama a API?

Não. O registro de desenvolvedor está vinculado ao projeto do Google Cloud usado para fazer as chamadas de API, não a usuários ou contas de serviço individuais. Depois que um projeto do Google Cloud é registrado com sua conta principal do Merchant Center, você pode usar qualquer identidade gerenciada pelo projeto do Google Cloud vinculado usando credenciais do OAuth ou contas de serviço para autorizar chamadas da API Merchant, desde que elas existam no Merchant Center e tenham o papel ADMIN atribuído.

Como faço para mudar o e-mail de contato do desenvolvedor após o registro inicial?

Para gerenciar ou mudar contatos, use o serviço accounts.users padrão ou a página "Acesso e serviços" na interface do Merchant Center para adicionar ou remover usuários com o papel API Developer.

O que acontece se o último usuário "Desenvolvedor de API" for removido da conta do Merchant Center?

Um período de carência de 30 dias é acionado para evitar interrupções imediatas no serviço. Durante esse período:

• Os administradores vão receber três anúncios de serviço obrigatórios por e-mail (geralmente cerca de 30, 17 e 4 dias antes do bloqueio).
• As chamadas de API vão continuar funcionando normalmente.
• Se um novo API Developer não for adicionado antes do período de carência expirar, as chamadas de API dos projetos do Google Cloud associados serão bloqueadas com um erro AUTH_GCP_NOT_REGISTERED.

Quando o período de carência de 30 dias termina, as chamadas de API dos projetos do Google Cloud associados são bloqueadas e recebem um erro AUTH_GCP_NOT_REGISTERED até que um contato de desenvolvedor válido seja restaurado.

O que acontece se o ID do Merchant Center em que o registro de desenvolvedor é feito for excluído?

Não exclua a conta do Merchant Center usada para o registro de desenvolvedor enquanto a integração estiver ativa. A exclusão dessa conta interrompe imediatamente a integração, e não será mais possível fazer chamadas de API do projeto na nuvem do Google Cloud associado.

Se você precisar excluir essa conta do Merchant Center, primeiro chame o unregisterGcp para remover o link com segurança e só então prossiga com a exclusão do ID do Merchant Center. Se você quiser continuar usando a API Merchant, registre-se com outro ID do Merchant Center logo após cancelar o registro do atual. Só então prossiga com a exclusão do ID do Merchant Center.

Casos de uso especiais

Perguntas comuns sobre casos de uso especiais:

Sou uma agência ou um desenvolvedor terceirizado que gerencia várias contas de comerciante. Qual é a melhor maneira de configurar isso?

Desenvolvedores terceirizados e agências precisam manter a própria conta principal do Merchant Center e registrar todos os projetos do Google Cloud nessa conta única e centralizada. Não registre seu projeto do Google Cloud com a conta de cada comerciante.

Como funciona o registro para o Google Apps Script?

Os Apps Scripts geralmente são executados em um projeto na nuvem padrão do Google Cloud. É necessário registrar esse ID padrão do Google Cloud com sua conta do Merchant Center. O ID do Google Cloud é recebido automaticamente pela API, então não é necessário fornecê-lo como um parâmetro.

Posso verificar se um ID do Merchant Center está registrado em um ID de projeto específico do Google Cloud?

Sim. É possível verificar qual ID do Merchant Center está registrado em um projeto específico do Google Cloud usando o getAccountForGcpRegistration. Para remover um link de projeto do Google Cloud da sua conta do Merchant Center, use o unregisterGcp.