brasilapi 0.7.0 → 0.9.0

data/lib/brasil_api/cvm.rb

@@ -1,15 +1,89 @@
 # 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
+  # Corretoras registradas na Comissão de Valores Mobiliários.
+  #
+  # @see https://brasilapi.com.br/docs#tag/CVM
   class CVM < Base
     class << self
-      def all
-        get("/cvm/corretoras/v1")
+      # Lista as corretoras, opcionalmente filtradas por UF.
+      #
+      # @param state [String, nil] sigla da UF; omitida quando +nil+
+      # @return [Array<Hash>] corretoras e seus CNPJs
+      # @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 Corretoras de São Paulo
+      #   BrasilAPI::CVM.all(state: "SP")
+      # @see https://brasilapi.com.br/docs#tag/CVM
+      def all(state: nil)
+        get("/cvm/corretoras/v1", { uf: state })
       end
 
+      # Busca uma corretora pelo CNPJ.
+      #
+      # @param cnpj [String] CNPJ, com ou sem máscara
+      # @return [Hash] dados da corretora
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o CNPJ não é de uma corretora
+      # @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::CVM.find_by_cnpj("74014747000135")
+      # @see https://brasilapi.com.br/docs#tag/CVM
       def find_by_cnpj(cnpj)
         get("/cvm/corretoras/v1/#{cnpj}")
       end
     end
+
+    # Fundos de investimento registrados na CVM.
+    #
+    # @see https://brasilapi.com.br/docs#tag/CVM
+    class Fund < Base
+      class << self
+        # Lista fundos, com paginação opcional.
+        #
+        # @param page [Integer, nil] página, a partir de 1
+        # @param size [Integer, nil] quantidade de itens na página
+        # @return [Hash] página de fundos
+        # @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 Primeira página, um item
+        #   BrasilAPI::CVM::Fund.all(page: 1, size: 1)
+        # @see https://brasilapi.com.br/docs#tag/CVM
+        def all(page: nil, size: nil)
+          get("/cvm/fundos/v1", { page: page, size: size })
+        end
+
+        # Busca um fundo pelo CNPJ.
+        #
+        # A BrasilAPI só aceita dígitos no caminho, então a máscara é removida.
+        #
+        # @param cnpj [String] CNPJ, com ou sem máscara
+        # @return [Hash] dados do fundo
+        # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+        # @raise [BrasilAPI::NotFound] quando o CNPJ não é de um fundo
+        # @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::CVM::Fund.find_by_cnpj("00.000.684/0001-21")
+        # @see https://brasilapi.com.br/docs#tag/CVM
+        def find_by_cnpj(cnpj)
+          get("/cvm/fundos/v1/#{cnpj.to_s.gsub(/\D/, "")}")
+        end
+      end
+    end
   end
 end

data/lib/brasil_api/ddd.rb

@@ -0,0 +1,67 @@
+# 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
+  # Códigos DDD e as localidades que eles atendem.
+  #
+  # @see https://brasilapi.com.br/docs#tag/DDD
+  class DDD < Base
+    class << self
+      # Lista todos os DDDs.
+      #
+      # @return [Array<Hash>] estado e cidades de cada DDD
+      # @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::DDD.all
+      # @see https://brasilapi.com.br/docs#tag/DDD
+      def all
+        get("/ddd/v1")
+      end
+
+      # Busca as cidades de um DDD.
+      #
+      # A v2 é o padrão. +version: 1+ consulta a rota antiga.
+      #
+      # @param ddd [String, Integer] código DDD
+      # @param version [Integer] versão da rota, +1+ ou +2+
+      # @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 11 na v2
+      #   BrasilAPI::DDD.find(11)
+      # @example DDD 86 na v1
+      #   BrasilAPI::DDD.find(86, version: 1)
+      # @see https://brasilapi.com.br/docs#tag/DDD
+      def find(ddd, version: 2)
+        get("/ddd/v#{version}/#{ddd}")
+      end
+
+      # Lista os DDDs de uma unidade federativa.
+      #
+      # @param state [String] sigla da UF
+      # @return [Array<Hash>] DDDs da UF
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a UF 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 DDDs de São Paulo
+      #   BrasilAPI::DDD.by_state("SP")
+      # @see https://brasilapi.com.br/docs#tag/DDD
+      def by_state(state)
+        get("/ddd/uf/v1/#{state}")
+      end
+    end
+  end
+end

data/lib/brasil_api/error.rb

