Relatório no Power Query (Excel e Power BI)

O Excel e o Power BI podem buscar um relatório da Engage direto da API, sem exportar planilha pela tela. Este artigo mostra como montar as duas consultas do Power Query: uma gera o token a cada atualização e a outra traz o relatório.

Antes de começar

• As credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage.
• Um usuário de serviço com a permissão Gerenciar relatórios — veja Criar o usuário de serviço da integração. Não use o login de uma pessoa.
• O guid_report do relatório, que vem da listagem descrita em Relatórios disponíveis e seus filtros.
• A chamada validada no Postman antes de ir para o Power Query: pasta 05 - Relatórios, request Consumir relatório (JSON).
• Monte tudo em homologação (https://sandbox.engage.bz/api/v1) e troque para produção (https://my.engage.bz/api/v1) só quando o resultado estiver conferido.

Request Consumir relatório (JSON) no Postman com resposta 200 e os registros do relatório; nomes de usuário ocultados

Montar as consultas

1Crie a consulta que gera o token

No Power Query: Obter Dados > De Outras Fontes > Consulta Nula. Renomeie a consulta para GetBearerToken — o nome precisa ser exatamente esse. Abra o Editor Avançado e cole:

let
    GetBearerToken = () =>
        let
            url  = "https://sandbox.engage.bz/api/v1/auth",
            body = Text.ToBinary(
                "grant_type=password"
                & "&username="      & Uri.EscapeDataString("LOGIN_DO_USUARIO_DE_SERVICO")
                & "&password="      & Uri.EscapeDataString("SENHA_DO_USUARIO_DE_SERVICO")
                & "&client_id="     & Uri.EscapeDataString("SEU_CLIENT_ID")
                & "&client_secret=" & Uri.EscapeDataString("SEU_CLIENT_SECRET")
                & "&customer_id="   & Uri.EscapeDataString("SEU_CUSTOMER_ID")
            ),
            options = [
                Headers = [#"Content-Type" = "application/x-www-form-urlencoded"],
                Content = body,
                Timeout = #duration(0, 0, 2, 0)
            ],
            resposta = Json.Document(Web.Contents(url, options)),
            token    = resposta[access_token]
        in
            token
in
    GetBearerToken

Substitua só os textos em MAIÚSCULAS e clique em Concluído.

2Crie a consulta que busca o relatório

Crie outra Consulta Nula, com o nome que preferir (por exemplo, RelatorioModulos). No Editor Avançado:

let
    token   = GetBearerToken(),
    origem  = "https://sandbox.engage.bz/api/v1",
    caminho = "/SEU_CUSTOMER_ID/reports/legacy/GUID_DO_RELATORIO/USER_ID_DO_USUARIO_DE_SERVICO/json",

    resposta = Web.Contents(
        origem,
        [
            RelativePath = caminho,
            Query = [
                roundCompletionDateStartDate = "2026-08-01",
                roundCompletionDateEndDate   = "2026-08-31"
            ],
            Headers = [ #"Authorization" = "Bearer " & token ],
            Timeout = #duration(0, 0, 60, 0)
        ]
    ),

    dados  = Json.Document(resposta),
    tabela = Table.FromList(dados, Splitter.SplitByNothing(), null, null, ExtraValues.Error)
in
    tabela

3Transforme a lista em colunas

1. Clique no botão de expandir (as duas setas) no cabeçalho da coluna Column1.
2. Desmarque "Usar o nome da coluna original como prefixo" e clique em OK.
3. Clique em Fechar e Carregar.

4Ajuste as opções que evitam erro

• Credenciais: se o Power Query pedir, escolha Anônimo. A autenticação já vai no cabeçalho da consulta.
• Erro Formula.Firewall: em Arquivo > Opções e Configurações > Opções > Privacidade, marque Ignorar Níveis de Privacidade.
• Power BI: em Opções > Carregamento de Dados, desmarque Permitir carregamento paralelo de tabelas. Assim duas consultas de relatório não rodam ao mesmo tempo.

Cuidados

• Não atualize duas consultas do mesmo relatório ao mesmo tempo com o mesmo usuário. Enquanto um relatório processa, uma segunda chamada igual não gera processamento novo: recebe o resultado da primeira, mesmo com filtros diferentes. Escalone os horários de atualização.
• Sempre use filtros. Relatório sem recorte de data estoura o tempo de processamento e a atualização falha.
• A senha fica gravada no arquivo. Trate o .xlsx ou o .pbix como material sensível e não o compartilhe. Se ele vazar, troque a senha do usuário de serviço.
• As colunas vêm do relatório. Se o relatório mudar de colunas, a etapa de expansão pode quebrar e precisa ser refeita.

Problemas comuns