Skip to content

README.md

Latest commit

 

History

History
316 lines (247 loc) · 15.1 KB

README.md

File metadata and controls

316 lines (247 loc) · 15.1 KB
Raw

Portal da Transparência — Skill para agentes de IA (Claude Code)

Acesse os dados de gastos públicos do governo federal brasileiro sem chave de API. Skill pronta para Claude Code (e scripts Python que funcionam sozinhos) para consultar o Portal da Transparência da CGU: despesas, licitações, contratos, convênios, cartão corporativo, salários de servidores, notas fiscais, viagens, emendas parlamentares, benefícios sociais e sanções.

Licença MIT Python 3.9+ Sem chave de API 27 conjuntos de dados

# quanto cada órgão gastou no cartão corporativo em maio/2026
python3 scripts/pt.py baixar cpgf 202605 --dir dados
python3 scripts/pt.py agregar dados/202605_CPGF.csv --por "NOME ÓRGÃO" --valor "VALOR TRANSAÇÃO"

# contratos federais assinados no 1º trimestre de 2026
python3 scripts/site.py consulta contratos --p assinaturaDe=01/01/2026 \
    --p assinaturaAte=31/03/2026 --tam 500 --paginas 4 --csv --out contratos.csv

Índice

Por que isso existe

Consultar o Portal da Transparência por código é mais chato do que deveria:

  1. A API REST oficial exige chave — cadastro com conta gov.br nível prata/ouro. Barreira real para script rápido, notebook de análise ou agente autônomo.
  2. O site é blindado por AWS WAF. curl e bibliotecas HTTP recebem 202 / 405 com x-amzn-waf-action: challenge e uma página "Human Verification".
  3. Os dados abertos em massa não são documentados de forma utilizável — o nome do arquivo, a periodicidade e o formato do período mudam de conjunto para conjunto, e não há listagem pública do bucket.

Este repositório resolve os três. Tudo aqui foi verificado empiricamente contra a fonte, não deduzido da documentação.

Descoberta 1 — o bucket de dados abertos é público e não tem WAF. https://dadosabertos-download.cgu.gov.br/PortalDaTransparencia/saida/ serve os zips direto, sem chave, sem cookie, sem captcha. O que faltava era o mapa: qual slug, qual periodicidade (diária, mensal, anual, snapshot) e qual template de nome de arquivo. Estão em references/datasets.json, com 27 conjuntos validados um a um por HEAD.

Descoberta 2 — o desafio do WAF é JS, não captcha visual. Um browser com fingerprint convincente passa em silêncio, e o cookie aws-waf-token resultante vale em requests HTTP normais depois. Resultado dos testes:

cliente resultado
curl, requests, WebFetch 202, página "Human Verification"
curl_cffi com impersonate de TLS 202 challenge — TLS sozinho não basta
Playwright Chromium headless desafio interativo ("Iniciar")
Playwright Chrome headed desafio interativo — CDP é detectado
Camoufox headless passa no 1º ciclo

Com o token em mãos, as APIs JSON internas do site ficam acessíveis (/<tema>/consulta/resultado): filtros arbitrários, 500 registros por página, sem chave. É o único caminho para contratos e convênios, que não têm zip publicado no bucket.

Instalação

O modo massa (pt.py) usa só a biblioteca padrão do Python — clone e rode.

git clone https://github.com/artificialguybr/portal-da-transparencia-skill.git
cd portal-da-transparencia-skill
python3 scripts/pt.py datasets

O modo consulta (site.py) precisa de duas dependências:

pip install -r requirements.txt
camoufox fetch          # baixa o browser stealth (~80 MB, uma vez)

Como skill do Claude Code

git clone https://github.com/artificialguybr/portal-da-transparencia-skill.git \
    ~/.claude/skills/portal-transparencia

Pronto — o agente carrega a skill sozinho quando você perguntar algo como "quanto o Ministério da Saúde gastou no cartão corporativo em maio?" ou "essa empresa está inidônea?". Para deixar disponível só em um projeto, clone em .claude/skills/ dentro dele.

Modo massa: dados abertos em CSV

Para série histórica, análise agregada, "tudo de um mês".

S=scripts/pt.py

python3 $S datasets                    # lista os 27 conjuntos (aceita filtro: datasets cartao)
python3 $S descobrir cpgf              # período mais recente publicado + tamanho do zip
python3 $S resolver cpgf 202605        # URL real no bucket, sem baixar
python3 $S baixar cpgf 202605 --dir dados
python3 $S colunas dados/202605_CPGF.csv

Filtrar e agregar são streaming — aguentam CSV de vários GB sem pandas:

# transações do cartão em postos de combustível
python3 $S filtrar dados/202605_CPGF.csv --onde "NOME FAVORECIDO~auto posto" \
    --cols "NOME ÓRGÃO" "NOME FAVORECIDO" "VALOR TRANSAÇÃO" --out postos.csv

