Consultar os dados da Makfil pela API

A API entrega os relatórios prontos do Banco Espelho Makfil (locação, frota, manutenção, logística, qualidade e outros) para qualquer programa: n8n, Power BI, Excel, Python, planilhas e sistemas internos.

Endereço da API: http://localhost:8000

Primeiros passos

1. Peça uma chave a equipe de dados, dizendo quais relatórios você precisa e para quê.
2. Confira se a API está no ar (não precisa de chave):

   curl {{BASE}}/saude

3. Veja o que a sua chave pode consultar:

   curl -H "X-API-Key: SUA_CHAVE" {{BASE}}/relatorios

4. Busque um relatório:

   curl -H "X-API-Key: SUA_CHAVE" "{{BASE}}/relatorios/locacoes_em_aberto?limite=10"

Prefere clicar? Use o explorador desta página ou a referência interativa (botão Authorize, cole a chave).

Chave de acesso

Toda chamada, menos /saude, precisa de uma chave no cabeçalho:

X-API-Key: mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Também é aceito Authorization: Bearer mk_…, para ferramentas que só oferecem esse formato.

Cuidados com a chave

• Trate como senha. Quem tem a chave vê os mesmos dados que você.
• Nunca na URL (fica gravada em histórico e em log) e nunca em e-mail, chat ou planilha compartilhada.
• Guarde no lugar certo: na credencial do n8n, num parâmetro do Power BI, numa variável de ambiente.
• Uma chave por uso (um fluxo, um relatório do Power BI). Assim dá para revogar uma sem parar as outras.
• Vazou? Avise na hora. A chave é revogada e deixa de funcionar na chamada seguinte.

O que cada chave enxerga

A chave é criada com a lista de relatórios que pode consultar. Relatórios com dado sensível (financeiro, conferência, departamentos, pessoal) só aparecem para chaves autorizadas expressamente. Se você pedir um relatório que não está na sua lista, a resposta é 404, como se ele não existisse.

Endpoints

GET /saude

{
  "ok": true,
  "camada_gerada_em": "2026-09-29T17:47:42",
  "arquivos_parquet": 853,
  "dado_mais_novo": "2026-09-30T10:09:35"
}

dado_mais_novo diz quando a última atualização chegou. Use para avisar se o dado estiver velho.

GET /relatorios

[
  {
    "nome": "locacoes_em_aberto",
    "titulo": "Locacoes em aberto",
    "descricao": "Contratos de locacao ainda nao encerrados, com cliente, obra e valores",
    "caminho": "/relatorios/locacoes_em_aberto"
  }
]

GET /relatorios/{nome}/colunas

[
  {"coluna": "filial", "tipo": "VARCHAR"},
  {"coluna": "disponivel_agora", "tipo": "BIGINT"}
]

Tipos mais comuns: VARCHAR (texto), BIGINT/INTEGER (inteiro), DOUBLE/DECIMAL (número com casas), DATE, TIMESTAMP (data e hora).

GET /relatorios/{nome}

{
  "relatorio": "comercial_tenho_disponivel_locar_agora_grupo_filial",
  "titulo": "O que eu tenho disponível para locar agora, por grupo e por filial?",
  "total": 64,
  "pagina": 1,
  "limite": 1000,
  "tem_mais": false,
  "colunas": ["filial", "grupo", "disponivel_agora", "locado", "reservado", "pct_utilizacao", "modelos_com_saldo"],
  "linhas": [
    {"filial": "MAKFILEQUI", "grupo": "MULTI DIRECIONAL", "disponivel_agora": 56550, "locado": 117616, …}
  ]
}

Datas vêm no formato ISO (2026-09-30, 2026-09-30T10:09:35). Campo vazio vem como null.

POST /consulta

Só para chaves de análise. Um único SELECT, lendo as tabelas do espelho e os relatórios (relatorios.nome):

curl -X POST {{BASE}}/consulta \
  -H "X-API-Key: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"sql": "SELECT filial, COUNT(*) AS contratos FROM relatorios.locacoes_em_aberto GROUP BY 1", "limite": 1000}'

Devolve {colunas, linhas, limite, cortado}; cortado: true quer dizer que havia mais linhas que o limite.

Filtros, ordem e páginas

Em GET /relatorios/{nome}, qualquer coluna do relatório vira filtro:

Os filtros se somam (E). Coluna que não existe dá 400 com o nome dela, para você corrigir.

Buscar tudo, página por página

Continue pedindo pagina=2, 3… enquanto tem_mais for true. Exemplos prontos em Python e n8n.

Formatos

CSV e Excel respeitam os mesmos filtros e a mesma ordem do JSON. O CSV vem em UTF-8, com vírgula e ponto decimal (padrão internacional).

