boleto_bancario 0.0.1.beta → 0.0.2

data/TODO.markdown

@@ -1,5 +1,19 @@
+# Road to 1.0.0
+
+## Código de barras
+
+* Colocar a gem barby para gerar a imagem do código de barras.
+
+## Layout
+
+* Verificar a questão dos formatos (html, pdf, png).
+
+# Outros
+
+* Logo dos bancos.
+* Formatacao documento (CPF/CNPJ).
 * Colocar exemplos melhores na documentação de cada banco.
 * Nos exemplos de cada banco colocar os métodos que são chamados pelo objeto.
 * Verificar as validações e suas mensagens de erro.
 * Internacionalização / Locales.
-* Verificar a questão dos formatos (html, pdf).
+* Criar páginas explicando cada banco.

data/boleto_bancario.gemspec

@@ -15,9 +15,13 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.version       = BoletoBancario::VERSION
 
-  gem.add_dependency "activesupport", "~> 3.2"
-  gem.add_dependency "activemodel", "~> 3.2"
-  gem.add_development_dependency "rspec", "~> 2.11"
+  gem.add_dependency "rake"
+  gem.add_dependency "activesupport", "~> 4.1"
+  gem.add_dependency "activemodel", "~> 4.1"
+  gem.add_dependency "barby"
+
+  gem.add_development_dependency "rspec", "~> 2.13"
+  gem.add_development_dependency "yard"
   gem.add_development_dependency "valid_attribute", "~> 1.3"
   gem.add_development_dependency "pry", "~> 0.9"
   gem.add_development_dependency "simplecov", "~> 0.2"

data/lib/boleto_bancario.rb

@@ -57,26 +57,38 @@ module BoletoBancario
   # você precise mudar os nomes dos campos nos boletos)
   #
   module Core
-    autoload :Boleto,      'boleto_bancario/core/boleto'
-    autoload :BancoBrasil, 'boleto_bancario/core/banco_brasil'
-    autoload :Bradesco,    'boleto_bancario/core/bradesco'
-    autoload :Itau,        'boleto_bancario/core/itau'
-    autoload :Santander,   'boleto_bancario/core/santander'
+    extend ActiveSupport::Autoload
+
+    autoload :Boleto
+    autoload :BancoBrasil
+    autoload :Banrisul
+    autoload :Bradesco
+    autoload :Caixa
+    autoload :Hsbc
+    autoload :Itau
+    autoload :Real
+    autoload :Santander
+    autoload :Sicoob
+    autoload :Sicredi
   end
 
   # Módulo que possui classes que realizam os cálculos dos campos que serão mostrados nos boletos.
   #
   module Calculos
-    autoload :FatorVencimento,             'boleto_bancario/calculos/fator_vencimento'
-    autoload :FatoresDeMultiplicacao,      'boleto_bancario/calculos/fatores_de_multiplicacao'
-    autoload :LinhaDigitavel,              'boleto_bancario/calculos/linha_digitavel'
-    autoload :Modulo10,                    'boleto_bancario/calculos/modulo10'
-    autoload :Modulo11,                    'boleto_bancario/calculos/modulo11'
-    autoload :Modulo11FatorDe2a9,          'boleto_bancario/calculos/modulo11_fator_de2a9'
-    autoload :Modulo11FatorDe2a9RestoZero, 'boleto_bancario/calculos/modulo11_fator_de2a9_resto_zero'
-    autoload :Modulo11FatorDe2a7,          'boleto_bancario/calculos/modulo11_fator_de2a7'
-    autoload :Modulo11FatorDe9a2RestoX,    'boleto_bancario/calculos/modulo11_fator_de9a2_resto_x'
-    autoload :Digitos,                     'boleto_bancario/calculos/digitos'
+    extend ActiveSupport::Autoload
+
+    autoload :FatorVencimento
+    autoload :FatoresDeMultiplicacao
+    autoload :LinhaDigitavel
+    autoload :Modulo10
+    autoload :Modulo11
+    autoload :Modulo11FatorDe2a9
+    autoload :Modulo11FatorDe2a9RestoZero
+    autoload :Modulo11FatorDe2a7
+    autoload :Modulo11FatorDe9a2
+    autoload :Modulo11FatorDe9a2RestoX
+    autoload :ModuloNumeroDeControle
+    autoload :Digitos
   end
 
   include Core

