boleto_bancario 0.0.1.beta

data/lib/boleto_bancario/calculos/linha_digitavel.rb

@@ -0,0 +1,158 @@
+# encoding: utf-8
+require 'active_support/core_ext/object'
+
+module BoletoBancario
+  module Calculos
+    # Representação numérica do código de barras, mais conhecida como linha digitável! :p
+    #
+    # A representação numérica do código de barras é composta, por cinco campos.
+    # Sendo os três primeiros campos, amarrados por DAC's (dígitos verificadores),
+    # todos calculados pelo módulo 10.
+    #
+    # <b>OBS.:</b> Para mais detalhes deste cálculo, veja a descrição em Modulo10.
+    #
+    # === Linha Digitável
+    #
+    # A linha digitável contêm exatamente 47 posições nessa sequência:
+    #
+    #       _____________________________________________________________________________________________________________
+    #      |Campo | Posição  | Tamanho | Descrição                                                                      |
+    #      |------|----------|---------|--------------------------------------------------------------------------------|
+    #      | 1º   | 01-03    |  03     | Código do banco (posições 1 a 3 do código de barras)                           |
+    #      |      | 04       |  01     | Código da moeda (posição 4 do código de barras)                                |
+    #      |      | 05-09    |  5      | Cinco primeiras posições do campo livre (posições 20 a 24 do código de barras) |
+    #      |      | 10       |  1      | Dígito verificador do primeiro campo (Módulo10)                                |
+    #      |------------------------------------------------------------------------------------------------------------|
+    #      | 2º   | 11-20    |  10     | 6º a 15º posições do campo livre (posições 25 a 34 do código de barras)        |
+    #      |      | 21       |  01     | Dígito verificador do segundo campo  (Módulo10)                                |
+    #      |------------------------------------------------------------------------------------------------------------|
+    #      | 3º   | 22-31    |  10     | 16º a 25º posições do campo livre (posições 35 a 44 do código de barras)       |
+    #      |      | 32       |  01     | Dígito verificador do terceiro campo  (Módulo10)                               |
+    #      |------------------------------------------------------------------------------------------------------------|
+    #      | 4º   | 33       |  01     | Dígito verificador do código de barras (posição 5 do código de barras)         |
+    #      |------------------------------------------------------------------------------------------------------------|
+    #      | 5ª   | 34-37    |  04     | Fator de vencimento (posições 6 a 9 do código de barras)                       |
+    #      |      | 38-47    |  10     | Valor nominal do documento (posições 10 a 19 do código de barras)              |
+    #      -------------------------------------------------------------------------------------------------------------|
+    #
+    # @return [String] Contêm a representação numérica do código de barras formatado com pontos e espaços.
+    #
+    # @example
+    #
+    #     LinhaDigitavel.new('34196166700000123451091234567880057123457000')
+    #     # => '34191.09123 34567.880058 71234.570001 6 16670000012345'
+    #
+    #     LinhaDigitavel.new('99991101200000350007772130530150081897500000')
+    #     # => '99997.77213 30530.150082 18975.000003 1 10120000035000'
+    #
+    #     LinhaDigitavel.new('39998100100000311551111122222500546666666001')
+    #     # => '39991.11119 22222.500542 66666.660015 8 10010000031155'
+    #
+    class LinhaDigitavel < String
+      attr_reader :codigo_de_barras
+      # @param [String] codigo_de_barras Código de Barras de 44 posições
+      # @return [String]
+      #
+      # Representação numérica do código de barras
+      #
+      # @example
+      #
+      #     LinhaDigitavel.new('34196166700000123451091234567880057123457000')
+      #     # => '34191.09123 34567.880058 71234.570001 6 16670000012345'
+      #
+      #     LinhaDigitavel.new('99991101200000350007772130530150081897500000')
+      #     # => '99997.77213 30530.150082 18975.000003 1 10120000035000'
+      #
+      #     LinhaDigitavel.new('39998100100000311551111122222500546666666001')
+      #     # => '39991.11119 22222.500542 66666.660015 8 10010000031155'
+      #
+      #     # Retorna uma String vazia caso o código de barras esteja vazio.
+      #     LinhaDigitavel.new('')
+      #     # => ''
+      #
+      #     # Retorna uma String vazia caso o código de barras esteja vazio.
+      #     LinhaDigitavel.new(nil)
+      #     # => ''
+      #
+      #     # Retorna uma String vazia caso o código de barras seja menor que 44 posições.
+      #     LinhaDigitavel.new('123456789')
+      #     # => ''
+      #
+      #     # Retorna uma String vazia caso o código de barras seja maior que 44 posições.
+      #     LinhaDigitavel.new('12345678901234567890123456789012345678901234567890')
+      #     # => ''
+      #
+      def initialize(codigo_de_barras)
+        @codigo_de_barras  = codigo_de_barras.to_s
+
+        if @codigo_de_barras.present? and @codigo_de_barras.size == 44
+          super(representacao_numerica_do_codigo_de_barras)
+        else
+          super('')
+        end
+      end
+
+      # @return [String] Retorna todos os campos da linha digitável pegando as posições exatas do código de barras.
+      #
+      def representacao_numerica_do_codigo_de_barras
+        "#{primeiro_campo} #{segundo_campo} #{terceiro_campo} #{quarto_campo} #{quinto_campo}"
+      end
+
+      # @api private
+      #
+      # Retorna o primeiro campo da linha digitável com seu respectivo dígito verificador.
+      #
+      # @return [String]
+      #
+      def primeiro_campo
+        primeiro_campo_sem_digito = "#{codigo_de_barras[0..3]}#{codigo_de_barras[19..23]}"
+        digito_verificador        = Modulo10.new(primeiro_campo_sem_digito)
+        "#{primeiro_campo_sem_digito}#{digito_verificador}".gsub(/^(.{5})(.{5})/, '\1.\2')
+      end
+
+      # @api private
+      #
+      # Retorna o segundo campo da linha digitável com seu respectivo dígito verificador.
+      #
+      # @return [String]
+      #
+      def segundo_campo
+        segundo_campo_sem_digito = "#{codigo_de_barras[24..33]}"
+        digito_verificador       = Modulo10.new(segundo_campo_sem_digito)
+        "#{segundo_campo_sem_digito}#{digito_verificador}".gsub(/(.{5})(.{6})/, '\1.\2')
+      end
+
+      # @api private
+      #
+      # Retorna o terceiro campo da linha digitável com seu respectivo dígito verificador.
+      #
+      # @return [String]
+      #
+      def terceiro_campo
+        terceiro_campo_sem_digito = "#{codigo_de_barras[34..46]}"
+        digito_verificador        = Modulo10.new(terceiro_campo_sem_digito)
+        "#{terceiro_campo_sem_digito}#{digito_verificador}".gsub(/(.{5})(.{6})/, '\1.\2')
+      end
+
+      # @api private
+      #
+      # Retorna o dígito verificador do código de barras (posição 5 do código de barras)
+      #
+      # @return [String]
+      #
+      def quarto_campo
+        "#{codigo_de_barras[4]}"
+      end
+
+      # @api private
+      #
+      # Retorna o quinto e último campo da linha digitável.
+      #
+      # @return [String]
+      #
+      def quinto_campo
+        "#{codigo_de_barras[5..8]}#{codigo_de_barras[9..18]}"
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/modulo10.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+module BoletoBancario
+  module Calculos
+    # === Cálculo do Modulo 10
+    #
+    # === Passos
+    #
+    # 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)
+    #
+    # <b>OBS.:</b> Se o resultado do passo 4 for 10, considere o DAC = 0.
+    #
+    # ==== Exemplos
+    #
+    # Considerando-se a seguinte representação numérica <b>'12345'</b>.
+    #
+    # 1) Multiplicando a seqüência de multiplicadores:
+    #
+    #      1     2     3     4     5
+    #      *     *     *     *     *  ===> Multiplicação.
+    #      2     1     2     1     2
+    #
+    # 2) Some, individualmente:
+    #
+    #      2  +  2  +  6  +  4   + 1 + 0 (Veja a observação abaixo explicando o '1' + '0').
+    #      # => 15
+    #
+    # <b>OBS.:</b>: Resultado da soma que possua 2 digitos deve somar cada dígito.
+    # Exemplos: 10 -> 1 + 0. 11 -> 1 + 1, 28 -> 2 + 8, etc.
+    #
+    # 3) Divida o total encontrado por 10, a fim de determinar o resto da divisão:
+    #
+    #      15 % 10
+    #      # => 5
+    #
+    # 4) Calculando o DAC:
+    #
+    #      10 - 5
+    #      # => 5 =======> Resultado final retornado.
+    #
+    class Modulo10 < String
+      # @param [String ou Integer] number (Corresponde ao número a ser calculado pelo Módulo 10)
+      # @return [String]
+      # @example
+      #
+      #    BoletoBancario::Calculos::Modulo10.new(1233)
+      #    # => "6"
+      #
+      #    BoletoBancario::Calculos::Modulo10.new(4411)
+      #    # => "5"
+      #
+      #    BoletoBancario::Calculos::Modulo10.new('9000')
+      #    # => "1"
+      #
+      #    BoletoBancario::Calculos::Modulo10.new('6789')
+      #    # => "2"
+      #
+      def initialize(number)
+        @number  = number
+        super(calculate.to_s)
+      end
+
+      # @return [String] Resultado final do cálculo do módulo 10.
+      #
+      def calculate
+        sum_total = FatoresDeMultiplicacao.new(@number, fatores: [2, 1]).collect do |result_of_each_sum|
+          Digitos.new(result_of_each_sum).sum
+        end.sum
+        total = 10 - (sum_total % 10)
+
+        return 0 if total.equal?(10)
+        total
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/modulo11.rb