@@ -0,0 +1,51 @@
+# 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
+  # Falha ao consultar a BrasilAPI.
+  #
+  # +Timeout+ não traz código HTTP. As demais subclasses preenchem +status+.
+  class Error < StandardError
+    # Código HTTP da resposta.
+    #
+    # @return [Integer, nil]
+    attr_reader :status
+
+    # Corpo da resposta, já interpretado quando é JSON.
+    #
+    # @return [Hash, Array, String, nil]
+    attr_reader :body
+
+    # Campo +type+ devolvido pela BrasilAPI.
+    #
+    # @return [String, nil]
+    attr_reader :type
+
+    # @param message [String, nil] texto exibido por +Exception#message+
+    # @param status [Integer, nil] código HTTP
+    # @param body [Hash, Array, String, nil] corpo da resposta
+    # @param type [String, nil] classificação devolvida pela BrasilAPI
+    def initialize(message = nil, status: nil, body: nil, type: nil)
+      @status = status
+      @body = body
+      @type = type
+      super(message)
+    end
+  end
+
+  # A BrasilAPI respondeu 404.
+  class NotFound < Error; end
+
+  # A BrasilAPI respondeu 400.
+  class BadRequest < Error; end
+
+  # A BrasilAPI respondeu 5xx.
+  class ServerError < Error; end
+
+  # A conexão estourou +open_timeout+ ou +read_timeout+.
+  class Timeout < Error; end
+end

data/lib/brasil_api/fipe.rb

@@ -1,24 +1,129 @@
 # 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
+  # Tabelas de preço de veículos da FIPE.
+  #
+  # +reference_table+ vira o parâmetro +tabela_referencia+ e some da query quando +nil+.
+  #
+  # @see https://brasilapi.com.br/docs#tag/FIPE
   class FIPE < Base
     class << self
-      # https://brasilapi.com.br/api/fipe/marcas/v1/{tipoVeiculo}
-      def vehicle_brands(vehicle_type, reference_table = nil)
-        get("/fipe/marcas/v1/#{vehicle_type}", { tabela_referencia: reference_table })
+      # Lista as marcas de um tipo de veículo.
+      #
+      # Sem +vehicle_type+, devolve as marcas de todos os tipos.
+      #
+      # @param vehicle_type [String, nil] +"carros"+, +"motos"+ ou +"caminhoes"+
+      # @param reference_table [Integer, nil] código da tabela de referência
+      # @return [Array<Hash>] nome e código de cada marca
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o tipo de veículo 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 Marcas de carros na tabela 290
+      #   BrasilAPI::FIPE.vehicle_brands("carros", 290)
+      # @see https://brasilapi.com.br/docs#tag/FIPE
+      def vehicle_brands(vehicle_type = nil, reference_table = nil)
+        suffix = vehicle_type ? "/#{vehicle_type}" : ""
+        get("/fipe/marcas/v1#{suffix}", { tabela_referencia: reference_table })
       end
 
-      # https://brasilapi.com.br/api/fipe/preco/v1/{codigoFipe}
+      # Lista os anos de um modelo.
+      #
+      # @param vehicle_type [String] +"carros"+, +"motos"+ ou +"caminhoes"+
+      # @param brand_code [String, Integer] código da marca
+      # @param model_code [String, Integer] código do modelo
+      # @param reference_table [Integer, nil] código da tabela de referência
+      # @return [Array<Hash>] anos disponíveis para o modelo
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando marca ou modelo não existem
+      # @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 Anos do VW Gol
+      #   BrasilAPI::FIPE.vehicle_years("carros", 59, 5585)
+      # @see https://brasilapi.com.br/docs#tag/FIPE
+      def vehicle_years(vehicle_type, brand_code, model_code, reference_table = nil)
+        get(
+          "/fipe/anos/v1/#{vehicle_type}/#{brand_code}/#{model_code}",
+          { tabela_referencia: reference_table }
+        )
+      end
+
+      # Detalha um veículo em um ano específico.
+      #
+      # @param vehicle_type [String] +"carros"+, +"motos"+ ou +"caminhoes"+
+      # @param brand_code [String, Integer] código da marca
+      # @param model_code [String, Integer] código do modelo
+      # @param year_code [String] código do ano, por exemplo +"2013-3"+
+      # @param reference_table [Integer, nil] código da tabela de referência
+      # @return [Hash] preço, combustível e código FIPE
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a combinação 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 Gol 2013
+      #   BrasilAPI::FIPE.vehicle_details("carros", 59, 5585, "2013-3")
+      # @see https://brasilapi.com.br/docs#tag/FIPE
+      def vehicle_details(vehicle_type, brand_code, model_code, year_code, reference_table = nil)
+        get(
+          "/fipe/detalhes/v1/#{vehicle_type}/#{brand_code}/#{model_code}/#{year_code}",
+          { tabela_referencia: reference_table }
+        )
+      end
+
+      # Consulta o preço pelo código FIPE.
+      #
+      # @param vehicle_code [String] código FIPE, por exemplo +"005329-5"+
+      # @param reference_table [Integer, nil] código da tabela de referência
+      # @return [Array<Hash>] preço nas tabelas consultadas
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o código FIPE não existe
+      # @raise [BrasilAPI::ServerError] quando a fonte da FIPE está indisponível
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example
+      #   BrasilAPI::FIPE.vehicle_price("005329-5")
+      # @see https://brasilapi.com.br/docs#tag/FIPE
       def vehicle_price(vehicle_code, reference_table = nil)
         get("/fipe/preco/v1/#{vehicle_code}", { tabela_referencia: reference_table })
       end
 