Exemplos por ferramenta

Troque SUA_CHAVE pela sua chave. Nos exemplos em código, a chave vem de uma variável de ambiente (MAKFIL_API_CHAVE), nunca escrita no arquivo.

# relatórios da sua chave
curl -H "X-API-Key: SUA_CHAVE" "{{BASE}}/relatorios"

# uma filial, os 100 com mais saldo
curl -H "X-API-Key: SUA_CHAVE" "{{BASE}}/relatorios/comercial_tenho_disponivel_locar_agora_grupo_filial?filial=MAKFILEQUI&ordem=-disponivel_agora&limite=100"

# baixar em Excel
curl -H "X-API-Key: SUA_CHAVE" -o locacoes.xlsx "{{BASE}}/relatorios/locacoes_em_aberto?formato=xlsx"

$h = @{ "X-API-Key" = $env:MAKFIL_API_CHAVE }
$r = Invoke-RestMethod -Headers $h -Uri "{{BASE}}/relatorios/locacoes_em_aberto?limite=500"
"$($r.total) contratos em aberto"
$r.linhas | Select-Object -First 10 | Format-Table

# salvar em Excel
Invoke-WebRequest -Headers $h -OutFile locacoes.xlsx -Uri "{{BASE}}/relatorios/locacoes_em_aberto?formato=xlsx"

import os
import requests

BASE = "{{BASE}}"
CABECALHO = {"X-API-Key": os.environ["MAKFIL_API_CHAVE"]}


def relatorio(nome, **filtros):
    """Todas as linhas de um relatório, página por página."""
    linhas, pagina = [], 1
    while True:
        r = requests.get(f"{BASE}/relatorios/{nome}", headers=CABECALHO, timeout=180,
                         params={**filtros, "limite": 5000, "pagina": pagina})
        r.raise_for_status()
        dados = r.json()
        linhas += dados["linhas"]
        if not dados["tem_mais"]:
            return linhas
        pagina += 1


abertas = relatorio("locacoes_em_aberto", filial="MAKFILEQUI")
print(len(abertas), "contratos")

# com pandas
import pandas as pd
df = pd.DataFrame(relatorio("comercial_tenho_disponivel_locar_agora_grupo_filial"))

// Node.js 18+ (no servidor; nunca coloque a chave em página aberta ao público)
const BASE = "{{BASE}}";
const resposta = await fetch(`${BASE}/relatorios/locacoes_em_aberto?limite=100`, {
  headers: { "X-API-Key": process.env.MAKFIL_API_CHAVE }
});
if (!resposta.ok) throw new Error(`${resposta.status}: ${await resposta.text()}`);
const { total, linhas } = await resposta.json();
console.log(total, linhas[0]);

let
    Base  = "{{BASE}}",
    Chave = ChaveApiMakfil,   // crie um parâmetro com esse nome; não escreva a chave aqui
    Resposta = Web.Contents(Base, [
        RelativePath = "relatorios/locacoes_em_aberto",
        Query   = [formato = "csv", limite = "300000"],
        Headers = [#"X-API-Key" = Chave]
    ]),
    Csv    = Csv.Document(Resposta, [Delimiter = ",", Encoding = 65001, QuoteStyle = QuoteStyle.Csv]),
    Tabela = Table.PromoteHeaders(Csv, [PromoteAllScalars = true])
in
    Tabela

Explorador de relatórios

Cole a sua chave para ver o que ela consulta, as colunas de cada relatório e uma amostra. A chave fica só nesta aba do navegador enquanto ela estiver aberta. Não é gravada em lugar nenhum.

Erros

Todo erro vem com um texto em detail dizendo o que houve:

{"detail": "Filtro 'filiall': o relatorio nao tem a coluna 'filiall'."}

Limites e boas práticas

• Frequência do dado: de hora em hora. Consultar de minuto em minuto não traz nada novo. Uma vez por hora (ou por dia) basta.
• Tempo máximo: 2 minutos por consulta. Os relatórios mais pesados levam de 5 a 45 s.
• Tamanho: JSON até 50.000 linhas por página; CSV e Excel até 300.000.
• Filtre na API, não depois: pedir só a filial ou o período que interessa é mais rápido que baixar tudo.
• Guarde o resultado quando for usar várias vezes (planilha, banco, nó do n8n), em vez de consultar de novo.
• Relatório novo ou alterado aparece na API em até ~10 minutos depois de publicado.

Suporte

Pedir chave, pedir um relatório novo ou relatar um problema: equipe de dados. Ao relatar, informe a hora, a rota chamada (sem a chave) e o texto do detail.

Documentação da API de leitura do Banco Espelho Makfil.