data/lib/boleto_bancario/calculos/modulo11_fator_de9a2.rb

@@ -0,0 +1,65 @@
+module BoletoBancario
+  module Calculos
+    # === Módulo 11 Fator de 9 a 2
+    #
+    # === Passos
+    #
+    # 1) Tomando-se os algarismos multiplique-os, iniciando-se da direita para a esquerda,
+    # pela seqüência numérica de 9 a 2 (9, 8, 7, 6, 5, 4, 3, 2 ... e assim por diante).
+    #
+    # 2) Some o resultado de cada produto efetuado e determine o total como (N).
+    #
+    # 3) Divida o total (N) por 11 e determine o resto obtido da divisão como Mod 11(N).
+    #
+    # ==== Exemplo Normal
+    #
+    # Considerando o seguinte número: '89234560'.
+    #
+    # 1) Multiplicando a seqüência de multiplicadores:
+    #
+    #      8    9    2    3    4    5    6    0
+    #      *    *    *    *    *    *    *    *
+    #      2    3    4    5    6    7    8    9
+    #
+    # 2) Soma-se o resultado dos produtos obtidos no item “1” acima:
+    #
+    #      16 + 27 + 8 + 15 + 24 + 35 + 48 + 0
+    #      # => 173
+    #
+    # 3) Determina-se o resto da Divisão:
+    #
+    #      173 % 11
+    #      # => 8 =============> Resultado final retornado.
+    #
+    # @param [String]: Corresponde ao número a ser calculado o Módulo 11 no fator de 9 a 2.
+    # @return [String] Retorna o resultado do cálculo descrito acima.
+    #
+    # @example
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe9a2.new('12345')
+    #    # => '5'
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe9a2.new('246')
+    #    # => '1'
+    #
+    class Modulo11FatorDe9a2 < Modulo11
+      # Sequência numérica de 9 a 2 que será feito a multiplicação de cada dígito
+      # do número passado no #initialize.
+      #
+      # @return [Array] Sequência numérica
+      #
+      def fatores
+        [9, 8, 7, 6, 5, 4, 3, 2]
+      end
+
+      # Calcula o número pelos fatores de multiplicação de 9 a 2.
+      # Depois calcula o resto da divisão por 11.
+      #
+      # @return [Fixnum]
+      #
+      def calculate
+        mod_division
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/modulo11_fator_de9a2_resto_x.rb

@@ -1,37 +1,9 @@
 module BoletoBancario
   module Calculos
-    # === Módulo 11 Fator de 9 a 2 - Resto 10, sendo X
+    #  === Módulo 11 Fator de 9 a 2 - Resto 10, sendo X
+    # <b>Essa classe difere da outra com Modulo11FatorDe9a2, no momento de verificar o resto da divisão por 11.</b>
     #
-    # === Passos
-    #
-    # 1) Tomando-se os algarismos multiplique-os, iniciando-se da direita para a esquerda,
-    # pela seqüência numérica de 9 a 2 (9, 8, 7, 6, 5, 4, 3, 2 ... e assim por diante).
-    #
-    # 2) Some o resultado de cada produto efetuado e determine o total como (N).
-    #
-    # 3) Divida o total (N) por 11 e determine o resto obtido da divisão como Mod 11(N).
-    #
-    # <b>OBS.:</b> Se o resultado desta expressão for igual a 10, considere DAC = X.
-    #
-    # ==== Exemplo Normal
-    #
-    # Considerando o seguinte número: '89234560'.
-    #
-    # 1) Multiplicando a seqüência de multiplicadores:
-    #
-    #      8    9    2    3    4    5    6    0
-    #      *    *    *    *    *    *    *    *
-    #      2    3    4    5    6    7    8    9
-    #
-    # 2) Soma-se o resultado dos produtos obtidos no item “1” acima:
-    #
-    #      16 + 27 + 8 + 15 + 24 + 35 + 48 + 0
-    #      # => 173
-    #
-    # 3) Determina-se o resto da Divisão:
-    #
-    #      173 % 11
-    #      # => 8 =============> Resultado final retornado.
+    # <b>Para mais detalhes veja a classe Modulo11FatorDe9a2.</b>
     #
     # ==== Exemplo 10 como resto da divisão
     #
