Automatizar relatório, auditoria e alerta com as APIs do Analytics

Com o purchase chegando pelo servidor, Marina ainda abria a interface toda manhã para conferir se as sessões, os pedidos e os leads de ontem estavam dentro do esperado. Vinte minutos por dia, e no dia em que ela faltou ninguém viu que o evento do checkout tinha parado.

O custo da conferência manual é a falha que passa. Um tema novo da Shopify que derruba a tag, um e-mail disparado sem UTM, um pico de referência falsa: cada um custa dias de dado ruim até alguém olhar. O que uma pessoa confere em vinte minutos, um script confere em segundos, todo dia, e avisa.

O capítulo mapeia as APIs do Analytics, monta a rotina que sinaliza anomalia na Verde Vivo, e diz o que existe e o que não existe em consulta conversacional e agentes em setembro de 2026.

O mapa tem três partes. A Data API lê relatórios: as mesmas dimensões e métricas da interface, tempo real e funis, com os mesmos limiares e a mesma modelagem dos relatórios. A Admin API lê e escreve configuração: propriedades, fluxos, definições personalizadas, vínculos, retenção e identidade de relatório. A coleta (Measurement Protocol e Data Manager API) é o caminho de entrada do capítulo anterior. O Data Studio consome a Data API, e por isso divide a cota com os scripts.

Autenticação decide quem é o robô. OAuth (o fluxo em que uma pessoa autoriza o acesso com a própria conta) vale para ferramenta que alguém opera. Conta de serviço (uma identidade própria do projeto no Google Cloud, com chave) vale para rotina sem pessoa. O e-mail da conta de serviço entra na propriedade como usuário com o papel de Viewer, e a chave fica num cofre de segredos, nunca no repositório.

Extrair é chamar runReport com intervalo de datas, dimensões, métricas e filtro, e paginar com limite e deslocamento quando a resposta passa do tamanho de uma página. runRealtimeReport lê os últimos minutos. runFunnelReport monta um funil. Desde 23 de abril de 2026 a versão v1alpha aceita ConversionSpec com os modelos DATA_DRIVEN ou LAST_CLICK, devolvendo os dados de desempenho de conversões da seção Advertising; o recurso está em alpha e com elegibilidade limitada.

Cota é medida em tokens (a unidade de custo que cada requisição consome, proporcional à complexidade). A propriedade padrão tem 200.000 tokens por dia e 40.000 por hora em cada categoria (Core, Realtime e Funnel), 14.000 por projeto por propriedade por hora, 10 requisições simultâneas e 10 erros de servidor por hora. No Analytics 360 os números são dez vezes maiores para tokens e cinco vezes para simultaneidade. O dia reinicia à meia-noite do Pacífico.

Falhas têm duas formas. Estourar a cota devolve um erro de limite, e o script precisa esperar em vez de insistir, porque insistir consome a cota de erros. Falha de servidor pede nova tentativa com espera crescente. O método getPropertyQuotasSnapshot, disponível desde setembro de 2024, mostra quanto da cota já foi consumido, e a rotina o consulta antes de rodar o lote grande.

Auditoria automática usa a Admin API para comparar a configuração com o que foi documentado. A rotina lista as dimensões personalizadas, os eventos-chave, os fluxos e os vínculos, e compara com o dicionário de dados do capítulo 8. Diferença vira aviso: uma dimensão criada fora do dicionário, um evento-chave desmarcado, um vínculo novo com uma conta de anúncios. A retenção (campo disponível na API desde janeiro de 2025) entra na mesma checagem.

A Admin API também escreve, com cuidado. Anotações de dados (ReportingDataAnnotation, desde abril de 2025) registram na propriedade o dia em que o site mudou ou a campanha começou, e aparecem nos gráficos. Desde 18 de junho de 2026, UpdateReportingIdentitySettings em v1alpha altera a identidade de relatório, e PropertySummary ganhou o campo can_edit. Escrita por script exige registro de quem, quando e por quê, e a Verde Vivo limita a conta de serviço da rotina a leitura.