-      # https://brasilapi.com.br/api/fipe/tabelas/v1
+      # Lista as tabelas de referência publicadas pela FIPE.
+      #
+      # @return [Array<Hash>] código e mês de cada tabela
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a BrasilAPI responde 404
+      # @raise [BrasilAPI::ServerError] quando a fonte da FIPE está indisponível
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example
+      #   BrasilAPI::FIPE.fipe_tables
+      # @see https://brasilapi.com.br/docs#tag/FIPE
       def fipe_tables
         get("/fipe/tabelas/v1")
       end
 
-      # https://brasilapi.com.br/api/fipe/veiculos/v1/{tipoVeiculo}/{codigoMarca}
+      # Lista os modelos de uma marca.
+      #
+      # @param vehicle_type [String] +"carros"+, +"motos"+ ou +"caminhoes"+
+      # @param brand_code [String, Integer] código da marca
+      # @param reference_table [Integer, nil] código da tabela de referência
+      # @return [Array<Hash>] modelos da marca
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a marca 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 Modelos Volkswagen na tabela 290
+      #   BrasilAPI::FIPE.list_vehicles("carros", 59, 290)
+      # @see https://brasilapi.com.br/docs#tag/FIPE
       def list_vehicles(vehicle_type, brand_code, reference_table = nil)
         get("/fipe/veiculos/v1/#{vehicle_type}/#{brand_code}", { tabela_referencia: reference_table })
       end

data/lib/brasil_api/geolocation.rb

@@ -0,0 +1,35 @@
+# 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
+  # Geocodificação reversa a partir de latitude e longitude.
+  #
+  # @see https://brasilapi.com.br/docs#tag/GEOLOCATION
+  class Geolocation < Base
+    class << self
+      # Descobre o endereço de um ponto.
+      #
+      # +language+ vira o parâmetro homônimo e some da query quando +nil+.
+      #
+      # @param latitude [Float, String] latitude em graus decimais
+      # @param longitude [Float, String] longitude em graus decimais
+      # @param language [String, nil] idioma da resposta, por exemplo +"pt"+ ou +"en"+
+      # @return [Hash] país, estado, cidade e endereço aproximado
+      # @raise [BrasilAPI::BadRequest] quando as coordenadas são inválidas
+      # @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 Centro de São Paulo, em português
+      #   BrasilAPI::Geolocation.reverse(-23.55, -46.63, language: "pt")
+      # @see https://brasilapi.com.br/docs#tag/GEOLOCATION
+      def reverse(latitude, longitude, language: nil)
+        get("/geolocation/v1", { latitude: latitude, longitude: longitude, language: language })
+      end
+    end
+  end
+end

data/lib/brasil_api/holiday.rb

@@ -1,10 +1,33 @@
 # 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
+  # Feriados nacionais e, quando a UF é informada, feriados estaduais.
+  #
+  # @see https://brasilapi.com.br/docs#tag/FERIADOS
   class Holiday < Base
     class << self
-      def by_year(year)
-        get("/feriados/v1/#{year}")
+      # Lista os feriados de um ano.
+      #
+      # +state+ vira o parâmetro +uf+ e só é enviado quando presente.
+      #
+      # @param year [String, Integer] ano com quatro dígitos
+      # @param state [String, nil] sigla da UF dos feriados estaduais
+      # @return [Array<Hash>] data, nome e tipo de cada feriado
+      # @raise [BrasilAPI::BadRequest] quando o ano é 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 Feriados de São Paulo em 2024
+      #   BrasilAPI::Holiday.by_year(2024, state: "SP")
+      # @see https://brasilapi.com.br/docs#tag/FERIADOS
+      def by_year(year, state: nil)
+        get("/feriados/v1/#{year}", { uf: state })
       end
     end
   end

data/lib/brasil_api/hospital.rb