@@ -58,30 +30,12 @@ module BoletoBancario
     #     resultado == 10
     #     # => 'X' =============> Resultado final retornado.
     #
-    # @param [String]: Corresponde ao número a ser calculado o Módulo 11 no fator de 9 a 2.
-    # @return [String] Retorna o resultado do cálculo descrito acima.
-    #
     # @example
     #
-    #    BoletoBancario::Calculos::Modulo11FatorDe9a2RestoX.new('12345')
-    #    # => '5'
-    #
-    #    BoletoBancario::Calculos::Modulo11FatorDe9a2RestoX.new('246')
-    #    # => '1'
-    #
-    #    BoletoBancario::Calculos::Modulo11FatorDe2a9.new('184122')
+    #    BoletoBancario::Calculos::Modulo11FatorDe9a2RestoX.new('184122')
     #    # => 'X'
     #
-    class Modulo11FatorDe9a2RestoX < Modulo11
-      # Sequência numérica de 9 a 2 que será feito a multiplicação de cada dígito
-      # do número passado no #initialize.
-      #
-      # @return [Array] Sequência numérica
-      #
-      def fatores
-        [9, 8, 7, 6, 5, 4, 3, 2]
-      end
-
+    class Modulo11FatorDe9a2RestoX < Modulo11FatorDe9a2
       # Calcula o número pelos fatores de multiplicação de 9 a 2.
       # Depois calcula o resto da divisão por 11.
       # Se o resultado desse cálculo for igual a 10, então o DAC = X.

data/lib/boleto_bancario/calculos/modulo_numero_de_controle.rb

