brasilapi 0.7.0 → 0.9.0

data/README.md

@@ -3,157 +3,393 @@
 
 </div>
 
-Dependency-less Brasil API lookup gem for brazilian data with an easy-to-use API.
-
-## Features
- - [x] **Bank**
- - [x] **CEP (Zip code)**
- - [x] **CNPJ**
- - [x] **Corretoras**
- - [x] **CPTEC**
- - [x] **DDD**
- - [x] **Feriados Nacionais**
- - [x] **FIPE**
- - [x] **IBGE**
- - [x] **ISBN**
- - [x] **NCM**
- - [x] **PIX**
- - [x] **Registros BR**
- - [x] **Taxas**
-
-## Installation
-
-Install the gem and add to the application's Gemfile by executing:
+Gem em Ruby, sem dependências de runtime, para consultar a [BrasilAPI](https://brasilapi.com.br).
+
+## Funcionalidades
+
+- [x] **Bancos**
+- [x] **CEP** (v1 e v2)
+- [x] **CNPJ**
+- [x] **CPF**
+- [x] **Corretoras da CVM** e **fundos**
+- [x] **CPTEC** (cidades, clima e ondas)
+- [x] **DDD** (lista, v1, v2 e por UF)
+- [x] **Feriados** nacionais e estaduais
+- [x] **FIPE**
+- [x] **IBGE** (UFs, municípios, regiões e CNAE)
+- [x] **ISBN**
+- [x] **NCM**
+- [x] **PIX**
+- [x] **Registro.br**
+- [x] **Taxas**
+- [x] **Câmbio**
+- [x] **Dias úteis**
+- [x] **Geolocalização**
+- [x] **Hospitais**
+- [x] **IBPT**
+- [x] **IGP-M**
+- [x] **CID-10**
+- [x] **Incidência solar**
+- [x] **Status**
+- [x] **Tickers da B3**
+- [x] **TUSS**
+
+CEP v3, previsão semanal do CPTEC por coordenadas, eleições e universidades ficam de fora enquanto a BrasilAPI não responder com sucesso nessas rotas.
+
+## Instalação
+
+Adicione a gem ao Gemfile da aplicação:
 
     $ bundle add brasilapi
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Sem Bundler:
 
     $ gem install brasilapi
 
-## Usage
+## Documentação
+
+A referência da gem, gerada com YARD, fica em [rubydoc.info/gems/brasilapi](https://rubydoc.info/gems/brasilapi) depois da publicação.
+
+Para navegar nela na máquina local:
+
+    $ bundle exec yard server
+
+O servidor sobe em [http://localhost:8808](http://localhost:8808). O Ruby 3.3 não inclui mais o Webrick, então ele entra como dependência de desenvolvimento. `bundle exec rake yard` só gera os arquivos em `doc/`.
+
+## Configuração
+
+O tempo limite padrão é de 10 segundos (`open_timeout` e `read_timeout`):
 
 ```ruby
-require 'brasilapi'
+BrasilAPI.configure do |config|
+  config.timeout = 30
+end
+```
+
+`Net::OpenTimeout` e `Net::ReadTimeout` sobem como `BrasilAPI::Timeout`. Falhas HTTP são `BrasilAPI::Error` (ou uma subclasse: `NotFound`, `BadRequest` e `ServerError`) e expõem `status`, `message`, `type` e `body`.
 
-# get all banks
+```ruby
+begin
+  BrasilAPI::Bank.find_by_code(0)
+rescue BrasilAPI::NotFound => e
+  e.status  # 404
+  e.message
+  e.type
+rescue BrasilAPI::Error => e
+  e.status
+end
+```
+
+## Uso
+
+```ruby
+require "brasilapi"
+```
+
+### Bancos
+
+```ruby
+# lista os bancos
 BrasilAPI::Bank.all
-=> 
-[{"ispb"=>"00000000", "name"=>"BCO DO BRASIL S.A.", "code"=>1, "fullName"=>"Banco do Brasil S.A."},
-{"ispb"=>"00000208", "name"=>"BRB - BCO DE BRASILIA S.A.", "code"=>70, "fullName"=>"BRB - BANCO DE BRASILIA S.A."},
-...]
 
-# find bank by code
+# busca um banco pelo código
 BrasilAPI::Bank.find_by_code(77)
-=> {"ispb"=>"00416968", "name"=>"BANCO INTER", "code"=>77, "fullName"=>"Banco Inter S.A."}
+```
+
+### CNPJ
 
-# find company by cnpj
+```ruby
+# busca uma empresa pelo CNPJ
 BrasilAPI::Company.find_by_cnpj("60316817000103")
-=> 
-{"uf"=>"SP",
- "cep"=>"04543907",
- "qsa"=>
-  [{"pais"=>"ESTADOS UNIDOS",
-  ...}
-
-# find address by zip code
-BrasilAPI::Address.find_by_zip_code('64001100')
-=> {"cep"=>"64001100", "state"=>"PI", "city"=>"Teresina", "neighborhood"=>"Centro", "street"=>"Praça Pedro II", "service"=>"correios"}
-
-# find address with location by zip code
-BrasilAPI::Address.find_by_zip_code('80060000', location: true)
-=> 
-{"cep"=>"80060000",
- "state"=>"PR",
- ...
- "location"=>{"type"=>"Point", "coordinates"=>{"longitude"=>"-49.2614791", "latitude"=>"-25.427253"}}}
-
-# get state and cities by area code
-BrasilAPI::Address.state_and_cities_by_area_code('89')
-=> 
-{"state"=>"PI",
- "cities"=>
- ["MASSÂPE DO PIAUÍ",
-  ...,
-  "ACAUÃ"
- ]}
-
-# get all CVM brokers
+```
+
+### CPF
+
+A rota devolve só validade e região fiscal, sem nome. O CPF pode ir com ou sem pontuação.
+
+```ruby
+BrasilAPI::CPF.find("000.000.000-00")
+# => {"isValid"=>false}
+```
+
+### CEP
+
+`location: true` continua sendo o atalho da v2.
+
+```ruby
+# CEP na v1
+BrasilAPI::Address.find_by_zip_code("64001100")
+
+# CEP na v2, com coordenadas
+BrasilAPI::Address.find_by_zip_code("80060000", location: true)
+```
+
+### DDD
+
+`Address.state_and_cities_by_area_code` permanece como atalho da v1.
+
+```ruby
+# cada estado e seus DDDs
+BrasilAPI::DDD.all
+
+# v2: lista de estados e cidades (DDDs que cobrem mais de um estado)
+BrasilAPI::DDD.find("11")
+
+# v1: um estado e as cidades
+BrasilAPI::DDD.find("86", version: 1)
+BrasilAPI::Address.state_and_cities_by_area_code("86")
+
+# DDDs de uma UF
+BrasilAPI::DDD.by_state("SP")
+```
+
+### CVM
+
+```ruby
+# corretoras; uf só é enviado quando state é informado
 BrasilAPI::CVM.all
-=> 
-[{"cnpj"=>"76621457000185",
-  "type"=>"CORRETORAS",
-  ...]
-
-# find bank by code
-BrasilAPI::CVM.find_by_cnpj('74014747000135')
-=> 
-{"cnpj"=>"74014747000135",
- "type"=>"CORRETORAS",
- ...}
-
-# get brazilian national holidays by year
+BrasilAPI::CVM.all(state: "SP")
+
+# busca a corretora da CVM pelo CNPJ
+BrasilAPI::CVM.find_by_cnpj("74014747000135")
+
+# fundos de investimento
+BrasilAPI::CVM::Fund.all(page: 1, size: 1)
+BrasilAPI::CVM::Fund.find_by_cnpj("00.000.684/0001-21")
+```
+
+### Feriados
+
+```ruby
+# feriados nacionais; uf não é enviado
 BrasilAPI::Holiday.by_year(2024)
-=> 
-[{"date"=>"2024-01-01", "name"=>"Confraternização mundial", "type"=>"national"},
- ...
- {"date"=>"2024-12-25", "name"=>"Natal", "type"=>"national"}]
 
-# get states from ibge
+# inclui os feriados estaduais
+BrasilAPI::Holiday.by_year(2024, state: "SP")
+```
+
+### IBGE
+
+Providers aceitos em `cities_by_state`: os mesmos da BrasilAPI, por exemplo `dados-abertos-br`, `gov` e `wikipedia`.
+
+```ruby
 BrasilAPI::IBGE.states
-=> 
-[{"id"=>11,
-  "sigla"=>"RO"
-  "nome"=>"Rondônia",
-  "regiao"=>{"id"=>1, "sigla"=>"N", "nome"=>"Norte"}},
-  ...
-   {"id"=>53,
-  "sigla"=>"DF",
-  "nome"=>"Distrito Federal",
-  "regiao"=>{"id"=>5, "sigla"=>"CO", "nome"=>"Centro-Oeste"}}]
-
-# find state by abbreviation from ibge
-BrasilAPI::IBGE.find_state_by_code('PI')
-=> 
-{"id"=>22,
- "sigla"=>"PI",
- "nome"=>"Piauí",
- "regiao"=>{"id"=>2, "sigla"=>"NE", "nome"=>"Nordeste"}}
-
-# find state by code from ibge
+BrasilAPI::IBGE.find_state_by_code("PI")
 BrasilAPI::IBGE.find_state_by_code(53)
-=> 
-{"id"=>53,
- "sigla"=>"DF",
- "nome"=>"Distrito Federal",
- "regiao"=>{"id"=>5, "sigla"=>"CO", "nome"=>"Centro-Oeste"}}
+BrasilAPI::IBGE.cities_by_state("CE")
+BrasilAPI::IBGE.cities_by_state("PI", providers: ["gov"])
+
+BrasilAPI::IBGE.regions
+BrasilAPI::IBGE.find_region_by_code(1)
+BrasilAPI::IBGE.states_by_region(1)
+```
+
+### CNAE
+
+```ruby
+BrasilAPI::IBGE::CNAE.classes
+BrasilAPI::IBGE::CNAE.find_class("01113")
+BrasilAPI::IBGE::CNAE.find_division("01")
+BrasilAPI::IBGE::CNAE.find_group("011")
+```
+
+### CPTEC
+
+`city_weather` e `ocean_forecast` aceitam até 6 dias com precisão garantida pela BrasilAPI.
+
+```ruby
+BrasilAPI::CPTEC.all
+BrasilAPI::CPTEC.search_location("São Francisco")
+BrasilAPI::CPTEC.capital_weather
+BrasilAPI::CPTEC.airport_weather("SBGR")
+BrasilAPI::CPTEC.city_weather(4801)
+BrasilAPI::CPTEC.city_weather(4801, 6)
+BrasilAPI::CPTEC.ocean_forecast(4701)
+BrasilAPI::CPTEC.ocean_forecast(4701, 6)
+```
+
+### FIPE
+
+`reference_table` é opcional. Quando fica `nil`, a gem não envia `tabela_referencia`. Sem `vehicle_type`, `vehicle_brands` lista as marcas de todos os tipos.
+
+```ruby
+BrasilAPI::FIPE.vehicle_brands
+BrasilAPI::FIPE.vehicle_brands("carros")
+BrasilAPI::FIPE.vehicle_brands("carros", 290)
+BrasilAPI::FIPE.list_vehicles("carros", 59)
+BrasilAPI::FIPE.vehicle_years("carros", 59, 5585)
+BrasilAPI::FIPE.vehicle_details("carros", 59, 5585, "2013-3")
+BrasilAPI::FIPE.vehicle_price("005329-5")
+BrasilAPI::FIPE.fipe_tables
+```
+
+### ISBN
+
+Providers aceitos: `cbl`, `mercado-editorial`, `open-library` e `google-books`.
+
+```ruby
+BrasilAPI::ISBN.search("9788545702870")
+BrasilAPI::ISBN.search("9788545702870", providers: ["open-library"])
+```
+
+### NCM
+
+```ruby
+BrasilAPI::NCM.all
+BrasilAPI::NCM.search("cafe")
+BrasilAPI::NCM.find_by_code("01012100")
+```
+
+### PIX
 
-# get cities by state abbreviation from ibge
-BrasilAPI::IBGE.cities_by_state('CE')
-=> 
-[{"nome"=>"ABAIARA", "codigo_ibge"=>"2300101"},
- ...
- {"nome"=>"VÁRZEA ALEGRE", "codigo_ibge"=>"2314003"},
- {"nome"=>"VIÇOSA DO CEARÁ", "codigo_ibge"=>"2314102"}]
+```ruby
+BrasilAPI::PIX.all
 ```
 
+### Registro.br
+
+```ruby
+BrasilAPI::RegistroBR.whois("google.com.br")
+```
+
+### Taxas
+
+```ruby
+BrasilAPI::Taxas.all
+BrasilAPI::Taxas.find_by_name("selic")
+```
+
+### Câmbio
+
+`quote` aceita `Date` ou `String` no formato `YYYY-MM-DD`.
+
+```ruby
+BrasilAPI::Cambio.currencies
+BrasilAPI::Cambio.quote("USD", Date.new(2024, 1, 15))
+```
+
+### Dias úteis
+
+`between` aceita `Date` ou `String`. `include_national_holidays: false` faz o dia útil incluir feriados nacionais. Sem o argumento, a BrasilAPI exclui esses feriados.
+
+```ruby
+BrasilAPI::BusinessDays.between("2024-01-01", "2024-01-10")
+BrasilAPI::BusinessDays.between(Date.new(2024, 1, 1), Date.new(2024, 1, 10), include_national_holidays: false)
+```
+
+### Geolocalização
+
+```ruby
+BrasilAPI::Geolocation.reverse(-23.55, -46.63)
+BrasilAPI::Geolocation.reverse(-23.55, -46.63, language: "en")
+```
+
+### Hospitais
+
+Filtros de `all`: `vertical`, `state`, `city`, `service`, `query`, `limit`, `offset`.
+
+`nearby` aceita `zip_code`, ou `latitude` e `longitude`, ou `city` e `state`, além de `radius`, `vertical`, `service`, `limit` e `offset`.
+
+```ruby
+BrasilAPI::Hospital.all(state: "PI", limit: 1)
+BrasilAPI::Hospital.nearby(zip_code: "64001100", limit: 1)
+BrasilAPI::Hospital.nearby(latitude: -5.09, longitude: -42.8, radius: 10, limit: 1)
+BrasilAPI::Hospital.options
+BrasilAPI::Hospital.ciatox(state: "SP")
+BrasilAPI::Hospital.find_by_cnes("2726998")
+BrasilAPI::Hospital.states
+```
+
+### IBPT
+
+`exception` corresponde ao query param `ex`. Sem `code`, a chamada devolve a tabela inteira da UF.
+
+```ruby
+BrasilAPI::IBPT.version
+BrasilAPI::IBPT.ncm("SP")
+BrasilAPI::IBPT.ncm("SP", "01012100")
+BrasilAPI::IBPT.ncm("PI", "02109100", exception: "01")
+BrasilAPI::IBPT.nbs("SP", "101011000")
+BrasilAPI::IBPT.lc116("SP", "0101")
+```
+
+### IGP-M
+
+`between` aceita `Date` ou `String`.
+
+```ruby
+BrasilAPI::IGPM.all
+BrasilAPI::IGPM.last(2)
+BrasilAPI::IGPM.between("2024-01-01", "2024-02-01")
+```
+
+### CID-10
+
+```ruby
+BrasilAPI::CID10.all
+BrasilAPI::CID10.find_by_code("A00")
+```
+
+### Incidência solar
+
+A rota usada é `GET /solar/v1?location=...`.
+
+```ruby
+BrasilAPI::Solar.incidence("Teresina")
+```
+
+### Status
+
+```ruby
+BrasilAPI::Status.check
+```
+
+### B3
+
+Tipos de fundo aceitos: `FII`, `SETORIAL`, `FIAGRO-FII`, `FIAGRO-FIDC`, `FIAGRO-FIP`, `FIP` e `FIA`.
+
+```ruby
+BrasilAPI::B3.stocks
+BrasilAPI::B3.funds("SETORIAL")
+```
+
+### TUSS
+
+`all` aceita `name`, `code`, `limit` e `offset`. `search` também aceita `query`, `match`, `sort`, `order` e `fields`. `autocomplete` aceita `query`, `name`, `code` e `limit`.
+
+```ruby
+BrasilAPI::TUSS.all(limit: 1)
+BrasilAPI::TUSS.find_by_code("10101012")
+BrasilAPI::TUSS.search(query: "consulta", limit: 1)
+BrasilAPI::TUSS.autocomplete(query: "cons", limit: 2)
+```
+
+## Publicação
+
+A publicação no RubyGems acontece quando um pull request que altera a versão entra na `main`:
+
+1. Atualize `BrasilAPI::VERSION` em `lib/brasil_api/version.rb`.
+2. Mova a seção `[Unreleased]` do `CHANGELOG.md` para essa versão, com a data.
+3. Abra um pull request e faça o merge na `main`.
+
+`.github/workflows/release.yml` roda a suíte (testes com cobertura e RuboCop), cria a tag `vX.Y.Z`, publica um GitHub Release com as notas daquela versão e envia a gem com Trusted Publishing do RubyGems (OIDC). Se a versão já tiver a tag `vX.Y.Z`, o workflow não faz nada.
+
+Antes da primeira publicação automática, registre um trusted publisher no rubygems.org para `dayvidemerson/brasilapi-rb` e o arquivo `release.yml`, sem environment do GitHub. O gemspec mantém `rubygems_mfa_required`.
 
-# License
-[MIT](./LICENSE)
+## Contribuindo
 
-## Contributing
+Relatos de bugs e pull requests são bem-vindos em https://github.com/dayvidemerson/brasilapi-rb. Este projeto deve ser um espaço seguro e acolhedor, e quem contribui deve seguir o [código de conduta](https://github.com/dayvidemerson/brasilapi-rb/blob/main/CODE_OF_CONDUCT.md).
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/dayvidemerson/brasilapi-rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/dayvidemerson/brasilapi-rb/blob/main/CODE_OF_CONDUCT.md).
+## Licença
 
-## License
+A gem é software livre sob a [licença MIT](https://opensource.org/licenses/MIT).
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Código de conduta
 
-## Code of Conduct
+Quem interage nos repositórios, issues, salas e listas deste projeto deve seguir o [código de conduta](https://github.com/dayvidemerson/brasilapi-rb/blob/main/CODE_OF_CONDUCT.md).
 
-Everyone interacting in the Brasilapi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/dayvidemerson/brasilapi-rb/blob/main/CODE_OF_CONDUCT.md).
+## Autor
 
-# Autor
 <div align="center">
 
 | [<img src="https://github.com/dayvidemerson.png?size=115" width=115><br><sub>@dayvidemerson</sub>](https://github.com/dayvidemerson) |

data/Rakefile

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
+require "open3"
 require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
@@ -9,4 +10,20 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+desc "Gera a documentação YARD em doc/"
+task :yard do
+  sh "yard", "doc"
+end
+
+desc "Falha se a documentação YARD não estiver em 100%"
+task :yard_stats do
+  output, status = Open3.capture2e("yard", "stats", "--list-undoc")
+  puts output
+  abort("yard stats --list-undoc falhou") unless status.success?
+
+  undocumented = output.scan(/\(\s*(\d+) undocumented\)/).flatten.map(&:to_i)
+  fully_documented = undocumented.any? && undocumented.all?(&:zero?) && output.match?(/100(?:\.0+)?% documented/)
+  abort("A documentação YARD não está em 100%.") unless fully_documented
+end
+
+task default: %i[spec yard_stats rubocop]

data/lib/brasil_api/address.rb

@@ -1,14 +1,52 @@
 # frozen_string_literal: true
 
+# Cliente Ruby da {https://brasilapi.com.br BrasilAPI}.
+#
+# @example Bancos participantes do STR
+#   BrasilAPI::Bank.all
+# @see https://brasilapi.com.br/docs
 module BrasilAPI
+  # Consulta CEP e o DDD de um código de área.
+  #
+  # @see https://brasilapi.com.br/docs#tag/CEP
+  # @see https://brasilapi.com.br/docs#tag/DDD
   class Address < Base
     class << self
+      # Busca o endereço de um CEP.
+      #
+      # Com +location: true+ a rota é a v2 e a resposta inclui coordenadas.
+      #
+      # @param zip_code [String] CEP, com ou sem hífen
+      # @param location [Boolean] usa +/cep/v2+ quando +true+
+      # @return [Hash] logradouro, bairro, cidade e UF
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o CEP não existe
+      # @raise [BrasilAPI::ServerError] quando a BrasilAPI responde 5xx
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example Avenida Frei Serafim, em Teresina
+      #   BrasilAPI::Address.find_by_zip_code("64001100")
+      # @example CEP com latitude e longitude
+      #   BrasilAPI::Address.find_by_zip_code("80060000", location: true)
+      # @see https://brasilapi.com.br/docs#tag/CEP
       def find_by_zip_code(zip_code, location: false)
         return get("/cep/v2/#{zip_code}") if location
 
         get("/cep/v1/#{zip_code}")
       end
 
+      # Lista o estado e as cidades de um DDD.
+      #
+      # @param area_code [String, Integer] código DDD, por exemplo +"11"+
+      # @return [Hash] estado e cidades atendidas
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o DDD não existe
+      # @raise [BrasilAPI::ServerError] quando a BrasilAPI responde 5xx
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example DDD de São Paulo
+      #   BrasilAPI::Address.state_and_cities_by_area_code(11)
+      # @see https://brasilapi.com.br/docs#tag/DDD
       def state_and_cities_by_area_code(area_code)
         get("/ddd/v1/#{area_code}")
       end

data/lib/brasil_api/b3.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Cliente Ruby da {https://brasilapi.com.br BrasilAPI}.
+#
+# @example Bancos participantes do STR
+#   BrasilAPI::Bank.all
+# @see https://brasilapi.com.br/docs
+module BrasilAPI
+  # Ações e fundos listados na B3.
+  #
+  # @see https://brasilapi.com.br/docs#tag/TICKERS
+  class B3 < Base
+    class << self
+      # Lista as ações negociadas na B3.
+      #
+      # @return [Array<Hash>] ticker, empresa e segmento de cada ação
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a BrasilAPI responde 404
+      # @raise [BrasilAPI::ServerError] quando a BrasilAPI responde 5xx
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example
+      #   BrasilAPI::B3.stocks
+      # @see https://brasilapi.com.br/docs#tag/TICKERS
+      def stocks
+        get("/tickers/b3/acoes/v1")
+      end
+
+      # Lista os fundos de um tipo da B3.
+      #
+      # Tipos aceitos: +"FII"+, +"SETORIAL"+, +"FIAGRO-FII"+, +"FIAGRO-FIDC"+,
+      # +"FIAGRO-FIP"+, +"FIP"+ e +"FIA"+.
+      #
+      # @param type [String] tipo do fundo
+      # @return [Array<Hash>] sigla e nome de cada fundo
+      # @raise [BrasilAPI::BadRequest] quando o tipo é inválido
+      # @raise [BrasilAPI::NotFound] quando a BrasilAPI responde 404
+      # @raise [BrasilAPI::ServerError] quando a BrasilAPI responde 5xx
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example Fundos setoriais
+      #   BrasilAPI::B3.funds("SETORIAL")
+      # @see https://brasilapi.com.br/docs#tag/TICKERS
+      def funds(type)
+        get("/tickers/b3/fundos/v1/#{type}")
+      end
+    end
+  end
+end

data/lib/brasil_api/bank.rb

@@ -1,12 +1,43 @@
 # frozen_string_literal: true
 
+# Cliente Ruby da {https://brasilapi.com.br BrasilAPI}.
+#
+# @example Bancos participantes do STR
+#   BrasilAPI::Bank.all
+# @see https://brasilapi.com.br/docs
 module BrasilAPI
+  # Bancos participantes do Sistema de Transferência de Reservas.
+  #
+  # @see https://brasilapi.com.br/docs#tag/BANKS
   class Bank < Base
     class << self
+      # Lista os bancos participantes do STR.
+      #
+      # @return [Array<Hash>] código, nome e ISPB de cada banco
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a BrasilAPI responde 404
+      # @raise [BrasilAPI::ServerError] quando a BrasilAPI responde 5xx
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example
+      #   BrasilAPI::Bank.all
+      # @see https://brasilapi.com.br/docs#tag/BANKS
       def all
         get("/banks/v1")
       end
 
+      # Busca um banco pelo código de compensação.
+      #
+      # @param code [String, Integer] código COMPE, por exemplo +77+
+      # @return [Hash] dados do banco
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o código não existe
+      # @raise [BrasilAPI::ServerError] quando a BrasilAPI responde 5xx
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example Banco Inter
+      #   BrasilAPI::Bank.find_by_code(77)
+      # @see https://brasilapi.com.br/docs#tag/BANKS
       def find_by_code(code)
         get("/banks/v1/#{code}")
       end