brasilapi 0.8.0 → 0.9.0

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

data/lib/brasil_api/base.rb

@@ -4,17 +4,68 @@ require "json"
 require "net/http"
 require "uri"
 
+# Cliente Ruby da {https://brasilapi.com.br BrasilAPI}.
+#
+# @example Bancos participantes do STR
+#   BrasilAPI::Bank.all
+# @see https://brasilapi.com.br/docs
 module BrasilAPI
+  # Cliente HTTP compartilhado pelas famílias de endpoint.
+  #
+  # @see https://brasilapi.com.br/docs
   class Base
+    # Origem das requisições, sem barra no final.
     BASE_URL = "https://brasilapi.com.br/api"
 
     class << self
+      # Executa um GET e devolve o JSON interpretado.
+      #
+      # Chaves +nil+ em +params+ não entram na query.
+      #
+      # @param path [String] caminho a partir de +/api+, começando com +/+
+      # @param params [Hash{Symbol,String=>Object}] query string
+      # @return [Hash, Array, nil] corpo JSON, ou +nil+ quando o corpo vem vazio
+      # @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::Base.get("/banks/v1")
       def get(path, params = {})
         request_data(build_uri(path, params))
       end
 
       protected
 
+      # Formata uma data para +YYYY-MM-DD+.
+      #
+      # @api private
+      # @param value [Date, Time, DateTime, String] data ou texto já formatado
+      # @return [String]
+      def format_date(value)
+        return value.strftime("%Y-%m-%d") if value.respond_to?(:strftime)
+
+        value
+      end
+
+      # Traduz chaves da gem para os nomes de query da BrasilAPI.
+      #
+      # @api private
+      # @param filters [Hash{Symbol=>Object}] filtros recebidos pelo método público
+      # @param mapping [Hash{Symbol=>Symbol}] chave da gem para chave da API
+      # @return [Hash{Symbol=>Object}]
+      def translate(filters, mapping)
+        filters.to_h { |key, value| [mapping.fetch(key), value] }
+      end
+
+      # Interpreta a resposta ou converte a falha em erro da gem.
+      #
+      # @api private
+      # @param uri [URI] URL completa
+      # @return [Hash, Array, nil]
+      # @raise [BrasilAPI::Error]
+      # @raise [BrasilAPI::Timeout]
       def request_data(uri)
         response = perform_request(uri)
         return parsed_body(response) if response.is_a?(Net::HTTPSuccess)
@@ -26,6 +77,12 @@ module BrasilAPI
 
       private
 
+      # Monta a URL, omitindo parâmetros +nil+.
+      #
+      # @api private
+      # @param path [String]
+      # @param params [Hash]
+      # @return [URI]
       def build_uri(path, params)
         uri = URI.parse("#{BASE_URL}#{encode_path(path)}")
         query = params.compact
@@ -33,16 +90,32 @@ module BrasilAPI
         uri
       end
 
+      # Escapa cada segmento do caminho.
+      #
+      # @api private
+      # @param path [String]
+      # @return [String]
       def encode_path(path)
         path.split("/", -1).map { |segment| encode_segment(segment) }.join("/")
       end
 
-      # Encode each segment on its own so "?", "#" and spaces stay inside the path.
-      # encode_uri_component keeps spaces as %20, matching the recorded cassettes.
+      # Codifica um segmento do caminho.
+      #
+      # Cada segmento é escapado sozinho para que "?", "#" e espaços permaneçam no path.
+      # +URI.encode_uri_component+ mantém espaços como +%20+, igual aos cassettes gravados.
+      #
+      # @api private
+      # @param segment [String]
+      # @return [String]
       def encode_segment(segment)
         URI.encode_uri_component(segment)
       end
 
