Perguntas frequentes

Esta seção aborda perguntas comuns sobre o registro de desenvolvedores 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. Registre seus dados de contato de 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ê só quiser conhecer e testar a API Merchant, use ferramentas como o Google OAuth Playground e o APIs Explorer, que não exigem registro.

Com que frequência preciso me registrar?

O registro é uma configuração única para cada projeto na nuvem do Google Cloud. Com várias contas de comerciante ou não, você realiza a operação de registro apenas uma vez, e ela se aplica a todos os usuários e contas de serviço no projeto vinculado do Google Cloud.

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

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

Recomendamos usar o endereço de e-mail corporativo de uma pessoa. Ou 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ços e informações sobre novos recursos.

Se o endereço de e-mail pertencer a um usuário na conta do Merchant Center, ele vai receber automaticamente a função 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 método registerGcp. Se você não fornecer um valor para esse campo ao se registrar, crie um usuário com a função 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 é do Google, associe-o a uma Conta do Google escolhendo a opção Usar seu e-mail atual no processo de inscrição Criar uma Conta do Google. Não é possível usar e-mails de contas de serviço porque 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 terceirizados ou agências que gerenciam várias contas de comerciante
  • Contas de serviço: para acessar sua própria conta do Merchant Center

Texto alternativo para acessibilidade

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
  • Usando uma conta de serviço como sa@project.iam.gserviceaccount.com

Se você decidir usar o OAuth:

  • Crie credenciais do OAuth no seu projeto 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 seu Merchant Center com o endereço de e-mail do desenvolvedor fornecido e a função API_DEVELOPER. Você vai receber 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 finalidades distintas no ecossistema da API Merchant:

  • E-mail de autenticação: geralmente, 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:
    • Ela existe no Merchant Center e tem a função ADMIN.
    • Um projeto do Google Cloud com a API Merchant ativada hospeda 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 contato principal para anúncios de serviços importantes 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 a função 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 tem 14 dias para aceitar o convite. A inscrição só será concluída depois que eles aceitarem o convite. No entanto, é possível fazer chamadas de API durante esse período.

Se o convite não for aceito no prazo especificado, o link vai expirar. Não é mais possível fazer chamadas da API Merchant, e você precisa 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ê é um desenvolvedor terceirizado ou uma agência que gerencia várias contas de comerciantes, registre seu projeto do Google Cloud com sua própria conta principal do Merchant Center, não com cada uma das contas dos comerciantes. Assim, você representa o desenvolvedor em 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 depende do tipo de empresa:

  • 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 de conta 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 exclusivo ou o ID de conta do grupo do CSS.
  • Agências, desenvolvedores e outros terceiros:se você é 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 conta principal do Merchant Center e peça para convertê-la em uma conta avançada.

Depois que seu projeto 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 usado 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, é possível usar o mesmo endereço de e-mail do desenvolvedor para fazer vários registros em vários projetos do Google Cloud ou várias contas do Merchant Center.

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

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

Como faço para autenticar a 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:

  • Existe como usuário no Merchant Center: o endereço de e-mail associado à Conta do Google ou à conta de serviço autenticada precisa ser adicionado como usuário na conta do Merchant Center que você está registrando.
  • Função de administrador necessária: o usuário precisa ter a função ADMIN atribuída a ele na conta específica do Merchant Center.

Ao fazer as chamadas de API:

  • Se você estiver usando chamadas diretas de API, será necessário conseguir 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 lidam com as complexidades de obter e atualizar tokens de acesso para você como parte da configuração.

O usuário autenticado 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 uma hora. No entanto, o mecanismo para conseguir 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 e receber um novo token de acesso de uma hora.

Recomendamos usar as bibliotecas oficiais do Google Auth, 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 vai receber automaticamente a função API_DEVELOPER.

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

Não. Por padrão, o usuário do Merchant Center associado ao e-mail de contato do desenvolvedor recebe a função API_DEVELOPER, que é necessária para receber notificações importantes. No entanto, ela 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 outros papéis, 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?

O papel API Developer tem direitos mínimos no Merchant Center. Se você planeja usar o e-mail de contato do desenvolvedor para autorizar chamadas à 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 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 for registrado com sua conta principal do Merchant Center, você poderá usar qualquer identidade gerenciada pelo projeto vinculado do Google Cloud usando credenciais OAuth ou contas de serviço para autorizar chamadas da API Merchant, desde que elas existam no Merchant Center e tenham a função ADMIN atribuída.

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 padrão accounts.users ou a página "Acesso e serviços" na interface do Merchant Center para adicionar ou remover usuários com a função 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 a interrupção imediata do 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 término do período de carência, as chamadas de API dos projetos associados do Google Cloud 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 associados do Google Cloud 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 foi feito for excluído?

Não exclua a conta do Merchant Center usada para o registro de desenvolvedor enquanto sua integração estiver ativa. A exclusão dessa conta interrompe imediatamente sua integração, e você não poderá mais fazer chamadas de API do projeto associado do Google Cloud.

Se for necessário excluir essa conta do Merchant Center, primeiro chame o método unregisterGcp para remover o link com segurança e só então prossiga com a exclusão do ID do Merchant Center. Se 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 exclua o 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?

Os desenvolvedores e agências terceirizados 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 na nuvem 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 padrão do Google Cloud. Você precisa registrar esse ID padrão do Google Cloud na sua conta do Merchant Center. O ID do Google Cloud é obtido 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. Para verificar qual ID do Merchant Center está registrado em um projeto na nuvem específico do Google Cloud, use o método getAccountForGcpRegistration. Para remover um link de projeto do Google Cloud da sua conta do Merchant Center, use o método unregisterGcp.