# 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](https://claude.com/claude-code) (e scripts Python
que funcionam sozinhos) para consultar o
[Portal da Transparência](https://portaldatransparencia.gov.br) 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](https://img.shields.io/badge/licença-MIT-blue.svg)](LICENSE)
![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
![Sem chave de API](https://img.shields.io/badge/chave%20de%20API-não%20precisa-brightgreen)
![27 conjuntos de dados](https://img.shields.io/badge/datasets-27-orange)

```bash
# 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](#por-que-isso-existe)
- [Instalação](#instalação)
- [Modo massa: dados abertos em CSV](#modo-massa-dados-abertos-em-csv)
- [Modo consulta: APIs internas do site](#modo-consulta-apis-internas-do-site)
- [Conjuntos de dados disponíveis](#conjuntos-de-dados-disponíveis)
- [API REST oficial (opcional)](#api-rest-oficial-opcional)
- [Armadilhas que vão te morder](#armadilhas-que-vão-te-morder)
- [Perguntas frequentes](#perguntas-frequentes)
- [Uso responsável](#uso-responsável)
- [English summary](#english-summary)

## 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`](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](https://github.com/daijro/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.

```bash
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:

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

### Como skill do Claude Code

```bash
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".

```bash
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:

```bash
# 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.

```bash
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`](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:

```bash
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`](references/endpoints.md), DTOs de retorno em
[`references/schemas.md`](references/schemas.md), spec OpenAPI completa em
[`references/openapi.json`](references/openapi.json).

```bash
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](https://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](https://www.planalto.gov.br/ccivil_03/_ato2011-2014/2011/lei/l12527.htm)
(Lei 12.527/2011) e do [Decreto
8.777/2016](https://www.planalto.gov.br/ccivil_03/_ato2015-2018/2016/decreto/d8777.htm)
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](https://github.com/daijro/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.