Nota de campo: integrando os dados eleitorais do TSE

O desenho

Duas origens com papéis distintos: os CSVs do CKAN (dadosabertos.tse.jus.br) fazem a carga em massa — candidatos, bens, votação por município e prestação de contas, de 2014 a 2024 — e a API do DivulgaCandContas (não documentada oficialmente) serve só para revalidação pontual. É o mesmo padrão que já usávamos com o Portal da Transparência: cache em massa + conferência por detalhe.

Como rodamos em Cloudflare Workers (sem disco, com limite de tempo), os zips do TSE — que chegam a 624 MB — nunca são baixados inteiros: lemos o diretório central do zip via HTTP Range e descomprimimos em streaming só o arquivo (ano × UF) da rodada. Cada rodada importa um arquivo e salva o progresso; arquivos grandes retomam de onde pararam.

Surpresas encontradas nos dados

• O TSE republicou o histórico no layout moderno. Esperávamos seis layouts diferentes (2014–2024); encontramos cabeçalhos padronizados (SQ_CANDIDATO, SG_UF…) em todos os anos de candidatos, bens e votação. A exceção são as contas de 2014/2016, que seguem no formato legado com cabeçalhos "humanos" ("CPF/CNPJ do doador", "Sigla Partido" — com dois espaços mesmo).
• Datas coladas em 2014: "10/10/201400:00:00", sem espaço antes da hora.
• Sentinelas variadas: #NULO#, #NULO, #NE, -1, -3, -4 e "NÃO DIVULGÁVEL" — inclusive um CPF de candidato que veio como -4.
• SQ_RECEITA/SQ_DESPESA existem desde 2018 e são identificadores naturais perfeitos para deduplicação; para 2014/2016 geramos um hash determinístico.
• O dataset de contas de 2022 tem nome fora do padrão no CKAN (dadosabertos-tse-jus-br-dataset-prestacao-de-contas-eleitorais-2022).

Decisões que merecem registro

• Parser dirigido por cabeçalho, nunca por posição — as pequenas variações entre anos (2016 tem colunas extras) deixam de quebrar a importação.
• Votação agregada por município (somamos as zonas) — resultados por seção ficaram fora do escopo.
• Três tipos de sinal desde o nascimento: alertas de qualidade rodam durante a importação; lacunas (ex.: eleito sem prestação de contas, confirmada na API antes de publicar) rodam depois; cruzamentos (doador↔fornecedor) são sinais investigativos e nunca se misturam com defeitos de dado.
• Ponte parlamentar↔candidato: por CPF na Câmara (a API expõe no detalhe); por nome+UF no Senado (não expõe) — vínculos por nome carregam aviso visível e fila de revisão.

Limitações que ficaram

• CPF de doador PF vem mascarado da origem — cruzamentos pessoa-física são impossíveis por desenho (e é bom que seja assim).
• Filiações partidárias ficaram para depois: o dataset é fragmentado por partido×UF, muda mensalmente e lista pessoas físicas nominalmente — decidimos não ingerir até termos um produto agregado que respeite a LGPD.
• A API do DivulgaCandContas pode mudar sem aviso; se passar a exigir chave, a revalidação para até configurarmos TSE_API_KEY — a carga em massa não depende dela.