@@ -0,0 +1,117 @@
+module BoletoBancario
+  module Calculos
+    # === Cálculo do Módulo do Número de Controle (2 dígitos)
+    #
+    # Tipo de cálculo usado pelo Banco Banrisul.
+    #
+    # === Cálculo do Primeiro Dígito
+    #
+    # 1) Multiplica-se cada algarismo do campo pela seqüência de multiplicadores <b>2, 1, 2, 1, 2, 1 ...</b>, posicionados da direita para a esquerda.
+    #
+    # 2) Some individualmente, os algarismos dos resultados dos produtos, obtendo-se o total (N).
+    #
+    # 3) Divida o total encontrado (N) por 10, e determine o resto da divisão como MOD 10 (N).
+    #
+    # 4) Encontre o DAC através da seguinte expressão:
+    #
+    #    DAC = 10 - Mod 10 (n)
+    #
+    # === Cálculo do segundo dígito
+    #
+    # # 1) Tomando-se os algarismos multiplique-os, iniciando-se da direita para a esquerda,
+    # pela seqüência numérica de 2 a 7 (2, 3, 4, 5, 6, 7 ... e assim por diante).
+    #
+    # 2) Some o resultado de cada produto efetuado e determine o total como (N).
+    #
+    # 3) Divida o total (N) por 11 e determine o resto obtido da divisão como Mod 11(N).
+    #
+    # 4) Calcule o dígito verificador (DAC) através da expressão:
+    #
+    #     DIGIT = 11 - Mod 11 (n)
+    #
+    # <b>Observações:</b>
+    #
+    # Caso o 'resto' obtido no cálculo do módulo '11' seja igual a '1', considera-se o DV inválido.
+    # Soma-se, então, "1" ao DV obtido do módulo "10" e refaz-se o cálculo do módulo “11”.
+    # Se o dígito obtido pelo módulo “10” era igual a "9", considera-se então (9+1=10) DV inválido.
+    # Neste caso, o DV do módulo "10" automaticamente será igual a "0" e procede-se assim
+    # novo cálculo pelo módulo "11".
+    #
+    # === Exemplo com Primeiro Dígito Inválido
+    #
+    # Dado o número '00009194':
+    #
+    # O somatório do primeiro cálculo é igual a '28' e o Resto é igual a '8'.
+    # Portanto, o primeiro DV é igual a 10 - 8 ou DV = 2.
+    #
+    # O somatório do segundo cálculo é igual a '111' e o Resto é, neste caso, igual a '1'.
+    # Portanto, o segundo DV é  inválido (11 - 1 = 10).
+    #
+    # Neste caso, soma-se '1' ao DV obtido do primeiro cálculo:
+    #
+    #      2 + 1
+    #      # ======> 3 # Primeiro dígito do número de controle
+    #
+    # Agora, efetua-se novo cálculo do módulo 11, agora com o novo número, ou seja, 000091943:
+    #
+    # A somatório do segundo cálculo é igual a '113' e o Resto igual a '3'.
+    # Portanto, o segundo DV é igual a:
+    #
+    #     11 - 3
+    #     # ====> 8 # Segundo dígito do número de controle
+    #
+    # Neste exemplo, o número de controle será '38'.
+    #
+    class ModuloNumeroDeControle < String
+      attr_reader :number, :first_digit, :second_digit
+
+      def initialize(number)
+        @number       = number
+        @first_digit  = calculate_first_digit
+        @second_digit = calculate_second_digit
+
+        super(calculate)
+      end
+
+      # Retorna 2 dígitos verificando o segundo dígito se é válido ou não.
+      #
+      # @return [String]
+      #
+      def calculate
+        if second_digit_result.equal?(10)
+          @first_digit  = first_digit.to_i + 1
+          @first_digit  = 0 if @first_digit.equal?(10)
+          @second_digit = calculate_second_digit
+        end
+
+        "#{first_digit}#{second_digit}"
+      end
+
+      # Retorna a subtração de 11 pelo resto da divisão por 11 do segundo dígito.
+      #
+      # @return [Integer]
+      #
+      def second_digit_result
+        11 - @second_digit.mod_division
+      end
+
+      # Calcula o primeiro dígito pelo módulo 10.
+      # Para mais detalhes veja a classe Modulo10.
+      #
+      # @return [String]
+      #
+      def calculate_first_digit
+        Modulo10.new(number)
+      end
+
+      # Calcula o segundo dígito pelo módulo 11 usando os fatores de 2 a 7.
+      # Para mais detalhes veja a classe Modulo11FatorDe2a7.
+      #
+      # @return [String]
+      #
+      def calculate_second_digit
+        Modulo11FatorDe2a7.new("#{number}#{first_digit}")
+      end
+    end
+  end
+end

data/lib/boleto_bancario/core/banco_brasil.rb

@@ -116,16 +116,25 @@ module BoletoBancario
         17
       end
 
-      validates :codigo_cedente, :agencia, :digito_agencia, :conta_corrente, :digito_conta_corrente, presence: true
+      # <b>Carteiras suportadas.</b>
+      #
+      # <b>Método criado para validar se a carteira informada é suportada.</b>
+      #
+      # @return [Array]
+      #
+      def self.carteiras_suportadas
+        %w[12 16 17 18]
+      end
 
-      validates :digito_agencia,        length: { maximum: 1  }
-      validates :digito_conta_corrente, length: { maximum: 1  }
+      validates :codigo_cedente, :agencia, :digito_agencia, :conta_corrente, :digito_conta_corrente, presence: true
 
-      # Validações de Agencia e Conta corrente.
+      # Validações de Agencia, Conta corrente e Carteira.
       #
       validates :agencia,          length: { maximum: tamanho_maximo_agencia        }, if: :deve_validar_agencia?
       validates :conta_corrente,   length: { maximum: tamanho_maximo_conta_corrente }, if: :deve_validar_conta_corrente?
 
+      validates :carteira, inclusion: { in: ->(object) { object.class.carteiras_suportadas } }, if: :deve_validar_carteira?
+
       # Validações do número do documento.
       #
       # === Número do Documento e Código do Cedente.