+      # Abre a conexão e envia o GET.
+      #
+      # @api private
+      # @param uri [URI]
+      # @return [Net::HTTPResponse]
       def perform_request(uri)
         Net::HTTP.start(
           uri.hostname,
@@ -55,6 +128,11 @@ module BrasilAPI
         end
       end
 
+      # Interpreta o corpo de uma resposta de sucesso.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse]
+      # @return [Hash, Array, nil]
       def parsed_body(response)
         body = utf8_body(response)
         return if body.nil? || body.empty?
@@ -62,6 +140,12 @@ module BrasilAPI
         JSON.parse(body)
       end
 
+      # Converte uma resposta de erro na exceção correspondente.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse]
+      # @return [void]
+      # @raise [BrasilAPI::Error]
       def raise_api_error(response)
         parsed = parse_error_body(response)
         raise error_class_for(response).new(
@@ -72,6 +156,11 @@ module BrasilAPI
         )
       end
 
+      # Interpreta o corpo de erro, ou +nil+ quando não é JSON.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse]
+      # @return [Hash, Array, nil]
       def parse_error_body(response)
         body = utf8_body(response)
         return if body.nil? || body.empty?
@@ -81,6 +170,11 @@ module BrasilAPI
         nil
       end
 
+      # Lê o corpo forçando UTF-8.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse]
+      # @return [String, nil]
       def utf8_body(response)
         body = response.body
         return if body.nil?
@@ -88,6 +182,12 @@ module BrasilAPI
         body.dup.force_encoding(Encoding::UTF_8)
       end
 
+      # Escolhe a mensagem exposta pela exceção.
+      #
+      # @api private
+      # @param parsed [Hash, Array, nil]
+      # @param response [Net::HTTPResponse]
+      # @return [String]
       def error_message(parsed, response)
         return parsed["message"] if parsed.is_a?(Hash) && parsed["message"]
 
@@ -97,16 +197,32 @@ module BrasilAPI
         "HTTP #{response.code}"
       end
 
+      # Escolhe o corpo exposto pela exceção.
+      #
+      # @api private
+      # @param parsed [Hash, Array, nil]
+      # @param response [Net::HTTPResponse]
+      # @return [Hash, Array, String, nil]
       def error_body(parsed, response)
         return parsed unless parsed.nil?
 
         utf8_body(response)
       end
 
+      # Lê o campo +type+ quando o corpo é um objeto.
+      #
+      # @api private
+      # @param parsed [Hash, Array, nil]
+      # @return [String, nil]
       def error_type(parsed)
         parsed["type"] if parsed.is_a?(Hash)
       end
 
+      # Associa o código HTTP à classe de erro.
+      #
+      # @api private
+      # @param response [Net::HTTPResponse]
+      # @return [Class]
       def error_class_for(response)
         case response.code.to_i
         when 400

data/lib/brasil_api/business_days.rb

@@ -0,0 +1,44 @@
+# 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
+  # Dias úteis entre duas datas.
+  #
+  # @see https://brasilapi.com.br/docs#tag/DIAS-UTEIS
+  class BusinessDays < Base
+    class << self
+      # Conta os dias úteis de um intervalo, inclusive as extremidades.
+      #
+      # +include_national_holidays+ vira +incluirFeriadosNacionais+.
+      # +nil+ omite o parâmetro (a API exclui feriados nacionais).
+      # +false+ é enviado e faz o intervalo tratar feriados como dias úteis.
+      #
+      # @param start_date [Date, Time, DateTime, String] data inicial
+      # @param end_date [Date, Time, DateTime, String] data final
+      # @param include_national_holidays [Boolean, nil] trata feriados como dias úteis quando +false+
+      # @return [Hash] quantidade de dias úteis e a lista de datas
+      # @raise [BrasilAPI::BadRequest] quando o intervalo é 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 Primeira quinzena de janeiro de 2024, sem o feriado do dia 1º
+      #   BrasilAPI::BusinessDays.between("2024-01-01", "2024-01-10")
+      # @see https://brasilapi.com.br/docs#tag/DIAS-UTEIS
+      def between(start_date, end_date, include_national_holidays: nil)
+        get(
+          "/diasuteis/v1",
+          {
+            dataInicial: format_date(start_date),
+            dataFinal: format_date(end_date),
+            incluirFeriadosNacionais: include_national_holidays
+          }
+        )
+      end
+    end
+  end
+end

data/lib/brasil_api/cambio.rb

@@ -0,0 +1,47 @@
+# 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
+  # Cotações de moedas em relação ao real.
+  #
+  # @see https://brasilapi.com.br/docs#tag/CAMBIO
+  class Cambio < Base
+    class << self
+      # Lista as moedas com cotação disponível.
+      #
+      # @return [Array<Hash>] símbolo e nome de cada moeda
+      # @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::Cambio.currencies
+      # @see https://brasilapi.com.br/docs#tag/CAMBIO
+      def currencies
+        get("/cambio/v1/moedas")
+      end
+
+      # Consulta a cotação PTAX de uma moeda em uma data.
+      #
+      # @param currency [String] código ISO, por exemplo +"USD"+
+      # @param date [Date, Time, DateTime, String] data da cotação
+      # @return [Hash] compra, venda e data da cotação
+      # @raise [BrasilAPI::BadRequest] quando a moeda ou a data é inválida
+      # @raise [BrasilAPI::NotFound] quando não há cotação na data
+      # @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 Dólar em 15 de janeiro de 2024
+      #   BrasilAPI::Cambio.quote("USD", "2024-01-15")
+      # @see https://brasilapi.com.br/docs#tag/CAMBIO
+      def quote(currency, date)
+        get("/cambio/v1/cotacao/#{currency}/#{format_date(date)}")
+      end
+    end
+  end
+end

data/lib/brasil_api/cid10.rb

@@ -0,0 +1,46 @@
+# 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
+  # Classificação Internacional de Doenças, 10ª revisão.
+  #
+  # @see https://brasilapi.com.br/docs#tag/CID10
+  class CID10 < Base
+    class << self
+      # Lista os capítulos, grupos e categorias do CID-10.
+      #
+      # @return [Array<Hash>] código e descrição de cada item
+      # @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::CID10.all
+      # @see https://brasilapi.com.br/docs#tag/CID10
+      def all
+        get("/oms/cid10/v1")
+      end
+
+      # Busca uma categoria do CID-10 pelo código.
+      #
+      # @param code [String] código CID, por exemplo +"A00"+
+      # @return [Hash] descrição da categoria
+      # @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 Cólera
+      #   BrasilAPI::CID10.find_by_code("A00")
+      # @see https://brasilapi.com.br/docs#tag/CID10
+      def find_by_code(code)
+        get("/oms/cid10/v1/#{code}")
+      end
+    end
+  end
+end

data/lib/brasil_api/company.rb

@@ -1,8 +1,28 @@
 # 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
+  # Cadastro de pessoa jurídica na Receita Federal.
+  #
+  # @see https://brasilapi.com.br/docs#tag/CNPJ
   class Company < Base
     class << self
+      # Busca uma empresa pelo CNPJ.
+      #
+      # @param documentation [String] CNPJ, com ou sem máscara
+      # @return [Hash] razão social, situação cadastral e endereço
+      # @raise [BrasilAPI::BadRequest] quando o CNPJ é inválido
+      # @raise [BrasilAPI::NotFound] quando o CNPJ 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::Company.find_by_cnpj("19131243000197")
+      # @see https://brasilapi.com.br/docs#tag/CNPJ
       def find_by_cnpj(documentation)
         get("/cnpj/v1/#{documentation}")
       end

data/lib/brasil_api/configuration.rb

@@ -1,25 +1,50 @@
 # 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
+  # Tempo limite das requisições HTTP.
   class Configuration
+    # Tempo limite padrão, em segundos.
     DEFAULT_TIMEOUT = 10
 
+    # Tempo limite de abertura e de leitura, em segundos.
+    #
+    # @return [Numeric]
     attr_accessor :timeout
 
+    # Aplica {DEFAULT_TIMEOUT}.
     def initialize
       @timeout = DEFAULT_TIMEOUT
     end
   end
 
   class << self
+    # Altera a configuração do cliente.
+    #
+    # @yieldparam config [BrasilAPI::Configuration] configuração atual
+    # @return [void]
+    # @example Trinta segundos de timeout
+    #   BrasilAPI.configure { |config| config.timeout = 30 }
     def configure
       yield config
     end
 
+    # Configuração usada pelas requisições.
+    #
+    # @return [BrasilAPI::Configuration]
     def config
       @config ||= Configuration.new
     end
 
+    # Volta o tempo limite para o padrão.
+    #
+    # @return [BrasilAPI::Configuration]
+    # @example
+    #   BrasilAPI.reset_config!
     def reset_config!
       @config = Configuration.new
     end

data/lib/brasil_api/cpf.rb

@@ -0,0 +1,36 @@
+# 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
+  # Validação de CPF.
+  #
+  # A resposta não traz nome nem dados pessoais: apenas se o número é válido
+  # e a região fiscal associada.
+  #
+  # @see https://brasilapi.com.br/docs#tag/CPF
+  class CPF < Base
+    class << self
+      # Verifica se um CPF tem dígitos válidos.
+      #
+      # A BrasilAPI descarta pontuação antes de validar.
+      #
+      # @param cpf [String] CPF, com ou sem máscara
+      # @return [Hash] +isValid+, região fiscal (+rf+) e UFs (+ufs+)
+      # @raise [BrasilAPI::BadRequest] quando o valor não tem 11 dígitos
+      # @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 CPF com máscara
+      #   BrasilAPI::CPF.find("000.000.000-00")
+      # @see https://brasilapi.com.br/docs#tag/CPF
+      def find(cpf)
+        get("/cpf/v1/#{cpf}")
+      end
+    end
+  end
+end

data/lib/brasil_api/cptec.rb

@@ -1,24 +1,93 @@
 # 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
+  # Previsão do tempo e de ondas do CPTEC/INPE.
+  #
+  # @see https://brasilapi.com.br/docs#tag/CPTEC
   class CPTEC < Base
     class << self
+      # Lista as cidades atendidas pelo CPTEC.
+      #
+      # @return [Array<Hash>] nome e código de cada cidade
+      # @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::CPTEC.all
+      # @see https://brasilapi.com.br/docs#tag/CPTEC
       def all
         get("/cptec/v1/cidade")
       end
 
+      # Procura cidades pelo nome.
+      #
+      # @param city_name [String] parte do nome da cidade
+      # @return [Array<Hash>] cidades encontradas e seus códigos
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando nenhuma cidade corresponde
+      # @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::CPTEC.search_location("Teresina")
+      # @see https://brasilapi.com.br/docs#tag/CPTEC
       def search_location(city_name)
         get("/cptec/v1/cidade/#{city_name}")
       end
 
+      # Previsão do tempo nas capitais.
+      #
+      # @return [Array<Hash>] condição atual de cada capital
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a BrasilAPI responde 404
+      # @raise [BrasilAPI::ServerError] quando a fonte do CPTEC está indisponível
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example
+      #   BrasilAPI::CPTEC.capital_weather
+      # @see https://brasilapi.com.br/docs#tag/CPTEC
       def capital_weather
         get("/cptec/v1/clima/capital")
       end
 
+      # Condição meteorológica de um aeroporto.
+      #
+      # @param code [String] código ICAO, por exemplo +"SBGR"+
+      # @return [Hash] condição do aeroporto
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando o código ICAO não existe
+      # @raise [BrasilAPI::ServerError] quando a fonte do CPTEC está indisponível
+      # @raise [BrasilAPI::Timeout] quando a requisição estoura o tempo limite
+      # @raise [BrasilAPI::Error] em outras respostas de erro
+      # @example Aeroporto de Guarulhos
+      #   BrasilAPI::CPTEC.airport_weather("SBGR")
+      # @see https://brasilapi.com.br/docs#tag/CPTEC
       def airport_weather(code)
         get("/cptec/v1/clima/aeroporto/#{code}")
       end
 
+      # Previsão do tempo de uma cidade do CPTEC.
+      #
+      # Sem +days+, a previsão é de um dia. A BrasilAPI aceita até 6 dias.
+      #
+      # @param city_code [String, Integer] código da cidade no CPTEC
+      # @param days [Integer, nil] quantidade de dias, de 1 a 6
+      # @return [Hash] previsão da cidade
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a cidade 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 Previsão de três dias
+      #   BrasilAPI::CPTEC.city_weather(244, 3)
+      # @see https://brasilapi.com.br/docs#tag/CPTEC
       def city_weather(city_code, days = nil)
         if days
           get("/cptec/v1/clima/previsao/#{city_code}/#{days}")
@@ -27,6 +96,21 @@ module BrasilAPI
         end
       end
 
+      # Previsão de ondas no litoral de uma cidade.
+      #
+      # Sem +days+, a previsão é de um dia. A BrasilAPI aceita até 6 dias.
+      #
+      # @param city_code [String, Integer] código da cidade no CPTEC
+      # @param days [Integer, nil] quantidade de dias, de 1 a 6
+      # @return [Hash] previsão de ondas
+      # @raise [BrasilAPI::BadRequest] quando a BrasilAPI responde 400
+      # @raise [BrasilAPI::NotFound] quando a cidade não tem previsão de ondas
+      # @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::CPTEC.ocean_forecast(241, 2)
+      # @see https://brasilapi.com.br/docs#tag/CPTEC
       def ocean_forecast(city_code, days = nil)
         if days
           get("/cptec/v1/ondas/#{city_code}/#{days}")