@@ -0,0 +1,54 @@
+module BoletoBancario
+  module Calculos
+    # Classe que possue a convenção de calculo do modulo 11.
+    # O que muda para cada classe é a forma de verificar o total do cálculo.
+    #
+    # @abstract Precisa implementar { #fatores, #calculate } nas subclasses.
+    #
+    class Modulo11 < String
+      # Número que será feito o cálculo do módulo 11.
+      #
+      attr_reader :number
+
+      # @param [String ou Integer] number (Corresponde ao número a ser calculado pelo Módulo 11)
+      # @return [String]
+      #
+      def initialize(number)
+        @number  = number
+
+        super(calculate.to_s)
+      end
+
+      # @return [Array] Fatores que serão multiplicados por cada digito do
+      # número passado como argumento no initialize.
+      # @raise [NotImplementedError] Precisa implementar na subclasse
+      #
+      def fatores
+        raise NotImplementedError, "Not implemented #fatores in subclass."
+      end
+
+      # @return [Fixnum]
+      # @raise [NotImplementedError] Precisa implementar na subclasse
+      #
+      def calculate
+        raise NotImplementedError, "Not implemented #calculate in subclass."
+      end
+
+      # Realiza o cálculo retornando o resto da divisão do cálculo dos fatores por 11.
+      #
+      # @return [Fixnum] Resto da divisão por 11.
+      #
+      def mod_division
+        @mod_division ||= FatoresDeMultiplicacao.new(@number, fatores: fatores).sum % 11
+      end
+
+      # Subtrai 11 do resto da divisão para se ter o total do módulo 11.
+      #
+      # @return [Fixnum]
+      #
+      def total
+        @total ||= 11 - mod_division
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/modulo11_fator_de2a7.rb

