CongregaPlenum

Cliente Ruby para a API de Dados Abertos da Câmara dos Deputados, com paginação, retries, logging e serviços para deputados, partidos e legislaturas e votações. O projeto inclui assinaturas RBS e uma API orientada a sincronizações e aplicações de dados cívicos.

• Documentação da API
• Como contribuir
• Changelog
• Política de segurança
• Código de conduta

Requisitos

• Ruby 3.4 ou superior
• Bundler 2.7 ou compatível

Instalação

Adicione a gem ao seu Gemfile:

gem 'congrega_plenum', '~> 0.2.0'

Depois execute:

bundle install

Ou instale diretamente pelo RubyGems:

gem install congrega_plenum -v '~> 0.2.0'

Consulte a página da gem no RubyGems para conferir as versões publicadas.

Configuração

CongregaPlenum.configure do |config|
  config.base_url = 'https://dadosabertos.camara.leg.br/api/v2'
  config.timeout = 20
  config.retries = 5
  config.retry_delay = 1.0
  config.rate_limit_delay = 0.1
  config.logger = Logger.new($stdout)
end

Os valores padrão já apontam para os endpoints oficiais. Requisições são repetidas somente em falhas transitórias: conexão, HTTP 429 e HTTP 5xx. Erros 4xx e respostas inválidas são propagados para que uma sincronização parcial não seja confundida com uma resposta vazia.

Uso

Exemplo coletando os deputados de uma legislatura específica:

deputados = CongregaPlenum::CongressmenService.fetch_all_by_legislature(57)

deputados.each do |deputado|
  puts "#{deputado['ultimoStatus']['nomeEleitoral']} - #{deputado['id']}"
end

Outros fluxos disponíveis:

• CongregaPlenum::CongressmenService.fetch_list(page:, items_per_page:, legislature_id:)
• CongregaPlenum::CongressmenService.fetch_by_id(deputy_id)
• CongregaPlenum::PartiesService.fetch_all
• CongregaPlenum::LegislaturesService.fetch_mesa(legislature_id)
• CongregaPlenum::LegislaturesService.fetch_deputies(legislature_id)
• CongregaPlenum::VotingsService.fetch_all(start_date:, end_date:)
• CongregaPlenum::VotingsService.fetch_by_id(voting_id)
• CongregaPlenum::VotingsService.fetch_votes(voting_id)
• CongregaPlenum::VotingsService.fetch_orientations(voting_id)

Uma votação representa uma decisão legislativa individual já concluída. Uma proposição pode ser afetada por várias votações de pareceres, emendas, requerimentos e destaques relacionados. Por isso, detalhes, votos individuais e orientações de bancada são expostos separadamente:

votacoes = CongregaPlenum::VotingsService.fetch_all(
  proposition_ids: [2_345_678],
  start_date: '2026-01-01',
  end_date: '2026-12-31'
)

votacao = CongregaPlenum::VotingsService.fetch_by_id(votacoes.first['id'])
votos = CongregaPlenum::VotingsService.fetch_votes(votacao['id'])
orientacoes = CongregaPlenum::VotingsService.fetch_orientations(votacao['id'])

Sem filtros de data ou identificadores, a API da Câmara limita a listagem de votações aos 30 dias anteriores. As duas datas de um intervalo devem pertencer ao mesmo ano. Votações simbólicas normalmente não possuem votos individuais, e uma lista de votos vazia não identifica quais deputados estavam ausentes.

Para controle de baixo nível, use CongregaPlenum::Client. Consulte a documentação YARD para os contratos completos.

Desenvolvimento

bin/setup
bundle exec rake
bundle exec steep check
bundle exec yard doc
bundle exec rake build

• bundle exec rake executa RSpec e RuboCop.
• bundle exec steep check valida as assinaturas RBS.
• bundle exec yard doc gera a documentação em doc/.
• bundle exec rake build constrói a gem em pkg/.

Contribuindo

Issues e pull requests são bem-vindos. Antes de começar, leia o guia de contribuição e o código de conduta. Vulnerabilidades não devem ser abertas como issues públicas; siga a política de segurança.

Licença

Distribuído sob a GNU Affero General Public License v3.0 ou posterior. Aplicações que incorporam a gem e são distribuídas ou disponibilizadas para uso por rede devem observar as obrigações de código-fonte da AGPL.

CongregaPlenum é um projeto independente e não é afiliado à Câmara dos Deputados.