Ao concluir a migração da Merchant API no Google Shopping passo a passo, sua equipe técnica terá substituído os endpoints legados da Content API v2.1 por uma integração modular e atualizada no Google Cloud Console. O resultado direto na operação é a manutenção ininterrupta da veiculação dos produtos em campanhas de Performance Max e Shopping, sem o risco de reprovação em massa no catálogo ou perda do histórico de vendas por falhas na comunicação com o Google Merchant Center.
A transição exige alterar a estrutura de autenticação, reescrever os payloads de envio de mercadorias e reconfigurar a leitura de diagnósticos de estoque e preço no seu ERP ou hub de integração.
Mapeamento das contas e permissões no Google Merchant Center
A etapa inicial consiste em identificar quais instâncias do seu sistema consomem a chamada antiga e validar a cadeia de acessos nas duas pontas da integração: o Google Cloud Console e o Google Merchant Center.
Para evitar falhas de autenticação no meio do processo, verifique se a conta corporativa responsável pela manutenção do e-commerce possui perfil de Administrador no Merchant Center e perfil de Proprietário ou Editor de IAM no projeto vinculado do Google Cloud Console. Sem essa correspondência exata, as chaves de API criadas nas etapas seguintes não conseguirão vincular os feeds de dados ao ID da conta de comerciante.
Em seguida, faça a varredura completa no código do seu sistema (ou na configuração da sua plataforma de e-commerce) e mapeie todas as rotas ativas que requisitam a versão v2.1 da Content API. Identifique quais credenciais atuais utilizam autenticação via OAuth 2.0 e quais utilizam Contas de Serviço (Service Accounts).
- Critério de conclusão: tabela de mapeamento preenchida e validada com os seguintes dados:
| Projeto GCP | Merchant Center ID | Tipo de Credencial | Status de Acesso Admin | Endpoint Atual |
|---|---|---|---|---|
| prj-ecommerce-prod | 123456789 | Service Account | Validado | content.googleapis.com/content/v2.1 |
| prj-ecommerce-staging | 123456789 | OAuth 2.0 Client | Validado | content.googleapis.com/content/v2.1 |
Ativação da Merchant API e geração de credenciais no Google Cloud
Com o mapeamento concluído, acesse o Google Cloud Console para ativar a nova API. Diferente da estrutura legada, a Merchant API é dividida em sub-APIs focadas em responsabilidades específicas, como gerenciamento de contas, fontes de dados e inventário local.
Dentro do seu projeto no GCP, navegue até APIs e Serviços > Biblioteca. Pesquise por "Merchant API" e selecione a opção Merchant API REST. Clique em Ativar.
Na sequência, acesse o menu IAM e Administrador > Contas de Serviço para criar a identidade de acesso da aplicação:
- Clique em Criar conta de serviço.
- Defina um nome identificável, como
merchant-api-sync-prod. - Conceda o papel de usuário da API no projeto.
- Na aba de permissões (Scopes), garanta a atribuição do escopo de gerenciamento do Shopping:
https://www.googleapis.com/auth/content. - Selecione a conta de serviço criada, vá até a aba Chaves > Adicionar Chave > Criar nova chave e selecione o formato JSON.
Após o download automático do arquivo JSON contendo a chave privada, copie o e-mail da conta de serviço gerada (formato nome@projeto.iam.gserviceaccount.com). Acesse o Google Merchant Center em Configurações > Pessoas e acesso, clique em Adicionar usuário, cole o e-mail da conta de serviço e atribua o nível de acesso Administrador.
- Critério de conclusão: arquivo de chave JSON salvo em cofre de segredos do ambiente de desenvolvimento e e-mail da Service Account ativado no painel do Merchant Center com permissão administrativa.
Ajuste do payload de produtos e substituição dos endpoints
A Merchant API altera a arquitetura das chamadas. Enquanto a Content API v2.1 concentrava operações no caminho content/v2.1/{merchantId}/products, a nova API utiliza namespaces segmentados. A documentação oficial da Merchant API REST estabelece a divisão entre recursos de contas (accounts), fontes de dados (datasources) e dados de produtos (products).
Substitua a URL base da sua aplicação. As chamadas passam a apontar para merchantapi.googleapis.com.
No payload JSON de envio, adeque os nomes dos atributos e a estrutura das propriedades obrigatórias:
- GTIN e Código MPN: devem ser enviados como atributos explícitos de identificação dentro do objeto do produto.
- Preço e Promoção: o objeto de preço exige a separação estrita da moeda ISO 4217 e do valor formatado em texto ou micros. A representação do preço em BRL deve conter o código
BRLe o valor numérico padronizado. - Atributos de localização e fiscais: inclua o código NCM nas informações técnicas personalizadas e confirme se os atributos de variação (tamanho, cor, gênero e grupo de idade) estão estruturados em formato de lista textual nativa.
Configure uma requisição de teste para inserção ou atualização de um único SKU utilizando uma ferramenta de execução de chamadas HTTP, como Postman ou via script de teste em staging.
Exemplo de chamada POST para inserção de fonte de dados de produto via Merchant API:
POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources
Header: Authorization: Bearer {ACCESS_TOKEN}
Header: Content-Type: application/json
- Critério de conclusão: envio de requisição de atualização para um lote de teste com 10 SKUs retornando código de status HTTP 200 OK ou HTTP 201 Created com o ID do recurso gerado no corpo da resposta.
Execução de testes paralelos e auditoria do diagnóstico de produtos
Não desative a sincronização via Content API v2.1 imediatamente. Execute os dois fluxos em paralelo utilizando um ambiente de staging para os envios da Merchant API enquanto a operação oficial de produção mantém o feed antigo atualizando o inventário.
Cadastre ou atualize um lote de controle com 100 SKUs variados (produtos simples, produtos com variação de tamanho/cor e produtos com regras fiscais distintas) por meio da nova API.
Após o processamento do lote, acesse o painel do Google Merchant Center e selecione Produtos > Diagnósticos. Filtre a visualização pelos dados enviados através da nova fonte de dados REST.
Audite os três pilares críticos de reprovação:
- Divergência de preço e moeda: confirmação se o valor enviado na API bate exatamente com o valor renderizado na página do produto (DOM HTML e microdados Schema.org).
- Identificadores exclusivos: verificação de erros do tipo "GTIN inválido" ou "Código de barras ausente".
- Parâmetros regionais: validação do envio correto de NCM e taxas aplicáveis ao mercado brasileiro.
Ajuste o mapeamento de dados no backend até que a aba de diagnósticos não apresente nenhum alerta bloqueante para o lote de teste.
- Critério de conclusão: relatório do painel de Diagnósticos do Merchant Center indicando 0% de erros fatais de processamento e 0% de divergências de preço/estoque no lote de 100 SKUs enviado via Merchant API.
Virada de chave oficial e desativação do feed legado
Com o lote de staging validado sem erros, agende a virada de chave para um horário de menor volume de atualizações no e-commerce, preferencialmente fora do horário de pico de vendas.
No seu servidor de aplicação ou hub de integração, altere as variáveis de ambiente para apontar a rota principal de sincronização de catálogo para a nova estrutura da Merchant API. Desative os rotinas em segundo plano (cron jobs ou workers) que executavam requisições HTTP para os endpoints da Content API v2.1.
Durante as primeiras 24 horas após a virada, monitore o comportamento da base completa de produtos:
- Verifique o log de resposta do seu backend a cada ciclo de sincronização de estoque e preço.
- Monitore a taxa de rejeição de requisições por limite de cota (rate limit).
- Acompanhe o volume total de produtos com status "Aprovado" na visão geral