@@ -182,7 +191,7 @@ module BoletoBancario
       # @return [String]
       #
       def numero_documento
-        if @numero_documento.present?
+        if @numero_documento.present? and numero_documento_esperado[tamanho_codigo_cedente].present?
           @numero_documento.to_s.rjust(numero_documento_esperado[tamanho_codigo_cedente], '0')
         else
           @numero_documento
@@ -214,6 +223,22 @@ module BoletoBancario
         '9'
       end
 
+      # Dígito do código da agência. Precisa mostrar esse dígito no boleto.
+      #
+      # @return [String] Dígito da agência calculado apartir do Modulo11FatorDe9a2RestoX.
+      #
+      def digito_agencia
+        Modulo11FatorDe9a2RestoX.new(agencia)
+      end
+
+      # Dígito da conta corrente. Precisa mostrar esse dígito no boleto.
+      #
+      # @return [String] Dígito da conta corrente calculado apartir do Modulo11FatorDe9a2RestoX.
+      #
+      def digito_conta_corrente
+        Modulo11FatorDe9a2RestoX.new(conta_corrente)
+      end
+
       # Campo Agencia / Código do Cedente
       # Retorna formatado a agência, digito da agência, número da conta corrente e dígito da conta.
       #

data/lib/boleto_bancario/core/banrisul.rb

