Conectar o Power BI e outras ferramentas aos relatórios

A API serve cada relatório como um CSV numa URL que já carrega o token de autenticação. Qualquer ferramenta que leia um CSV por URL (Power BI, Google Sheets e, por uma ponte, o Looker Studio) consegue consumir os relatórios da sua conta.

Monte a URL do relatório

A URL de um relatório tem esta forma:

https://tgsr.com.br/reports/{nome}?token=SEU_TOKEN&param=valor

A resposta é um CSV (Content-Type: text/csv) com uma linha de cabeçalho seguida das linhas de dados.

O nome de cada relatório e os parâmetros que ele exige vêm de GET /reports, documentado em Relatórios. Os nomes seguem o padrão dash.{plataforma}.{nome}, e o segmento da Meta é facebook. Os relatórios padrão por plataforma são dash.ga4.performance, dash.googleads.campaign-performance, dash.facebook.ad-performance e dash.tgsr.performance. A família dash.tgsr.* traz os relatórios do rastreamento do próprio TagServer (performance, traffic, pages, landing-pages, events-daily, conversions, devices, geo, referrers, entre outros): é a opção para levar ao BI os dados do seu site mesmo sem conta de anúncios conectada.

O parâmetro que identifica a entidade muda por plataforma: property_id no GA4, customer_id no Google Ads, meta_id no Meta Ads e server_name nos relatórios dash.tgsr.* (o hostname do servidor, que precisa pertencer à sua conta).

A janela de datas usa start_date e end_date em todo relatório que aceita data, no formato YYYY-MM-DD e inclusiva nas duas pontas. Ainda assim, cada relatório declara os próprios parâmetros e o servidor valida a URL contra essa declaração: confira em GET /reports o que o seu relatório aceita antes de montar a URL.

https://tgsr.com.br/reports/dash.ga4.performance?token=SEU_TOKEN&property_id=...&start_date=...&end_date=...

Todo relatório declara account_id, e ele vem do próprio token: não inclua account_id na URL. Os demais parâmetros (property_id, customer_id, meta_id, server_name, start_date, end_date e afins) entram na query.

O token vai em ?token= e autentica pela própria URL. Gere um token de nível ReadOnly ou superior da conta em Autenticação. O endpoint do relatório também aceita o token no cabeçalho Authorization: Bearer, mas o ?token= é o caminho mais simples: a autenticação viaja na própria URL e funciona em qualquer ferramenta que só aceita uma URL, como o IMPORTDATA do Google Sheets. Esse atalho vale só para o download (GET /reports/{nome}): a listagem GET /reports continua exigindo o cabeçalho Authorization: Bearer, e abrir https://tgsr.com.br/reports?token=... no navegador responde 401; a descoberta de nomes e parâmetros se faz com o cabeçalho. Como o token fica visível na URL, ele pode aparecer em logs de acesso: trate a URL com o mesmo cuidado que o próprio token. A validade e a renovação do token estão na seção "Quando os dados param de atualizar".

O que vem no CSV

Para cada relatório, GET /reports devolve uma descrição do relatório, uma descrição por parâmetro e, por coluna, o tipo e o papel: dimensão, atributo ou métrica, e a métrica vem com o modo de agregação (soma, mínimo, máximo ou contagem distinta). Os tipos escalares são DATE, VARCHAR, INTEGER, BIGINT, DOUBLE e BOOLEAN, e há dois tipos compostos, descritos abaixo. É dali que sai a tipagem das colunas no Power Query, em vez de adivinhar.

Há também o tipo JSON[T] (por exemplo, JSON[DOUBLE]): um mapa JSON cujos valores são todos do escalar T. No CSV essa coluna chega como texto JSON, um blob por linha, e não como número. Nos relatórios da Meta (dash.facebook.ad-performance, dash.facebook.campaign-performance), actions, action_values e cost_per_action_type são JSON[DOUBLE], chaveados por action_type. Na ferramenta de BI, expanda ou interprete essas colunas como JSON; não as tipe como número.