Alerta externo é a rotina mais útil para uma equipe pequena. Todo dia, o script lê sessões, purchase e generate_lead de anteontem por origem e mídia, compara com a mediana dos mesmos dias da semana nas quatro semanas anteriores e avisa quando a diferença passa de um limiar combinado. Anteontem, e não ontem, por causa da janela de atualização do capítulo 29. O aviso vai para o canal da equipe com o número, a comparação e o link do relatório.

Consulta conversacional por API existe desde 14 de setembro de 2026: o método properties.chat, na Data API v1alpha, recebe uma pergunta em linguagem natural, aceita um sessionId opcional para manter a conversa, devolve blocos de resposta e informa a cota própria em PropertyChatQuota. A mesma versão trouxe dataTruncationReasons nos metadados, que dizem quando a resposta foi cortada. É alpha: mudanças incompatíveis podem acontecer, e o acesso segue as regras do Analytics Advisor, em beta e para propriedades em inglês.

O servidor MCP oficial do Google Analytics (um servidor local que expõe ferramentas de leitura para assistentes de IA) é experimental, de código aberto sob Apache-2.0 e somente leitura: resume contas, detalha propriedades, lista vínculos com o Google Ads, roda relatórios, funis e tempo real e lista definições personalizadas. Está disponível desde 2025. Não existe produto chamado "Analytics agent": o agente oficial é o Ask Advisor, e o acesso programático a ele é o properties.chat.

Agente analítico, seja pelo MCP, pelo properties.chat ou por um assistente que chama a Data API, precisa de três coisas. Acesso: credencial própria, com o papel de Viewer, separada da credencial de qualquer pessoa. Rastreabilidade: cada consulta que o agente faz fica registrada com propriedade, dimensões, métricas, filtro e período. Validação: todo número que o agente entrega vem acompanhado da consulta que o gerou, e a consulta roda de novo por uma pessoa antes de virar decisão.

Armadilha comum: dar ao agente a mesma conta de serviço da rotina de escrita, com papel de Editor, "para não criar outra credencial". Um agente que lê também passa a poder apagar uma dimensão ou desmarcar um evento-chave, e o registro de alterações mostra o nome da conta de serviço, não quem pediu. Leitura e escrita são credenciais diferentes, com papéis diferentes.

Na Verde Vivo, Marina escreveu a rotina sentinela em duas tardes, com uma conta de serviço em Viewer. Ela roda às 9h, consome cerca de 9.000 tokens por dia dos 200.000 da propriedade, e compara doze combinações de origem e métrica com a mediana das quatro semanas anteriores. No primeiro mês disparou quatro alertas: a tag do checkout parada depois de uma atualização de tema da Shopify, um e-mail disparado sem UTM caindo em Direct, um pico de referência falsa de um domínio desconhecido, e um feriado que derrubou as sessões de terça e não era problema.

Três de quatro eram reais, e o primeiro foi encontrado às 9h02 de um sábado, quando ninguém abriria a interface. A auditoria semanal da Admin API encontrou uma dimensão personalizada criada por um fornecedor fora do dicionário e um evento-chave desmarcado por engano. O agente de leitura ficou restrito ao MCP oficial, em Viewer, para responder perguntas de gestão, com cada consulta registrada.

O que mudou foi o tempo entre a falha e o aviso: de dias, quando dependia de alguém abrir a interface, para uma manhã. E a propriedade ganhou um auditor que não esquece de conferir.

Crie hoje uma conta de serviço em Viewer na sua propriedade e rode um runReport de sessões por origem e mídia de anteontem; compare o resultado com o relatório de aquisição de tráfego na interface, e o critério de acerto é o mesmo número nas cinco primeiras linhas. O próximo capítulo decide se a propriedade continua padrão ou vai para o Analytics 360, e quem governa o ativo.