@@ -0,0 +1,182 @@
+module BoletoBancario
+  module Core
+    # Implementação de emissão de boleto bancário do Banrisul.
+    #
+    # === Documentação Implementada
+    #
+    # A documentação na qual essa implementação foi baseada está localizada na pasta
+    # 'documentacoes_dos_boletos/banrisul' dentro dessa biblioteca.
+    #
+    # === Contrato das classes de emissão de boletos
+    #
+    # Para ver o "<b>contrato</b>" da Emissão de Boletos (geração de código de barras, linha digitável, etc) veja
+    # a classe BoletoBancario::Core::Boleto.
+    #
+    # === Carteiras Suportadas
+    #
+    # 00 - CCB sem registro
+    # 08 - CCB com registro
+    #
+    # === Usage
+    #
+    #    class BoletoBanrisul < BoletoBancario::Banrisul
+    #    end
+    #
+    #    boleto = BoletoBanrisul.new do |boleto|
+    #      boleto.numero_documento      = 22832563
+    #      boleto.agencia               = 100
+    #      boleto.data_vencimento       = Date.parse('2004-07-04')
+    #      boleto.codigo_cedente        = "0000001"
+    #      boleto.valor_documento       = 5.0
+    #    end
+    #
+    class Banrisul < Boleto
+      # Tamanho máximo de uma agência no Banrisul (sem número de controle).
+      # <b>Método criado justamente para ficar documentado o tamanho máximo aceito até a data corrente.</b>
+      #
+      # @return [Fixnum] 3
+      #
+      def self.maximo_agencia
+        3
+      end
+
+      # Tamanho máximo do código cedente.
+      # <b>Método criado justamente para ficar documentado o tamanho máximo aceito até a data corrente.</b>
+      #
+      # @return [Fixnum] 4
+      #
+      def self.maximo_codigo_cedente
+        7
+      end
+
+      # Tamanho máximo do número do documento.
+      # <b>Método criado justamente para ficar documentado o tamanho máximo aceito até a data corrente.</b>
+      #
+      # @return [Fixnum] 8
+      #
+      def self.maximo_numero_documento
+        8
+      end
+
+      # <b>Carteiras suportadas.</b>
+      #
+      # <b>Método criado para validar se a carteira informada é suportada.</b>
+      #
+      # @return [Array]
+      #
+      def self.carteiras_suportadas
+        %w[00 08]
+      end
+
+      validates :agencia, :digito_agencia, :codigo_cedente, :digito_codigo_cedente, presence: true
+
+      validates :agencia,               length: { maximum: maximo_agencia          }, if: :deve_validar_agencia?
+      validates :codigo_cedente,        length: { maximum: maximo_codigo_cedente   }, if: :deve_validar_codigo_cedente?
+      validates :numero_documento,      length: { maximum: maximo_numero_documento }, if: :deve_validar_numero_documento?
+
+      validates :carteira, inclusion: { in: ->(object) { object.class.carteiras_suportadas } }, if: :deve_validar_carteira?
+
+      # @return [String] 3 caracteres
+      #
+      def agencia
+        @agencia.to_s.rjust(3, '0') if @agencia.present?
+      end
+
+      # @return [String] 8 caracteres
+      #
+      def numero_documento
+        @numero_documento.to_s.rjust(8, '0') if @numero_documento.present?
+      end
+
+      # @return [String] 7 caracteres
+      #
+      def codigo_cedente
+        @codigo_cedente.to_s.rjust(7, '0') if @codigo_cedente.present?
+      end
+
+      # @return [String] 2 caracteres
+      #
+      def carteira
+        @carteira.to_s.rjust(2, '0') if @carteira.present?
+      end
+
+      # @return [String] Código do Banco descrito na documentação.
+      #
+      def codigo_banco
+        '041'
+      end
+
+      # Dígito do código do banco. Precisa mostrar esse dígito no boleto.
+      #
+      # @return [String] Dígito do código do banco descrito na documentação.
+      #
+      def digito_codigo_banco
+        '8'
+      end
+
+      # Dígito do código da agência. Precisa mostrar esse dígito no boleto.
+      #
+      # @return [String] Dígito da agência calculado apartir do ModuloNumeroDeControle.
+      #
+      def digito_agencia
+        ModuloNumeroDeControle.new(agencia)
+      end
+
+      # Dígito do código do cedente. Precisa mostrar esse dígito no boleto.
+      #
+      # @return [String] Dígito do código do cedente calculado apartir do ModuloNumeroDeControle.
+      #
+      def digito_codigo_cedente
+        ModuloNumeroDeControle.new(codigo_cedente)
+      end
+
+      # Retorna a Agencia, digito da agencia, código do cedente e o dígito do código do cedente.
+      #
+      # @return [String]
+      #
+      def agencia_codigo_cedente
+        "#{agencia}.#{digito_agencia} #{codigo_cedente}.#{digito_codigo_cedente}"
+      end
+
+      # Retorna o número do documento com seu número de controle.
+      #
+      # Para mais detalhes do cálculo, veja a classe ModuloNumeroDeControle.
+      #
+      # @return [String]
+      #
+      def nosso_numero
+        "#{numero_documento}.#{ModuloNumeroDeControle.new(numero_documento)}"
+      end
+
+      #  === Código de barras do banco
+      #
+      #     ________________________________________________________________________________________________
+      #    | Posição | Tamanho | Descrição                                                                 |
+      #    |---------|---------|---------------------------------------------------------------------------|
+      #    | 20      |  01     | Tipo da cobrança do produto (mais detalhes veja #tipo_da_cobranca)        |
+      #    | 21      |  01     | Constante '1'                                                             |
+      #    | 22-24   |  03     | Agência (sem número de controle)                                          |
+      #    | 25-31   |  07     | Código do Cedente (sem número de controle)                                |
+      #    | 32-39   |  08     | Nosso número (número do documento sem número de controle)                 |
+      #    | 40-42   |  03     | Constante '041'                                                           |
+      #    | 43-44   |  02     | Duplo Dígito referente às posições 20 a 42 (módulo do numero de controle) |
+      #    ------------------------------------------------------------------------------------------------|
+      #
+      def codigo_de_barras_do_banco
+        codigo = "#{tipo_da_cobranca}1#{agencia}#{codigo_cedente}#{numero_documento}041"
+        "#{codigo}#{ModuloNumeroDeControle.new(codigo)}"
+      end
+
+      # Tipo da cobranca do boleto
+      #
+      # "1" Cobrança Normal, Fichário emitido pelo BANRISUL.
+      # "2" Cobrança Direta, Fichário emitido pelo CLIENTE.
+      #
+      # @return [String]
+      #
+      def tipo_da_cobranca
+        "2"
+      end
+    end
+  end
+end