@@ -0,0 +1,97 @@
+module BoletoBancario
+  module Calculos
+    # === Módulo 11 Fator de 2 a 7
+    #
+    # === Passos
+    #
+    # 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>OBS.:</b> Se o resto da divisão for “1”, desprezar a diferença entre o divisor
+    # menos o resto que será “10” e considerar o dígito como “P”.
+    #
+    # <b>OBS.:</b> Se o resto da divisão for “0”, desprezar o cálculo de subtração entre
+    # divisor e resto, e considerar o “0” como dígito.
+    #
+    # ==== Exemplo
+    #
+    # Considerando o seguinte número: '89234560'.
+    #
+    # 1) Multiplicando a seqüência de multiplicadores:
+    #
+    #      1    9    0    0    0    0    0    0    0    0    0    0    2
+    #      *    *    *    *    *    *    *    *    *    *    *    *    *
+    #      2    7    6    5    4    3    2    7    6    5    4    3    2
+    #
+    # 2) Soma-se o resultado dos produtos obtidos no item “1” acima:
+    #
+    #      2 +  63 + 0  + 0  + 0  + 0  + 0  + 0  + 0  + 0  + 0  + 0  + 4
+    #      # => 69
+    #
+    # 3) Determina-se o resto da Divisão:
+    #
+    #      69 % 11
+    #      # => 3
+    #
+    # 4) Calcula-se o DAC:
+    #
+    #      11 - 3
+    #      # => 8 =============> Resultado final retornado.
+    #
+    # @param [String]: Corresponde ao número a ser calculado o Módulo 11 no fator de 2 a 7.
+    # @return [String] Retorna o resultado do cálculo descrito acima.
+    #
+    # @example
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a7.new('20')
+    #    # => '5'
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a7.new('64')
+    #    # => '7'
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a7.new('26')
+    #    # => '4'
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a7.new('6')
+    #    # => 'P'
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a7.new('14')
+    #    # => '0'
+    #
+    class Modulo11FatorDe2a7 < Modulo11
+      # Sequência numérica de 2 a 7 que será feito a multiplicação de cada dígito
+      # do número passado no #initialize.
+      #
+      # @return [Array] Sequência numérica
+      #
+      def fatores
+        [2, 3, 4, 5, 6, 7]
+      end
+
+      # Calcula o número pelos fatores de multiplicação de 2 a 7.
+      # Depois calcula o resto da divisão por 11 e subtrai por 11.
+      # Se o resultado desse cálculo for igual a 11, considere DAC = 0.
+      # Se o resultado desse cálculo for igual a 10, considere DAC = P.
+      #
+      # @return [Fixnum]
+      #
+      def calculate
+        return 0 if total.equal?(11)
+
+        if total == 10
+          'P'
+        else
+          total
+        end
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/modulo11_fator_de2a9.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+module BoletoBancario
+  module Calculos
+    # === Módulo 11 Fator de 2 a 9
+    #
+    # === Passos
+    #
+    # 1) Tomando-se os algarismos multiplique-os, iniciando-se da direita para a esquerda,
+    # pela seqüência numérica de 2 a 9 (2, 3, 4, 5, 6, 7, 8, 9 ... 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>OBS.:</b> Se o resultado desta expressão for igual a 0, 1, 10 ou 11, considere DAC = 1.
+    #
+    # ==== Exemplo
+    #
+    # Considerando o seguinte número: '89234560'.
+    #
+    # 1) Multiplicando a seqüência de multiplicadores:
+    #
+    #      8    9    2    3    4    5    6    0
+    #      *    *    *    *    *    *    *    *
+    #      9    8    7    6    5    4    3    2
+    #
+    # 2) Soma-se o resultado dos produtos obtidos no item “1” acima:
+    #
+    #      72 + 72 + 14 + 18 + 20 + 20 + 18 + 0
+    #      # => 234
+    #
+    # 3) Determina-se o resto da Divisão:
+    #
+    #      234 % 11
+    #      # => 3
+    #
+    # 4) Calcula-se o DAC:
+    #
+    #      11 - 3
+    #      # => 8 =============> Resultado final retornado.
+    #
+    # @param [String]: Corresponde ao número a ser calculado o Módulo 11 no fator de 2 a 9.
+    # @return [String] Retorna o resultado do cálculo descrito acima.
+    #
+    # @example
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a9.new('1')
+    #    # => '9'
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a9.new('91')
+    #    # => '4'
+    #
+    #    BoletoBancario::Calculos::Modulo11FatorDe2a9.new('189')
+    #    # => '9'
+    #
+    class Modulo11FatorDe2a9 < Modulo11
+      # Sequência numérica de 2 a 9 que será feito a multiplicação de cada dígito
+      # do número passado no #initialize.
+      #
+      # @return [Array] Sequência numérica
+      #
+      def fatores
+        [2, 3, 4, 5, 6, 7, 8, 9]
+      end
+
+      # Calcula o número pelos fatores de multiplicação de 2 a 9.
+      # Depois calcula o resto da divisão por 11 e subtrai por 11.
+      # Se o resultado desse cálculo for igual a 0, 1, 10 ou 11, considere DAC = 1.
+      #
+      # @return [Fixnum]
+      #
+      def calculate
+        return 1 if total > 9
+
+        total
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/modulo11_fator_de2a9_resto_zero.rb