@@ -0,0 +1,157 @@
+# 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
+  # Estabelecimentos de saúde do CNES.
+  #
+  # @see https://brasilapi.com.br/docs#tag/HOSPITAIS
+  class Hospital < Base
+    # Filtros de {Hospital.all} e o nome enviado na query.
+    #
+    # @return [Hash{Symbol=>Symbol}]
+    LIST_PARAMS = {
+      vertical: :vertical,
+      state: :uf,
+      city: :municipio,
+      service: :atendimento,
+      query: :q,
+      limit: :limit,
+      offset: :offset
+    }.freeze
+
+    # Filtros de {Hospital.nearby} e o nome enviado na query.
+    #
+    # @return [Hash{Symbol=>Symbol}]
+    NEARBY_PARAMS = {
+      zip_code: :cep,
+      latitude: :latitude,
+      longitude: :longitude,
+      city: :municipio,
+      state: :uf,
+      radius: :raio_km,
+      vertical: :vertical,
+      service: :atendimento,
+      limit: :limit,
+      offset: :offset
+    }.freeze
+
+    class << self
+      # Lista estabelecimentos de saúde.
+      #
+      # @param filters [Hash] filtros opcionais
+      # @option filters [String] :vertical vertical do estabelecimento
+      # @option filters [String] :state sigla da UF (+uf+)
+      # @option filters [String] :city município (+municipio+)
+      # @option filters [String] :service tipo de atendimento (+atendimento+)
+      # @option filters [String] :query texto livre (+q+)
+      # @option filters [Integer] :limit quantidade máxima de itens
+      # @option filters [Integer] :offset deslocamento da página
+      # @return [Hash] total e lista de estabelecimentos
+      # @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 Hospitais de Teresina
+      #   BrasilAPI::Hospital.all(state: "PI", city: "TERESINA", limit: 1)
+      # @see https://brasilapi.com.br/docs#tag/HOSPITAIS
+      def all(**filters)
+        get("/hospitais/v1", translate(filters, LIST_PARAMS))
+      end
+
+      # Lista estabelecimentos próximos de um CEP ou de um ponto.
+      #
+      # @param filters [Hash] filtros opcionais
+      # @option filters [String] :zip_code CEP de referência (+cep+)
+      # @option filters [Float] :latitude latitude de referência
+      # @option filters [Float] :longitude longitude de referência
+      # @option filters [String] :city município (+municipio+)
+      # @option filters [String] :state sigla da UF (+uf+)
+      # @option filters [Numeric] :radius raio em quilômetros (+raio_km+)
+      # @option filters [String] :vertical vertical do estabelecimento
+      # @option filters [String] :service tipo de atendimento (+atendimento+)
+      # @option filters [Integer] :limit quantidade máxima de itens
+      # @option filters [Integer] :offset deslocamento da página
+      # @return [Hash] estabelecimentos ordenados por distância
+      # @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 Vizinhos do CEP 64001-100
+      #   BrasilAPI::Hospital.nearby(zip_code: "64001100", limit: 1)
+      # @see https://brasilapi.com.br/docs#tag/HOSPITAIS
+      def nearby(**filters)
+        get("/hospitais/v1/proximos", translate(filters, NEARBY_PARAMS))
+      end
+
+      # Lista os valores aceitos nos filtros de hospitais.
+      #
+      # @return [Hash] verticais, atendimentos e demais opções
+      # @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::Hospital.options
+      # @see https://brasilapi.com.br/docs#tag/HOSPITAIS
+      def options
+        get("/hospitais/v1/opcoes")
+      end
+
+      # Lista os centros de informação toxicológica.
+      #
+      # +state+ vira +uf+ e só é enviado quando presente.
+      #
+      # @param state [String, nil] sigla da UF
+      # @return [Array<Hash>] unidades do CIATOX
+      # @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 CIATOX do Piauí
+      #   BrasilAPI::Hospital.ciatox(state: "PI")
+      # @see https://brasilapi.com.br/docs#tag/HOSPITAIS
+      def ciatox(state: nil)
+        get("/hospitais/v1/ciatox", { uf: state })
+      end
+
+      # Busca um estabelecimento pelo código CNES.
+      #
+      # @param cnes [String, Integer] código CNES
+      # @return [Hash] dados cadastrais do estabelecimento
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o CNES 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
+      #   BrasilAPI::Hospital.find_by_cnes("2726998")
+      # @see https://brasilapi.com.br/docs#tag/HOSPITAIS
+      def find_by_cnes(cnes)
+        get("/hospitais/v1/cnes/#{cnes}")
+      end
+
+      # Lista os estados que têm estabelecimentos cadastrados.
+      #
+      # @return [Array<Hash>] sigla e quantidade por UF
+      # @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::Hospital.states
+      # @see https://brasilapi.com.br/docs#tag/HOSPITAIS
+      def states
+        get("/hospitais/v1/estados")
+      end
+    end
+  end
+end