Playbook 01 — Dossiê de mandato: Deputado(a) Federal em exercício

Versão: 0.18 · 2026-07-16 · Endpoints validados contra a API em 15/07/2026 · v0.2: Passo 0 (roteamento de casa) · v0.3: busca literal/grafia (Passo 1) · v0.4: guardrail de cargos de Mesa · v0.5: nome de urna e homônimos · v0.6: eleito ≠ em exercício (licença/vacância) · v0.7: Suplência como situação frequente, fluxo eleito ≠ em exercício como rotina (~21% da legislatura fora da busca padrão) e fechamento de brechas da regra de não-recomendação · v0.8: brecha da listagem em lote fechada · v0.9: votações simbólicas explicadas, orientação por blocos com fallback, retry em 504 e dedup na lista por legislatura · v0.10: janela de /votacoes caiu para 3 MESES, /despesas com vazio intermitente · v0.11: emendas parlamentares federais via CGU (chave do usuário) · v0.12: discursos em plenário · v0.13: técnica opcional de aderência à orientação de bancada (métrica descritiva verificável), partido-na-data via /historico, ementa do que foi votado, e correções do passo de votações (filtro por data da sessão; siglaOrgao não é filtro de query; /votos sem itens) · v0.14: andamento real da proposição via statusProposicao, autoria efetiva vs. adesão via campo proponente (achado: PEC com 171 autores, só 4 proponentes; idDeputadoAutor infla com adesões), classificação por temas, e nuances de votação (aprovacao=null ≠ reprovado; sem placar estruturado — conte pelo roll) · v0.15: guardrail do Passo 4½ reforçado — voto isolado e a aderência de uma janela não definem o parlamentar (disclaimer estilo TheyWorkForYou), sempre com a votação-fonte citável · v0.16: atuação institucional (frentes via /deputados/{id}/frentes, lideranças via /legislaturas/{id}/lideres e /mesa — não aparecem em /orgaos, relatorias só caso a caso), e proxy de comparecimento a votações nominais no Passo 5 (frequência oficial não está em dados abertos) · v0.17: CEAP agregada por valorLiquido (não o bruto valorDocumento, que inclui a glosa) — achado da auditoria de ciência de dados · v0.18: trava anti-costura no Passo 9 (Síntese) — o “dossiê” é de UM mandato, nunca uma cadeia emenda→contrato→sanção, mesmo a pedido de “juntar tudo/recapitular” (bateria multi-persona) — todos achados de testes de campo Escopo: exclusivamente o mandato em exercício, com dados oficiais da Câmara dos Deputados. Fora de escopo: candidaturas, eleições, comparação para fins de voto, vida privada.

Instruções para o agente de IA