# ranking de gasto por órgão
python3 $S agregar dados/202605_CPGF.csv --por "NOME ÓRGÃO" --valor "VALOR TRANSAÇÃO"

--onde aceita COLUNA~texto (contém) e COLUNA=valor (igual), ignorando acento e caixa, e pode ser repetido (AND). Nome de coluna casa por prefixo, então --por "NOME ÓRGÃO" já resolve "NOME ÓRGÃO SUPERIOR" vs "NOME ÓRGÃO".

Sempre rode descobrir antes de baixar: a defasagem varia por conjunto — despesas sai no dia seguinte, benefícios costumam atrasar 1 a 2 meses, licitações às vezes mais.

Modo consulta: APIs internas do site

Para filtro específico (nome, CNPJ, órgão, período), poucos registros, e os temas sem zip.

T=scripts/site.py

python3 $T consulta contratos --p assinaturaDe=01/01/2026 --p assinaturaAte=31/03/2026 \
    --tam 500 --paginas 4 --csv --out contratos.csv
python3 $T consulta servidores --p nome=silva --tam 50
python3 $T consulta convenios --p periodoLiberacaoRecursosDe=01/01/2026

Temas já mapeados em references/consultas.json: contratos, convenios, licitacoes, cartoes, viagens, beneficios, emendas, servidores, despesas-favorecido.

Para qualquer outra consulta do site, descubra o endpoint e os parâmetros automaticamente:

python3 $T capturar https://portaldatransparencia.gov.br/<tema>/consulta --salvar <nome>

Isso abre a página no Camoufox, intercepta o XHR /resultado e grava endpoint + parâmetros no catálogo — nenhum mapeamento manual necessário.

A primeira chamada gasta ~15 s abrindo o browser para pegar o token; depois ele fica em cache (~/.cache/portal-transparencia/) e as consultas são HTTP puro, com renovação automática quando expira.

Conjuntos de dados disponíveis

Pergunta slug periodicidade
Quanto o órgão X pagou / empenhou despesas diária (AAAAMMDD)
Quanto a empresa/pessoa Y recebeu da União despesas-favorecidos mensal
Execução orçamentária por programa/ação despesas-execucao, orcamento-despesa mensal / anual
Gasto no cartão corporativo e quem é o portador cpgf, cpcc, cpdc mensal
Salário e cadastro de servidor, militar, pensionista servidores AAAAMM_<sufixo>
Licitações, itens licitados, compras licitacoes, compras mensal
Notas fiscais emitidas contra órgão federal notas-fiscais mensal
Diárias e passagens de viagens a serviço viagens anual
Emendas parlamentares (autor, valor pago) emendas-parlamentares arquivo único
Transferências a estados e municípios transferencias mensal
Receitas da União receitas anual
Empresas inidôneas / punidas por corrupção ceis, cnep snapshot do dia
ONGs impedidas, servidores expulsos, leniência cepim, ceaf, acordos-leniencia snapshot do dia
Pessoas Expostas Politicamente pep mensal
Bolsa Família, BPC, Garantia-Safra, Seguro Defeso novo-bolsa-familia, bpc, garantia-safra, seguro-defeso mensal
Auxílio Brasil, Auxílio Emergencial (encerrados) auxilio-brasil, auxilio-emergencial mensal, histórico

servidores usa período composto — 202605_Servidores_SIAPE. Sufixos válidos: Servidores_SIAPE, Militares, Pensionistas_SIAPE, Reserva_Reforma_Militares.

Contratos, convênios, imóveis funcionais e renúncias fiscais não têm zip no bucket (testado exaustivamente, com dezenas de variações de slug e nome). Use o modo consulta ou a API oficial.

API REST oficial (opcional)

Se você já tem chave, ela também está coberta: 106 endpoints documentados em references/endpoints.md, DTOs de retorno em references/schemas.md, spec OpenAPI completa em references/openapi.json.

export PORTAL_TRANSPARENCIA_API_KEY="sua-chave"
python3 scripts/pt.py api contratos codigoOrgao=26000 pagina=1

Chave gratuita em portaldatransparencia.gov.br/api-de-dados/cadastrar-email (exige conta gov.br nível prata ou ouro). Limite de 400 requisições/minuto (700 entre 0h e 6h); estourar suspende o token por 8 horas.

Vale a chave em um caso que nenhum outro modo atende: busca por CPF completo.

Armadilhas que vão te morder

