Power BI e Excel

Esta página é para quem monta relatórios de BI com os dados do TOPO. Ela mostra como ler as rotas de leitura no Power BI e no Excel (Power Query), por REST e por GraphQL. Nada aqui altera dados no TOPO.

O que você precisaCopiar link da seção

1. Uma chave de API com os escopos de leitura que o relatório usa. Peça ao suporte TOPO por um chamado. Para um painel de conciliações, por exemplo: companies:read, trial_balances:read e reconciliations:read. Para GraphQL, analytics:read.
2. O endereço da API do ambiente: https://api.topocontabil.com.br em produção.

As respostas vêm planas, uma coluna por campo, para o Power Query montar a tabela sem expandir registros aninhados.

REST, com paginaçãoCopiar link da seção

Cada rota de leitura devolve uma página: data traz as linhas e pagination traz page, limit, total e pages. Peça páginas de 100 linhas (limit=100) e repita até pagination.pages.

Exemplo com curl, conciliações da empresa 12 em agosto de 2026:

curl -s "$TOPO_API/api/v1/reconciliations?companyId=12&period=2026-08&limit=100&page=1" \
  -H "X-API-Key: $TOPO_CHAVE"

Cada linha traz a conta, o status, o responsável atual, o prazo, a situação do prazo e os saldos:

{
  "id": 5120,
  "empresaId": 12,
  "empresaNome": "Transportes Exemplo Ltda",
  "competencia": "2026-08",
  "contaCodigo": "1.1.01.001",
  "contaDescricao": "Caixa Geral",
  "status": "IN_ELABORATION",
  "responsavelNome": "Mariana Souza",
  "responsavelPapel": "Elaborador",
  "prazo": "2026-09-05T00:00:00.000Z",
  "slaStatus": "ON_TIME",
  "saldoContabil": 1150.5,
  "saldoConciliado": 1150.5,
  "diferenca": 0,
  "ajustes": 0
}

No Power BI ou no Excel (Power Query)Copiar link da seção

1. No Power BI, crie um parâmetro chamado ChaveTopo com a chave. No Excel, guarde a chave numa célula nomeada e leia com Excel.CurrentWorkbook(), ou use um parâmetro do Power Query.
2. Abra Obter dados > Consulta em branco > Editor avançado e cole a consulta abaixo. Ela lê todas as páginas de conciliações de uma competência.

let
    Base = "https://api.topocontabil.com.br",
    Pagina = (n as number) =>
        Json.Document(Web.Contents(Base, [
            RelativePath = "api/v1/reconciliations",
            Query = [period = "2026-08", limit = "100", page = Number.ToText(n)],
            Headers = [#"X-API-Key" = ChaveTopo]
        ])),
    Primeira = Pagina(1),
    Total = Primeira[pagination][pages],
    Paginas = List.Transform({1..Total}, each if _ = 1 then Primeira else Pagina(_)),
    Linhas = List.Combine(List.Transform(Paginas, each _[data])),
    Tabela = Table.FromRecords(Linhas)
in
    Tabela

3. Quando o Power BI pedir a credencial da fonte, escolha Anônimo: a chave já vai no cabeçalho X-API-Key.
4. Para outra tabela, troque o RelativePath e o Query: api/v1/trial-balances (balancetes), api/v1/companies (empresas) ou api/v1/trial-balances/318/lines (linhas do balancete 318).

Uma atualização do relatório faz uma chamada por página. Com 30 chamadas por minuto por rota, uma tabela de até 3.000 linhas atualiza dentro do limite. Acima disso, filtre por empresa ou competência. Veja limites.

GraphQLCopiar link da seção

A rota POST /api/v1/graphql traz os mesmos dados numa chamada só, escolhendo os campos. Ela é só de leitura.

curl -s -X POST "$TOPO_API/api/v1/graphql" \
  -H "X-API-Key: $TOPO_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"query":"query Saldos($empresa: Int!, $competencia: String!) { balancetes(companyId: $empresa, period: $competencia) { data { id competencia status linhas } } }","variables":{"empresa":12,"competencia":"2026-08"}}'

Resultado esperado:

{
  "data": {
    "balancetes": {
      "data": [{ "id": 318, "competencia": "2026-08", "status": "RELEASED", "linhas": 474 }]
    }
  }
}

As consultas disponíveis são empresas, planosDeContas, contas, balancetes, linhasDoBalancete e conciliacoes, com os mesmos filtros (companyId, period) e a mesma paginação (page, limit) da REST.

No Power Query, mande o GraphQL com Web.Contents e a opção Content, que faz a chamada virar POST:

Json.Document(Web.Contents("https://api.topocontabil.com.br", [
    RelativePath = "api/v1/graphql",
    Headers = [#"X-API-Key" = ChaveTopo, #"Content-Type" = "application/json"],
    Content = Text.ToBinary("{""query"":""{ empresas(limit: 100) { data { id razaoSocial cnpj } } }""}")
]))

Quando der erradoCopiar link da seção