API do Perfil da Empresa: como automatizar o pedido e a gestão de avaliações

O que é a API do Perfil da Empresa?

É o conjunto de APIs do Google que permite ler e gerenciar Perfis da Empresa por código: dados dos locais, avaliações, respostas e notificações. Em inglês, Google Business Profile API, o antigo Google My Business API.

Para um único perfil, o painel do Google resolve quase tudo. A API passa a valer a pena quando:

• Você gerencia muitos locais, como uma rede de lojas, franquias ou os clientes de uma agência.
• Você quer integrar o Perfil da Empresa ao seu sistema, como o ERP, o CRM ou a plataforma de atendimento.
• Você quer automatizar a rotina de avaliações: mandar o link certo para cada cliente, saber na hora quando chega uma avaliação e acompanhar a nota ao longo do tempo.

Ela não é uma API única. São várias, cada uma com uma parte do trabalho:

Como conseguir acesso à API?

Crie um projeto no Google Cloud e envie o pedido de acesso básico pelo formulário da API, com um perfil verificado e ativo há mais de 60 dias. Sem aprovação, a API não responde: a cota fica em 0 consultas por minuto.

Os requisitos, segundo a documentação do Google:

O passo a passo:

1. Crie um projeto no Google Cloud Console e anote o número do projeto, que aparece no painel.
2. Envie o formulário de contato da API do Perfil da Empresa, escolhendo "Application for Basic API Access".
3. Aguarde o e-mail com a resposta. Se for recusado, ajuste o que faltou e envie de novo.
4. Confira a cota em APIs e serviços > Cotas, no Google Cloud: 0 QPM significa que ainda não foi aprovado; 300 QPM, que está liberado.

Se o perfil ainda não está verificado, comece pelo guia de verificação do Perfil da Empresa. Os 60 dias contam a partir daí.

Como configurar o projeto?

Habilite as APIs, crie uma credencial OAuth e autorize com o escopo business.manage. A API age em nome de uma pessoa com acesso ao perfil, então a autenticação é por OAuth, e não só por chave de API.

1. Habilite as quatro APIs da tabela acima em APIs e serviços > Biblioteca.
2. Configure a tela de consentimento OAuth do projeto.
3. Crie um ID do cliente OAuth (aplicativo da Web ou de computador).
4. Autorize uma vez com a conta que administra os perfis, pedindo o escopo https://www.googleapis.com/auth/business.manage.
5. Guarde o refresh token em um cofre de segredos. É com ele que o sistema gera novos tokens de acesso sem pedir login de novo.

Como pegar o link de avaliação de cada local?

Liste os locais da conta pedindo o campo metadata: o newReviewUri de cada um é o link oficial para o cliente escrever uma avaliação. A documentação descreve o campo como o link para a página da Pesquisa Google em que o cliente pode deixar uma avaliação do local.

Primeiro, o ID da conta:

curl -H "Authorization: Bearer $TOKEN" \
  "https://mybusinessaccountmanagement.googleapis.com/v1/accounts"

Depois, os locais com o link de avaliação. O parâmetro readMask diz quais campos a API deve devolver:

curl -H "Authorization: Bearer $TOKEN" \
  "https://mybusinessbusinessinformation.googleapis.com/v1/accounts/$CONTA/locations?readMask=name,title,metadata"

Na resposta, cada local traz algo assim:

{
  "name": "locations/1234567890",
  "title": "Loja Centro",
  "metadata": {
    "placeId": "ChIJ...",
    "mapsUri": "https://maps.google.com/maps?cid=...",
    "newReviewUri": "https://search.google.com/local/writereview?placeid=ChIJ..."
  }
}

Os valores acima são ilustrativos. Salve o newReviewUri de cada local no seu CRM ou na base de clientes, ligado à loja em que o cliente comprou. Assim cada pedido leva o cliente para o perfil certo, o problema mais comum em redes com vários endereços.

Como automatizar o pedido de avaliação?

Ligue um gatilho de venda ou atendimento concluído a uma mensagem com o newReviewUri do local, enviada a todos os clientes. A API entra no fluxo como a fonte dos links; o resto é automação comum.

Para quem não quer programar, ferramentas como Make, Zapier e n8n fazem esse fluxo com poucos blocos. É o que eu ensino no curso da Alura sobre automação da coleta de avaliações para o Google Meu Negócio, com Make, Google Sheets e WhatsApp.

Como receber um aviso a cada avaliação nova?

Ligue a conta a um tópico do Google Cloud Pub/Sub pela My Business Notifications API: o Google publica uma mensagem a cada avaliação nova ou alterada. É melhor do que consultar a API de tempos em tempos, porque o aviso chega na hora e não gasta cota.

1. Crie um tópico no Pub/Sub, no mesmo projeto.
2. Dê permissão de publicação no tópico para a conta de serviço [email protected].
3. Crie uma assinatura (push para um endpoint seu, ou pull).
4. Ligue a conta ao tópico com um PATCH no notificationSetting:

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://mybusinessnotifications.googleapis.com/v1/accounts/$CONTA/notificationSetting?updateMask=pubsubTopic,notificationTypes" \
  -d '{
    "name": "accounts/'$CONTA'/notificationSetting",
    "pubsubTopic": "projects/'$PROJETO'/topics/avaliacoes",
    "notificationTypes": ["NEW_REVIEW", "UPDATED_REVIEW"]
  }'

Com o aviso chegando, o seu sistema pode mandar a avaliação para um canal do time, abrir um chamado quando a nota for baixa ou registrar tudo em uma planilha.

Como listar e responder avaliações pela API?

Liste com GET em .../locations/{local}/reviews e responda com PUT em .../reviews/{avaliação}/reply. Esses métodos ficam na Google My Business API v4, que continua sendo a versão usada para avaliações.

Listar as avaliações de um local:

curl -H "Authorization: Bearer $TOKEN" \
  "https://mybusiness.googleapis.com/v4/accounts/$CONTA/locations/$LOCAL/reviews"

Cada avaliação traz, entre outros, a nota (starRating), o texto (comment), quem avaliou (reviewer), a data (createTime) e a resposta, se houver (reviewReply). Para vários locais de uma vez, existe o locations:batchGetReviews.

Responder:

curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://mybusiness.googleapis.com/v4/accounts/$CONTA/locations/$LOCAL/reviews/$AVALIACAO/reply" \
  -d '{"comment": "Obrigado pela visita, Ana! Que bom que o atendimento foi rápido."}'

O que dá para medir com a API?

Volume de avaliações, nota média e tempo de resposta, por local e por período. Com as avaliações listadas, as métricas saem de contas simples:

As avaliações também pesam fora do ranking: o Gemini no Google Maps usa o texto delas para responder perguntas sobre os lugares, como mostra o post sobre o Gemini no Google Maps.

Quais erros evitar?