Cada uma destas custou uma sessão de depuração:

  • Os CSVs são latin-1, separador ;, decimal com vírgula (1.234,56). Com pandas: pd.read_csv(f, sep=";", encoding="latin-1", decimal=",").
  • CPF vem sempre mascarado (***.866.951-**) nos arquivos em massa e nas APIs do site. CNPJ vem completo. Casar CPF exato só pela API oficial.
  • Parâmetro desconhecido é ignorado em silêncio nas APIs do site, sem erro: nome=silva filtra servidores, termo=silva devolve a lista inteira como se tivesse filtrado. Sempre confira que os registros batem com o filtro.
  • recordsTotal vem como 9223372036854775807 (Long.MAX_VALUE) — é lixo, não use como contagem. Pagine até um lote voltar menor que tamanhoPagina.
  • O nome do filtro de período muda por tema: de/ate em despesas, licitações, cartões e viagens; assinaturaDe/assinaturaAte em contratos; periodoLiberacaoRecursosDe/...Ate em convênios. Datas em DD/MM/AAAA.
  • Órgãos têm dois sistemas de código: SIAFI (orçamento e despesa) e SIAPE (pessoal). Códigos diferentes, não intercambiáveis. Municípios usam código IBGE.
  • Um zip pode conter vários CSVs — despesas traz Empenhos, Liquidação, Pagamento e itens separados.
  • Arquivos grandes: novo-bolsa-familia ~340 MB, auxilio-brasil ~350 MB, bpc ~185 MB. pt.py baixar aborta acima de 500 MB por padrão (--limite-mb 0 libera) e cacheia o zip.
  • O nome do arquivo de viagens inclui a data de extração (2026_20260719_Viagens.zip), que muda sem aviso. pt.py descobre sozinho.

Perguntas frequentes

Preciso de chave de API? Não. Os dois modos principais funcionam sem cadastro. A chave só é necessária para busca por CPF completo.

Isso é raspagem de site? O modo massa baixa arquivos de dados abertos publicados justamente para download em volume — é o uso pretendido. O modo consulta chama as mesmas APIs JSON que o navegador chama ao usar o site, com pausa de 1 s entre requisições e paginação limitada.

Por que precisa de browser stealth? O WAF na frente do site desafia qualquer cliente que não pareça browser, inclusive para ler dado público. O browser só resolve o desafio uma vez; o resto é HTTP normal.

Funciona no Linux/Windows? Sim. pt.py é stdlib puro. site.py depende de Camoufox e curl_cffi, ambos multiplataforma.

Os dados são em tempo real? Não. Cada conjunto tem sua defasagem — rode descobrir para ver o período mais recente publicado e cite conjunto e período na sua análise.

Um tema do modo consulta parou de funcionar. É API interna, sem contrato de estabilidade. Rode site.py capturar <url> --salvar <nome> de novo para remapear.

Uso responsável

Os dados são públicos por força da Lei de Acesso à Informação (Lei 12.527/2011) e do Decreto 8.777/2016 de dados abertos. Ainda assim:

  • Prefira o modo massa para volume. O bucket de dados abertos existe para isso; o site não. Não use o modo consulta para varrer o portal inteiro.
  • Respeite a infraestrutura pública. Os padrões deste repo são conservadores (1 s entre requisições, paginação explícita). Mantenha assim.
  • Os arquivos de benefícios e de servidores contêm dados pessoais de milhões de pessoas — nome, NIS, CPF parcial. Servidor público e empresa sancionada são informação pública por lei; beneficiário de programa social merece mais cuidado. Não monte perfis de indivíduos privados nem cruze bases para reidentificar CPF mascarado.
  • Confira na fonte antes de publicar. Se sua análise vai virar reportagem ou denúncia, valide os números na tela do portal.

Projeto independente, sem vínculo com a CGU ou o governo federal.

English summary

AI-agent skill and Python CLI for Brazil's federal government transparency portal (Portal da Transparência / CGU) — no API key required.

Two access modes, both verified against the live source:

  1. Bulk mode (scripts/pt.py, stdlib only): downloads open-data zips from the CGU's public bucket, which has no WAF and needs no key. This repo contributes the missing map of 27 datasets — slug, periodicity and filename template — plus streaming filter/aggregate over the latin-1 ;-separated CSVs.
  2. Query mode (scripts/site.py): the portal's own internal JSON APIs behind AWS WAF. The WAF challenge is JS-based, so a stealth browser (Camoufox) clears it silently and the resulting aws-waf-token cookie is then reusable from plain HTTP. This is the only route to federal contracts and grant agreements, which have no bulk zip. Includes an XHR-capture command that auto-discovers any consultation endpoint and its parameters.

Covers public spending, procurement, contracts, corporate-card transactions, civil-servant salaries, invoices, travel, congressional budget amendments, social benefits (Bolsa Família, BPC), and sanction registries (debarred and corruption-punished companies). The official REST API (106 endpoints, OpenAPI spec included) is supported as an optional third mode when you have a key.

MIT licensed. Independent project, not affiliated with the Brazilian government.