O tipo BIGINT[] é uma lista de ids, usada pelas métricas de contagem distinta. No CSV ela chega entre colchetes, como [3,42,57] (ou [], se vazia). Em dash.tgsr.distinct-users, a coluna users traz em cada linha os ids dos visitantes. O número de usuários distintos de um período é a contagem dos ids distintos na união das linhas, nunca a soma das contagens de cada linha. Na ferramenta de BI, trate a coluna como lista: expanda os ids e conte os valores distintos, em vez de tipá-la como número.

Razões e métricas derivadas (CPC, CTR, ROAS, ticket médio) não chegam como coluna do CSV. No meta elas vivem como fórmula aritmética sobre as medidas base, calculada depois da agregação. Na Meta, cpc é spend / clicks e ctr é clicks / impressions. No Google Ads, average_cpc é cost_micros / 1e6 / clicks, e até o cost é derivado de cost_micros / 1e6, porque o CSV traz cost_micros. O CSV entrega só as medidas base; a razão você recria como uma medida na própria ferramenta de BI.

Power BI

No Power BI Desktop, use Get Data com a opção Web e cole a URL completa, já com ?token=. Como o token está na URL, escolha a credencial Anonymous para a fonte.

O Power BI baixa o CSV e abre o Power Query. Promova a primeira linha a cabeçalho e tipe as colunas conforme os tipos que GET /reports declara. Cada relatório vira uma consulta (uma tabela); para vários relatórios, repita o processo e combine as consultas no modelo.

A atualização agendada no Power BI Service tem requisitos próprios (credenciais de fonte no nível do modelo semântico e, para uma fonte pública, possivelmente um gateway): siga a documentação de atualização agendada da Microsoft para configurá-la.

Google Sheets

Em uma célula, use IMPORTDATA apontando para a URL do relatório:

=IMPORTDATA("https://tgsr.com.br/reports/{nome}?token=SEU_TOKEN&property_id=...&start_date=...&end_date=...")

O IMPORTDATA carrega o CSV de uma URL pública com um GET e sem cabeçalho; por isso o token precisa estar na própria URL. Enquanto o documento está aberto, a planilha reimporta a fonte por volta de uma vez por hora, sem horário garantido.

Looker Studio

O conector CSV nativo do Looker Studio só faz upload de arquivo e não busca um CSV autenticado por URL. Use uma planilha do Google Sheets como ponte: alimente-a com IMPORTDATA (como na seção acima) e conecte o Looker Studio a essa planilha. Um conector de terceiros, como Supermetrics ou CData, também resolve.

Quando os dados param de atualizar

Como todo relatório declara account_id, todo download exige o token. Um token expirado, inválido ou ausente faz a atualização falhar com Error 401: unauthorized em qualquer relatório, GA4 inclusive. O token padrão tem validade limitada, em torno de 14 dias.

Para uma integração que roda sozinha, prefira um token de longa duração: ele tem validade customizada e é sempre somente leitura. Se usar o token padrão, gere um novo em Autenticação quando a validade acabar e atualize a URL nas suas consultas. O valor do token só aparece uma vez, na criação, e não pode ser reconsultado depois: ao renovar, copie o novo token na hora e cole na consulta.

No Power BI Service, o agendamento é desativado depois de quatro falhas consecutivas ou diante de credencial inválida ou expirada; corrigido o token, volte em Refresh > Schedule refresh e religue o agendamento (detalhes na documentação da Microsoft).

Os outros erros vêm com uma mensagem que diz o que corrigir:

• Error 400: missing parameter "<nome>": a URL está sem um parâmetro que o relatório exige. Confira os parâmetros em Relatórios.
• Error 400: unexpected parameters: <lista>: a URL tem um parâmetro que o relatório não declara (o token é isento). Um parâmetro com o nome errado dispara os dois erros de 400 ao mesmo tempo: falta o certo e sobra o errado.
• Error 404: report '<nome>' not found: o nome do relatório na URL não existe. Confira o nome em GET /reports.

Um relatório sem linhas no período pedido não é erro: o CSV vem com a linha de cabeçalho mesmo assim, e na ferramenta de BI isso aparece como uma tabela com colunas e sem linhas.

Veja também

• Token de longa duração: gere um token com validade customizada para deixar a integração rodando sozinha.
• Relatórios: a referência de GET /reports, GET /reports/{nome} e os parâmetros de cada relatório.
• Autenticação: como gerar o token ReadOnly que vai na URL.