@@ -0,0 +1,29 @@
+module BoletoBancario
+  module Calculos
+    # Classe responsável por calcular o módulo 11 com fatores de 2 a 9.
+    # <b>Essa classe difere da outra com Modulo11FatorDe2a9, no momento de verificar o resto da divisão por 11.</b>
+    #
+    # <b>Para mais detalhes veja a classe Modulo11FatorDe2a9.</b>
+    #
+    class Modulo11FatorDe2a9RestoZero < Modulo11FatorDe2a9
+      # Realiza o cálculo do módulo 11 com fatores de 2 a 9.
+      #
+      # === Resto Da divisão por 11
+      #
+      # * Se o resto da divisão por 11 for igual a 10, o digito será '1' (um),
+      # * Se o resto da divisão por 11 for igual a 1 (um) ou 0 (zero) o digito será 0 (zero).
+      #
+      # Qualquer “RESTO” diferente de “0, 1 ou 10”, subtrair o resto de 11 para obter o digíto.
+      #
+      # @return [Fixnum] Resultado da subtração ou resultado da verificação do resto da divisão.
+      #
+      def calculate
+        if mod_division.equal?(1) or mod_division.equal?(0)
+          0
+        else
+          total
+        end
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/modulo11_fator_de9a2_resto_x.rb

@@ -0,0 +1,101 @@
+module BoletoBancario
+  module Calculos
+    # === Módulo 11 Fator de 9 a 2 - Resto 10, sendo X
+    #
+    # === 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.
+    #
+    # ==== Exemplo 10 como resto da divisão
+    #
+    # Considerando o seguinte número: '100008'.
+    #
+    # 1) Multiplicando a seqüência de multiplicadores:
+    #
+    #      1    0    0    0    0    8
+    #      *    *    *    *    *    *
+    #      4    5    6    7    8    9
+    #
+    # 2) Soma-se o resultado dos produtos obtidos no item “1” acima:
+    #
+    #      4  + 0  + 0  + 0  + 0 + 72
+    #      # => 76
+    #
+    # 3) Determina-se o resto da Divisão:
+    #
+    #      76 % 11
+    #      # => 10
+    #
+    # 4) Quando o resultado for '10', o dígito será:
+    #
+    #     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')
+    #    # => '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
+
+      # 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.
+      # Se o resultado desse cálculo for menor que 10, retornar o resultado.
+      #
+      # @return [Fixnum]
+      #
+      def calculate
+        if mod_division.equal?(10)
+          'X'
+        else
+          mod_division
+        end
+      end
+    end
+  end
+end