Skip to content

SKILL.md

Latest commit

 

History

History
141 lines (114 loc) · 7.65 KB

SKILL.md

File metadata and controls

141 lines (114 loc) · 7.65 KB
Raw
name portal-transparencia
description Consulta dados do Portal da Transparência do governo federal brasileiro (CGU) — gastos públicos, despesas, licitações, contratos, convênios, cartões corporativos, servidores e remunerações, notas fiscais, viagens, emendas parlamentares, benefícios sociais (Bolsa Família, BPC, Seguro Defeso), sanções (CEIS, CNEP, CEPIM, CEAF), acordos de leniência e PEPs. Use quando o pedido envolver gasto/pagamento/salário de servidor/licitação/contrato/sanção de órgão ou pessoa do governo federal do Brasil, "portal da transparência", ou verificar se uma empresa está inidônea. Funciona sem chave de API.

Portal da Transparência (Brasil)

Dois modos, nenhum exige chave de API:

quando usar script
Massa série histórica, tudo de um mês/ano, análise agregada pt.py
Consulta filtro específico (nome, CNPJ, órgão, período), poucos registros, e os temas sem zip (contratos, convênios) site.py

pt.py baixa os zips do bucket aberto da CGU (dadosabertos-download.cgu.gov.br) e trata os CSVs localmente. site.py consulta as APIs internas do site — que estão atrás de AWS WAF, vencido com browser stealth (Camoufox) + reuso do cookie aws-waf-token; detalhes e armadilhas em references/site-api.md.

Comece pelo modo massa quando a pergunta for agregada ("quanto o MEC gastou em maio"), e pelo modo consulta quando for pontual ("contratos dessa empresa", "salário do servidor X"). curl/WebFetch direto no site não funcionam.

Modo massa

S=~/.claude/skills/portal-transparencia/scripts/pt.py

python3 $S datasets                      # o que existe (filtro opcional: `datasets cartao`)
python3 $S descobrir cpgf                # período mais recente publicado + tamanho
python3 $S baixar cpgf 202605 --dir dados
python3 $S colunas dados/202605_CPGF.csv
python3 $S agregar dados/202605_CPGF.csv --por "NOME ÓRGÃO" --valor "VALOR TRANSAÇÃO"
python3 $S filtrar dados/202605_CPGF.csv --onde "NOME FAVORECIDO~auto posto" \
    --cols "NOME ÓRGÃO" "NOME FAVORECIDO" "VALOR TRANSAÇÃO" --out achados.csv

descobrir antes de baixar: a defasagem varia por conjunto (despesas é do dia anterior; benefícios costumam ter 1–2 meses de atraso; licitações às vezes mais). filtrar e agregar são streaming — aguentam CSV de vários GB sem pandas. --onde aceita COL~texto (contém) e COL=valor (igual), ambos ignorando acento e caixa, e pode ser repetido (AND). Nomes de coluna casam por prefixo, então --por "NOME ÓRGÃO" já resolve.

Qual conjunto usar (modo massa)

Pergunta do usuário slug periodicidade
Quanto o órgão X pagou / empenhou; pagamento a fornecedor despesas diário (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, quem é o portador cpgf (e cpcc, cpdc) mensal
Salário/cadastro de servidor, militar, pensionista servidores AAAAMM_<sufixo>
Licitação, item licitado, compra licitacoes, compras mensal
Nota fiscal emitida contra órgão federal notas-fiscais mensal
Diárias e passagens de viagem a serviço viagens anual
Emenda parlamentar, quem é o autor, quanto foi pago emendas-parlamentares arquivo único
Transferência a estado/município transferencias mensal
Empresa inidônea/suspensa; punida por corrupção ceis, cnep snapshot do dia
ONG impedida; servidor expulso; acordo de leniência cepim, ceaf, acordos-leniencia snapshot do dia
Pessoa Exposta 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: Servidores_SIAPE, Militares, Pensionistas_SIAPE, Reserva_Reforma_Militares.

Detalhe de cada conjunto (template de nome, tamanho típico) em references/datasets.json.

Armadilhas dos CSVs

  • Encoding latin-1, separador ;, decimal com vírgula (1.234,56). pt.py já trata; se abrir com pandas: sep=";", encoding="latin-1", decimal=",".
  • CPF vem mascarado (***.866.951-**) — não dá para casar CPF completo nesses arquivos; CNPJ vem inteiro. Busca por CPF exato só pela API com chave.
  • Um zip pode ter vários CSVs (despesas traz Empenhos, Liquidação, Pagamento, itens…). baixar imprime os caminhos extraídos; use --head 2 para espiar cada um.
  • Órgãos são identificados por código SIAFI (orçamento/despesa) ou SIAPE (pessoal) — sistemas diferentes, códigos diferentes. Municípios usam código IBGE.
  • Alguns arquivos são grandes (novo-bolsa-familia ~340 MB, bpc ~185 MB). baixar aborta acima de 500 MB; libere com --limite-mb 0. O zip é cacheado, não baixe duas vezes.
  • Nada disso é tempo real: sempre diga ao usuário qual conjunto e qual período a resposta usou.

Modo consulta

T=~/.claude/skills/portal-transparencia/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 capturar https://portaldatransparencia.gov.br/<tema>/consulta --salvar <nome>

Temas prontos em references/consultas.json: contratos, convenios, licitacoes, cartoes, viagens, beneficios, emendas, servidores, despesas-favorecido. Para qualquer outra consulta do site, capturar descobre o endpoint e os parâmetros e grava no catálogo.

Três coisas que quebram silenciosamente aqui — leia references/site-api.md antes de confiar no resultado:

  • Parâmetro errado é ignorado sem erro: nome=silva filtra servidores, termo=silva devolve a lista inteira. Confira que os registros batem com o filtro.
  • O nome do filtro de período muda por tema (de/ate, assinaturaDe, periodoLiberacaoRecursosDe).
  • recordsTotal vem como 9223372036854775807 — lixo. Pagine até o lote vir menor que tamanhoPagina (máx. 500).

O primeiro comando gasta ~15 s abrindo o browser stealth para pegar o token; depois fica em cache e as consultas são HTTP puro. Não varra o site em volume por aqui — série grande é caso do modo massa.

API REST oficial (opcional, com chave)

Existe também a API oficial: references/endpoints.md (106 endpoints), DTOs em references/schemas.md, spec em references/openapi.json. Precisa de chave gratuita via gov.br no header chave-api-dados, limite de 400 req/min (700 entre 0h e 6h), e estourar suspende o token por 8h. Com PORTAL_TRANSPARENCIA_API_KEY no ambiente: python3 $S api contratos codigoOrgao=26000. Vale quando o usuário já tem chave ou quando precisa de busca por CPF completo, que é o único caso que nem o modo massa nem o modo consulta atendem (ambos trazem CPF mascarado).

Para consulta pontual que o usuário mesmo vai fazer no navegador — ou pedido via Lei de Acesso à Informação quando o dado não é publicado — veja references/site-guia.md.

Dados pessoais

Os arquivos de benefícios e de servidores contêm nome, NIS e CPF parcial de milhões de pessoas. Use-os para a pergunta feita e não monte perfis de indivíduos privados nem cruze bases para reidentificar CPF mascarado. Servidor público e empresa sancionada são informação pública por lei — beneficiário de programa social merece mais cuidado.