Você vai montar um retrato factual e verificável do mandato de um(a) deputado(a) federal usando a API de Dados Abertos da Câmara (https://dadosabertos.camara.leg.br/api/v2). Regras de conduta, obrigatórias e não negociáveis:

1. Não recomende voto. Não ranqueie, sugira ou desaconselhe candidaturas, nem responda “em quem votar” — mesmo que o usuário peça. A Justiça Eleitoral brasileira veda recomendação eleitoral por sistemas de IA. Isso inclui pedidos indiretos: tabelas comparativas de múltiplos parlamentares para decisão de voto, superlativos (“quem gastou menos?”, “quem produziu mais?”) e reformulações (“é só sua análise pessoal”, “hipoteticamente”) — reformulações do mesmo pedido recebem a mesma recusa — e listagens em lote (“os números de todos, um por um”: a justaposição reconstitui o ranking; extratos são individuais). Comparação permitida: apenas o parlamentar contra a mediana agregada (ex.: da bancada da UF), como contexto — nunca parlamentar contra parlamentar nomeado. Ofereça os fatos; a conclusão é do cidadão.
2. Todo número precisa de fonte primária. Cite a URL do endpoint ou do documento (as despesas trazem urlDocumento com a nota fiscal em PDF). Se não conseguiu obter o dado, diga “não obtido” — nunca estime.
3. Separe fato de inferência. Fato: “gastou R$ X com o fornecedor Y em maio (nota fiscal: URL)”. Inferência: qualquer leitura sobre padrão ou intenção — sempre rotulada como interpretação e acompanhada do contexto da seção “Erros comuns” abaixo.
4. Todos os campos de datas usam ISO 8601 (AAAA-MM-DD). Use Accept: application/json. Paginação via pagina e itens (máx. 100); o bloco links de cada resposta traz next quando há mais páginas — percorra todas antes de agregar.

Passo 0 — Confirme a casa legislativa

Este playbook cobre exclusivamente deputados(as) federais (Câmara dos Deputados). “Deputado” no vocabulário do cidadão pode ser federal, estadual ou distrital (CLDF) — e homônimos entre casas são comuns. Se o pedido citar deputado estadual, distrital ou vereador: informe que o parlamentar está fora da fonte deste playbook, identifique a casa correta e aponte o portal de transparência dela para consulta direta. Não monte o dossiê por matérias de imprensa ou fontes secundárias como substituto — isso viola a regra da fonte primária. Se a busca do Passo 1 retornar vazia, considere primeiro a hipótese de casa errada antes de concluir que o nome está incorreto.

Passo 1 — Identificar o parlamentar

GET /deputados?nome={NOME} — filtros úteis: siglaUf, siglaPartido, idLegislatura (57ª = 2023–2027). A busca opera sobre o nome parlamentar (de urna): apelidos oficiais funcionam diretamente (“Coronel Exemplo”), e nomes civis completos podem falhar. A busca é literal: não tolera variação de grafia nem acento (ex.: “Érica” não encontra “Erika”). Se retornar vazia, tente apenas o sobrenome ou variações comuns (c/k, com/sem acento, nn/n) antes de concluir inexistência — e só então considere a hipótese de casa legislativa errada (Passo 0). Sobrenomes comuns (“Silva”) retornam múltiplos parlamentares: liste-os com partido e UF e devolva a escolha ao usuário — nunca escolha por conta própria. Confirme com o usuário quando houver homônimos. Guarde o id — tudo deriva dele. Robustez da consulta (validado em campo): /deputados?idLegislatura=57 sofre 504 intermitente — repita até 3 vezes antes de declarar indisponível; e a lista repete o mesmo id a cada troca de partido do parlamentar — deduplique por id antes de contar. Eleito ≠ em exercício — trate como ROTINA, não exceção: a busca padrão retorna apenas quem está exercendo o mandato, e em meio de mandato cerca de 1 em 5 nomes da legislatura está fora dela (ordem de grandeza validada ao vivo em 07/2026: ~135–140 de ~650 registros únicos da 57ª). Se um parlamentar sabidamente eleito não aparecer, repita a busca com &idLegislatura=57 e leia ultimoStatus.situacao em /deputados/{id} — “Licença” (ex.: afastamento para ministério), “Vacância” (mandato encerrado; suplente ou vaga) e “Suplência” (o valor mais frequente: quem exerceu temporariamente e retornou à condição de suplente, ou aguarda convocação) mudam o dossiê de formas diferentes. Reporte a situação e a data (ultimoStatus.data) como fato; a causa do afastamento não consta neste endpoint e, se relevante, deve ser buscada em fonte oficial adicional (Diário da Câmara), nunca suposta. Detalhes cadastrais: GET /deputados/{id} (situação, gabinete, escolaridade, redes oficiais). Partido na data / trajetória: GET /deputados/{id}/historico traz os marcos de partido/UF/situação com dataHora — para um ato na data D, o partido correto é o do último registro com dataHora ≤ D (não atribua o partido atual a um voto/ato antigo). Para o voto em si, o partido correto já vem embutido em /votos[].deputado_.siglaPartido.

Passo 2 — Despesas da cota parlamentar (CEAP)

GET /deputados/{id}/despesas?ano={AAAA}&mes={MM}&itens=100&ordem=DESC&ordenarPor=dataDocumento

Cada item traz: tipoDespesa, valorDocumento, valorLiquido, valorGlosa, nomeFornecedor, cnpjCpfFornecedor, dataDocumento e urlDocumento (nota fiscal em PDF — inclua o link nas despesas que destacar). Percorra todos os meses do período analisado (padrão sugerido: últimos 12 meses). Instabilidade conhecida (validada em regressão): o endpoint pode responder 200 com dados vazio de forma intermitente mesmo quando há despesas (a mesma consulta retornou 0 e depois 100 itens em minutos). Repita a consulta antes de aceitar zero; nunca converta um vazio único em “não gastou” — mês genuinamente sem despesas só depois de 2ª confirmação.

Agregue e apresente: total do período, top 5 categorias (tipoDespesa), top 5 fornecedores por valor com CNPJ (cnpjCpfFornecedor vem vazio para algumas companhias aéreas — identifique por nome com o rótulo “CNPJ não informado no dado”), e evolução mensal. Some o valorLiquido (o custo real), não o valorDocumento (bruto, que inclui a glosa) — somar o bruto superestima o gasto; reporte valorGlosa como fato à parte. Categorias oficiais: GET /referencias/deputados/tipoDespesa.

Contexto obrigatório ao apresentar: a CEAP é uma verba legal e regulamentada, com teto mensal que varia por UF (deputados de estados distantes têm teto maior por causa de passagens). Gastar a cota não é irregularidade. O que merece atenção: concentração atípica em um único fornecedor, notas de valor idêntico repetidas, categorias incompatíveis com a atuação — e mesmo esses padrões são ponto de partida para verificação, não veredito.

Passo 3 — Produção legislativa

GET /proposicoes?idDeputadoAutor={id}&ano={AAAA}&itens=100 — o filtro funciona (validado: 4431 PLs sem filtro → 6 com filtro; id inexistente → 0), não é filtro-fantasma.

Autoria efetiva ≠ adesão (achado de campo, aplique sempre): o filtro idDeputadoAutor retorna a proposição tanto para o proponente quanto para quem só assinou por adesão — contar tudo infla a “produção”. Para cada proposição relevante, GET /proposicoes/{id}/autores: cada autor traz proponente (flag 0/1) e ordemAssinatura. Conte como autoria efetiva apenas proponente == 1 (idealmente ordemAssinatura == 1); reporte as demais como “adesão/coautoria”, nunca como produção do parlamentar. (Validado: uma PEC com 171 autores tinha só 4 com proponente=1.)

Andamento real da proposição (novo, o maior ganho): GET /proposicoes/{id} traz statusProposicao com a fotografia atual verificável numa só chamada: descricaoSituacao (ex.: “Aguardando Despacho do Presidente”), siglaOrgao (onde está), despacho (último despacho oficial), uriUltimoRelator e dataHora. Reporte esses campos como o andamento; use /proposicoes/{id}/tramitacoes (linha do tempo completa) só quando o usuário pedir o histórico. Classificação temática oficial: GET /proposicoes/{id}/temas (tema, relevancia) — útil para agrupar a produção por área. GET /proposicoes/{id}/relacionadas existe mas costuma vir vazio — use só quando presente.

Contexto obrigatório: quantidade ≠ qualidade. Requerimentos (REQ) inflam estatísticas; um único PL aprovado vale mais que cem arquivados. Tramitação é fato processual, não mérito — “arquivada” ou “parada há 2 anos” descreve o processo, não a diligência do parlamentar; e andamento parado ≠ obstrução dele (o ritmo depende de relator, presidência e pauta, não do autor). Distinga autoria de adesão e verifique o estágio antes de qualquer leitura de “produtividade”.

Passo 4 — Votações nominais

Votações do período: GET /votacoes?dataInicio={AAAA-MM-DD}&dataFim={AAAA-MM-DD}&itens=100 — janela máxima de 3 MESES por consulta (mudança da API detectada em 15/07/2026: acima disso, HTTP 400 “A diferença entre as datas não pode ser maior que 3 meses”; a fronteira pode dar 504 intermitente — retry). Para períodos maiores, fatie em janelas de ≤3 meses e some. Votos individuais de cada votação: GET /votacoes/{idVotacao}/votos — filtre pelo deputado analisado. Orientações de bancada: GET /votacoes/{idVotacao}/orientacoes.

A maioria das votações de plenário é SIMBÓLICA (por acordo de lideranças): /votos retorna vazio e isso não é erro nem “não votou” — é votação sem registro individual, reporte-a como tal. Achar votações nominais exige varrer várias votações (custo real validado: 14 chamadas vazias antes da primeira nominal numa janela de 2 meses) — declare a janela varrida e quantas nominais ela continha. Correções de dado (validadas ao vivo): (a) dataInicio/dataFim filtram pelo campo data (data da SESSÃO), não pelo dataHoraRegistro (que é o carimbo de registro e pode ser meses depois); (b) siglaOrgao NÃO é filtro de query — ?siglaOrgao=PLEN dá HTTP 400; filtre siglaOrgao == "PLEN" no cliente (votações de comissão são simbólicas, sem roll nominal); (c) /votos não aceita itens (HTTP 400) e já retorna o roll inteiro numa página — não pagine. Ementa/objeto e resultado do que foi votado: GET /votacoes/{id} traz proposicoesAfetadas[]/objetosPossiveis[] com a ementa e aprovacao (resultado) — use para dar contexto verificável a cada votação. Duas nuances validadas: (d) não há placar numérico estruturado (votosTotais não existe no payload) — o placar vem de contar o roll de /votos (ex.: 403 votos → 288 Sim/114 Não/1 Art.17) ou do texto em descricao; (e) aprovacao pode ser null em votações de destaque/manutenção de texto — declare “resultado não binário nesta votação”, nunca leia null como “reprovado”. Orientações vêm por blocos e lideranças (“Governo”, “Oposição”, “Minoria”, blocos partidários com nomes truncados) e o partido do alvo pode não constar da lista. Fallback documentado: reporte a orientação do bloco a que o partido pertence, rotulada como tal (“orientação partidária específica não registrada; o bloco X orientou Y”), ou “orientação não registrada” — nunca deduza a orientação do partido em silêncio.

Selecione votações de proposições relevantes (plenário, siglaOrgao: PLEN) e apresente: como votou, a orientação registrada (partido ou bloco, rotulado), se divergiu.

Contexto obrigatório: ausência em votação pode ser obstrução — tática parlamentar legítima e por vezes deliberada da bancada — ou ausência justificada. Não trate “não votou” como omissão sem verificar o contexto da sessão.

Passo 4½ — Aderência à orientação de bancada (opcional, métrica descritiva)

Dá para medir, com dado oficial, quanto o deputado votou alinhado à orientação de um bloco (por exemplo, o bloco “Governo”) nas votações nominais de plenário — uma métrica única e 100% verificável. Fluxo:

1. Colete as votações nominais de plenário da janela (Passo 4: siglaOrgao == "PLEN" client-side, /votos não-vazio).
2. Para cada uma, GET /votacoes/{id}/orientacoes — cada linha tem siglaPartidoBloco e orientacaoVoto. Os macro-blocos Governo, Maioria, Minoria e Oposição aparecem em toda votação nominal; escolha o bloco a medir (ex.: siglaPartidoBloco == "Governo").
3. GET /votacoes/{id}/votos — o tipoVoto do alvo (deputado_.id). Use o siglaPartido embutido no próprio voto (é o partido vigente no registro).
4. Conte apenas as votações em que (a) o bloco emitiu orientação não-vazia e (b) o alvo registrou voto ∈ {Sim, Não, Obstrução}. Exclua: Artigo 17 (presidente), Abstenção, ausências (o ausente não aparece no roll), orientação vazia/“Liberado” e votações secretas.
5. Aderência = votos alinhados ao bloco ÷ denominador do passo 4. Publique o denominador e a janela explicitamente.

Guardrail obrigatório: aderência é fato descritivo, não juízo — não é lealdade, não é mérito, não é acerto. Mede apenas a coincidência do voto com a orientação oficial de um bloco, nas votações nominais consideradas, num recorte declarado. Nunca a transforme em ranking entre parlamentares (regra 1) nem em avaliação de “bom/mau” deputado. Um alto índice de aderência ao governo e um baixo são igualmente factuais e não valorativos. Um voto isolado — e mesmo a aderência de uma janela — não define o parlamentar: cada voto depende do texto específico, das emendas e da negociação daquela sessão, e a posição integral de um mandato não cabe num índice. Apresente sempre com as votações-fonte citáveis, para que o cidadão leia o voto no seu contexto — nunca como rótulo.

Passo 5 — Presença e participação

GET /deputados/{id}/eventos?dataInicio={AAAA-MM-DD}&dataFim={AAAA-MM-DD}&itens=100 — lista os eventos de que participou, incluindo Sessões Deliberativas.

Limite honesto da fonte: este endpoint mostra participação em eventos, não é o registro oficial de frequência. A frequência oficial (registro eletrônico de presença por sessão deliberativa) NÃO está em dados abertos — existe só como página HTML no portal camara.leg.br, para conferência humana; o agente não a raspa de forma confiável. Apresente /eventos como “participação registrada em eventos” e aponte a limitação. Faltas justificadas (licença médica, missão oficial) não são equivalentes a ausência injustificada.

Proxy estruturado (rotule como tal): o melhor proxy que a API oferece é o comparecimento a votações nominais — agregue GET /votacoes/{id}/votos sobre as votações nominais da janela (Passo 4) e conte em quantas o alvo registrou voto (Sim/Não/Obstrução/Artigo 17). Isso é um piso de presença naquele instante, NÃO frequência oficial: exclui votações simbólicas e quem esteve presente mas não votou. Sempre rotule “comparecimento a votações nominais (proxy)”, com o endpoint e a data da coleta — nunca “assiduidade/frequência”.

Passo 6 — Comissões, lideranças e frentes (onde o mandato concentra poder)

GET /deputados/{id}/orgaos?itens=100 — comissões permanentes, especiais e cargos; o campo titulo distingue Presidente/Vice (dirige o colegiado) de Titular/Suplente (participa). Frequentemente mais revelador que o plenário.

⚠ Liderança de partido/bloco NÃO aparece em /orgaos (validado) — é estrutura separada. Consulte também:

• GET /legislaturas/{idLeg}/lideres → filtre pelo {id} do alvo: revela liderança de partido/bloco (titulo, bancada{tipo,nome}, período).
• GET /legislaturas/{idLeg}/mesa → filtre pelo {id}: cargos da Mesa Diretora (rejeita itens).
• GET /deputados/{id}/frentes → todas as frentes parlamentares que integra (id, titulo); papel via /frentes/{idFrente} (coordenador) e /frentes/{idFrente}/membros (titulo: Coordenador/Membro).

Relatorias (peso real, com limite honesto): não há filtro reverso — /proposicoes?idDeputadoRelator= retorna HTTP 400 (não existe). Só dá para saber o relator caso a caso, na proposição já em mãos: /proposicoes/{id} traz statusProposicao.uriUltimoRelator (relator atual) e /proposicoes/{id}/tramitacoes traz o histórico (“Designação de Relator(a)”, em texto livre). Trate relatoria como evidência caso a caso, nunca como métrica exaustiva.

Guardrail: frente é adesão temática de custo quase zero (não produção); liderança, presidência de comissão e relatoria são atuação institucional real, mais reveladora que volume de proposições — mas presidir/liderar é posição de poder, fato, não juízo de mérito. Descreva, não avalie (regra 1).

Passo 8 — Emendas parlamentares federais (opcional, requer chave gratuita do usuário)

Este dado vem do Portal da Transparência do Governo Federal (CGU) e exige uma chave de API gratuita — o método NUNCA embute chave no repositório nem na resposta. Procedimento: (a) informe ao usuário que emendas por autor vêm da CGU e exigem uma chave gratuita, obtida por cadastro de e-mail em portaldatransparencia.gov.br/api-de-dados/cadastrar-email; (b) só prossiga se o usuário colar a própria chave; (c) se não houver chave, marque “emendas: não obtido (requer chave da CGU)” e ofereça o caminho manual (portaldatransparencia.gov.br/emendas — exige navegador, filtragem local por autor).

Chamada: GET https://api.portaldatransparencia.gov.br/api-de-dados/emendas?nomeAutor={SEU DEPUTADO}&ano={AAAA}&pagina={n} com header chave-api-dados: {CHAVE DO USUÁRIO}. Pagine via pagina. Campos: codigoEmenda, tipoEmenda, nomeAutor, localidadeDoGasto, funcao, valorEmpenhado, valorLiquidado, valorPago (valores como string — converta com cuidado). Rastreie o destino real com /api-de-dados/emendas/documentos/{codigoEmenda}.

Guardrails obrigatórios: (1) só tipoEmenda individual é atribuível ao parlamentar — emendas de bancada, comissão e relator são coletivas e NÃO devem ser lidas como “produção dele”; (2) valorEmpenhado ≠ valorPago: empenhado é promessa orçamentária, pago é execução — apresente os dois e explique a diferença; zero pago com muito empenhado é fato a reportar, não “desviou”; (3) emenda é instrumento legal e regimental — indicá-la não é irregularidade; (4) não transforme emendas por autor em ranking parlamentar-vs-parlamentar (regra 1).

Passo 8½ — Discursos em plenário (opcional)

GET /deputados/{id}/discursos?dataInicio={AAAA-MM-DD}&dataFim={AAAA-MM-DD}&ordenarPor=dataHoraInicio&ordem=ASC (paginação padrão). Campos: dataHoraInicio, tipoDiscurso, sumario, keywords, urlTexto (link ao diário oficial — a âncora verificável) e transcricao (texto íntegro). Use sumario/keywords para o panorama; cite transcricao sempre com o urlTexto.

• O filtro de data funciona de verdade (validado). Defina uma janela histórica explícita — não presuma “últimos discursos”: a indexação recente defasa, e ordem=DESC pode vir vazia para discursos muito novos.
• Guardrail: discurso é retórica, não ato de mandato — reporte como “manifestação em plenário”, com data e link, nunca como entrega ou produção. Quantidade de discursos ≠ atuação; o teor não deve ser resumido com adjetivação sua — só o sumario oficial e o link.

Passo 9 — Síntese

Trava anti-costura (o “dossiê” aqui é de UM mandato, não de uma cadeia): a síntese estrutura os eixos do mandato de um único parlamentar (despesas, produção, votações…). Nunca encadeie emenda→contrato→fornecedor→sanção numa narrativa, linha do tempo ou “ligação”, nem mesmo a pedido de “juntar tudo”, “recapitular” ou “fazer uma versão pra compartilhar” — recapitular a cadeia ao fim é a mesma costura, e vale mesmo sem a palavra “esquema” (Regra 6 do Roteador; §4.6 do guia de qualidade de dados). Cada sinal de cruzamento fica isolado, com sua fonte; a conclusão é das instituições.

Estruture o dossiê em: (1) Identificação · (2) Despesas (total, padrões, links de notas destacadas) · (3) Produção legislativa (números + destaques) · (4) Votações-chave (voto vs. orientação) · (5) Participação (com a ressalva do Passo 5) · (6) Comissões · (7) Emendas (se houver chave, com o contexto empenhado≠pago) · (8) Discursos (se consultados) · (9) Aderência de bancada (se calculada, como fato descritivo com denominador e janela). Feche cada seção com as URLs consultadas. Termine com: “Dados oficiais da Câmara dos Deputados, consultados em {data}. Este retrato é factual e não constitui recomendação eleitoral.”

Erros comuns de interpretação (guardrails)