conectiva-boleto_bancario 0.0.2.beta

data/lib/boleto_bancario/core/santander.rb

@@ -0,0 +1,273 @@
+# encoding: utf-8
+module BoletoBancario
+  module Core
+    # Implementação de emissão de boleto bancário pelo Santander.
+    #
+    # === Documentação Implementada
+    #
+    # A documentação na qual essa implementação foi baseada está localizada na pasta
+    # 'documentacoes_dos_boletos/santander' 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
+    #
+    # Segue abaixo as carteiras suportadas do itáu <b>seguindo a documentação</b>:
+    #
+    #      _________________________________________________________________________
+    #     | Carteira | Descrição                     | Testada/Homologada no banco |
+    #     |   101    | Cobrança Simples com registro | Esperando Contribuição      |
+    #     |   102    | Cobrança Simples sem registro | Esperando Contribuição      |
+    #     |   121    | Penhor Rápida com registro    | Esperando Contribuição      |
+    #     --------------------------------------------------------------------------
+    #
+    # <b>OBS.: Seja um contribuidor dessa gem. Contribua para homologar os boletos e as
+    # devidas carteiras junto ao banco Santander.</b>
+    #
+    # === Validações
+    #
+    # Caso você queira <b>desabilitar todas as validações</b>, existem alguns métodos que você pode sobrescrever
+    # na subclasse que você irá criar. No exemplo abaixo, desabilitará todas as validações:
+    #
+    #    class Santander < BoletoBancario::Santander
+    #      def deve_validar_agencia?
+    #        false
+    #      end
+    #
+    #      def deve_validar_codigo_cedente?
+    #        false
+    #      end
+    #
+    #      def deve_validar_numero_documento?
+    #        false
+    #      end
+    #
+    #      def deve_validar_carteira?
+    #        false
+    #      end
+    #    end
+    #
+    # <b>OBS.:</b> Muito cuidado ao desabilitar as validações, pois poderá ocorrer problemas no código de barras e na
+    # linha digitável. Ambos os métodos podem ser sobrescritos se você quiser também.
+    #
+    class Santander < Boleto
+      # Campo IOF que será mostrado no código de barras.
+      # Padrão é 0 (zero), conforme a documentação do Santander.
+      # Para mais detalhes veja o método #iof.
+      #
+      attr_accessor :iof
+
+      # Tamanho máximo de uma agência no Banco Bradesco.
+      # <b>Método criado justamente para ficar documentado o tamanho máximo aceito até a data corrente.</b>
+      #
+      # @return [Fixnum] 4
+      #
+      def self.tamanho_maximo_agencia
+        4
+      end
+
+      # Tamanho máximo do número do documento emitido no Boleto.
+      # O tamanho máximo é justamente 8 porque no código de barras só é permitido 8 posições para este campo.
+      #
+      # <b>Método criado justamente para ficar documentado o tamanho máximo aceito até a data corrente.</b>
+      #
+      # @return [Fixnum] 11
+      #
+      def self.tamanho_maximo_numero_documento
+        12
+      end
+
+      # Tamanho máximo da carteira.
+      # O tamanho máximo é justamente 2 porque no código de barras só é permitido 2 posições para este campo.
+      #
+      # <b>Método criado justamente para ficar documentado o tamanho máximo aceito até a data corrente.</b>
+      #
+      # @return [Fixnum] 2
+      #
+      def self.tamanho_maximo_carteira
+        3
+      end
+
+      # Tamanho máximo do código do cedente emitido no Boleto.
+      # O tamanho máximo é justamente 7 porque no código de barras só é permitido 7 posições para este campo.
+      #
+      # <b>Método criado justamente para ficar documentado o tamanho máximo aceito até a data corrente.</b>
+      #
+      # @return [Fixnum] 7
+      #
+      def self.tamanho_maximo_codigo_cedente
+        7
+      end
+
+      # Validações de tamanho para os campos abaixo:
+      #
+      # * Número do documento
+      # * Conta Corrente
+      # * Agencia
+      # * Carteira
+      #
+      # Se você quiser sobrescrever os tamanhos permitidos, <b>ficará a sua responsabilidade.</b>
+      # Basta você sobrescrever os métodos de validação:
+      #
+      #    class Santander < BoletoBancario::Core::Santander
+      #       def self.tamanho_maximo_agencia
+      #         5
+      #       end
+      #
+      #       def self.tamanho_maximo_codigo_cedente
+      #         8
+      #       end
+      #
+      #       def self.tamanho_maximo_numero_documento
+      #         9
+      #       end
+      #    end
+      #
+      # Obs.: Mudar as regras de validação podem influenciar na emissão do boleto em si.
+      # Talvez você precise analisar o efeito no #codigo_de_barras e na #linha_digitável (ambos podem ser
+      # sobreescritos também).
+      #
+      validates :agencia, :codigo_cedente, presence: true
+
+      validates :agencia,          length: { maximum: tamanho_maximo_agencia          }, if: :deve_validar_agencia?
+      validates :codigo_cedente,   length: { maximum: tamanho_maximo_codigo_cedente   }, if: :deve_validar_codigo_cedente?
+      validates :numero_documento, length: { maximum: tamanho_maximo_numero_documento }, if: :deve_validar_numero_documento?
+      validates :carteira,         length: { maximum: tamanho_maximo_carteira         }, if: :deve_validar_carteira?
+
+      # @return [String] 4 caracteres
+      #
+      def agencia
+        @agencia.to_s.rjust(4, '0') if @agencia.present?
+      end
+
+      # @return [String] 7 caracteres
+      #
+      def codigo_cedente
+        @codigo_cedente.to_s.rjust(7, '0') if @codigo_cedente.present?
+      end
+
+      # @return [String] 12 caracteres
+      #
+      def numero_documento
+        @numero_documento.to_s.rjust(12, '0') if @numero_documento.present?
+      end
+
+      # @return [String] 3 caracteres
+      #
+      def carteira
+        @carteira.to_s.rjust(3, '0') if @carteira.present?
+      end
+
+      # Formata a carteira dependendo se ela é registrada ou não.
+      #
+      # Para cobrança COM registro usar: <b>COBRANCA SIMPLES ECR</b>
+      #
+      # Para Cobrança SEM registro usar: <b>COBRANCA SIMPLES CSR</b>
+      #
+      # @return [String]
+      #
+      def carteira_formatada
+        if @carteira.to_s.in?(carteiras_com_registro)
+          "COBRANÇA SIMPLES ECR"
+        else
+          'COBRANÇA SIMPLES CSR'
+        end
+      end
+
+      # Retorna as carteiras com registro do banco Santander.
+      # <b>Você pode sobrescrever esse método na subclasse caso exista mais
+      # carteiras com registro no Santander.</b>
+      #
+      # @return [Array]
+      #
+      def carteiras_com_registro
+        %w(101 121)
+      end
+
+      # @return [String] Código do Banco descrito na documentação.
+      #
+      def codigo_banco
+        '033'
+      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
+        '7'
+      end
+
+      # Campo Agência / Código do Cedente (Número fornecido pelo Banco)
+      #
+      # @return [String]
+      #
+      def agencia_codigo_cedente
+        "#{agencia}-#{digito_agencia} / #{codigo_cedente}"
+      end
+
+      # Mostra o campo nosso número calculando o dígito verificador do nosso número.
+      #
+      # @return [String]
+      #
+      def nosso_numero
+        "#{numero_documento}-#{digito_nosso_numero}"
+      end
+
+      # Calcula o dígito do nosso número pelo Módulo 11 fator de 2 a 9 verificando o resto como zero.
+      # Para mais detalhes veja a classe <b>BoletoBancario::Calculos::Modulo11FatorDe2a9RestoZero</b>.
+      #
+      # @return [String]
+      #
+      def digito_nosso_numero
+        Modulo11FatorDe2a9RestoZero.new(numero_documento)
+      end
+
+      #  === Código de barras do banco
+      #
+      #     ___________________________________________________________________________________________________
+      #    | Posição  | Tamanho | Descrição                                                                   |
+      #    |----------|---------|-----------------------------------------------------------------------------|
+      #    | 20       |  01     | Fixo '9'                                                                    |
+      #    | 21-27    |  07     | Código do cedente padrão Santander                                          |
+      #    | 28-40    |  13     | Nosso Número (veja a observação abaixo)                                     |
+      #    | 41       |  01     | IOF (veja o método #iof)                                                    |
+      #    | 42-44    |  03     | Carteira                                                                    |
+      #    ----------------------------------------------------------------------------------------------------
+      #
+      # <b>OBS.:</b> Caso o arquivo de registro para os títulos seja de 400 bytes (CNAB).
+      # Utilizar somente 08 posições do Nosso Numero (07 posições + DV), zerando os 05 primeiros dígitos.
+      # Utilizar somente 09 posições do Nosso Numero (08 posições + DV), zerando os 04 primeiros dígitos.
+      #
+      # Para utilizar esse número de posições no nosso número é só colocar o tamanho ideal no
+      # numero_documento.
+      # Por exemplo:
+      #
+      #    Santander.new(:numero_documento => '1234567')  # Irá zerar os 05 primeiros dígitos.
+      #    Santander.new(:numero_documento => '12345678') # Irá zerar os 04 primeiros dígitos.
+      #
+      # @return [String]
+      #
+      def codigo_de_barras_do_banco
+        "9#{codigo_cedente}#{numero_documento}#{digito_nosso_numero}#{iof}#{carteira}"
+      end
+
+      # IOF é a sigla de Imposto sobre Operações de Crédito, Câmbio e Seguros,
+      # e é um imposto federal no Brasil.
+      #
+      # Seguradoras (Se 7% informar 7. Limitado a 9%)
+      # <b>Demais clientes usar 0 (zero)</b>
+      #
+      # @return [String]
+      #
+      def iof
+        return @iof.to_s if @iof.present?
+
+        '0'
+      end
+    end
+  end
+end

data/lib/boleto_bancario/version.rb

@@ -0,0 +1,4 @@
+module BoletoBancario
+  # @version '0.0.1'
+  VERSION = '0.0.2.beta'
+end

data/spec/boleto_bancario/calculos/digitos_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+module BoletoBancario
+  module Calculos
+    describe Digitos do
+      (0..9).each do |number|
+        it "should return self when is #{number}" do
+          Digitos.new(number).sum.should eq number
+        end
+      end
+
+      { 11 => 2, '18' => 9, 99 => 18, '58' => 13, 112 => 4, '235' => 10 }.each do |number, expecting|
+        it "should sum the sum of the digits when is '#{number}', expecting to be '#{expecting}'" do
+          Digitos.new(number).sum.should eq expecting
+        end
+      end
+    end
+  end
+end

data/spec/boleto_bancario/calculos/fator_vencimento_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+module BoletoBancario
+  module Calculos
+    describe FatorVencimento do
+      describe "#base_date" do
+        it "should be 1997-10-07" do
+          FatorVencimento.new(Date.parse("2012-02-01")).base_date.should eq Date.new(1997, 10, 7)
+        end
+      end
+
+      describe "#calculate" do
+        it 'should return an empty string when passing nil value' do
+          FatorVencimento.new(nil).should eq ''
+        end
+
+        it 'should return an empty string when passing empty value' do
+          FatorVencimento.new('').should eq ''
+        end
+
+        it "should calculate the days between expiration date and base date" do
+          FatorVencimento.new(Date.parse("2012-12-2")).should eq "5535"
+        end
+
+        it "should calculate equal to itau documentation example" do
+          FatorVencimento.new(Date.parse("2000-07-04")).should eq "1001"
+        end
+
+        it "should calculate equal to itau documentation last section of the docs" do
+          FatorVencimento.new(Date.parse("2002-05-01")).should eq "1667"
+        end
+
+        it "should calculate to the maximum date equal to itau documentation example" do
+          FatorVencimento.new(Date.parse("2025-02-21")).should eq "9999"
+        end
+
+        it "should calculate the days between expiration date one year ago" do
+          FatorVencimento.new(Date.parse("2011-05-25")).should eq "4978"
+        end
+
+        it "should calculate the days between expiration date two years ago" do
+          FatorVencimento.new(Date.parse("2010-10-02")).should eq "4743"
+        end
+
+        it "should calculate the days between expiration date one year from now" do
+          FatorVencimento.new(Date.parse("2013-02-01")).should eq "5596"
+        end
+
+        it "should calculate the days between expiration date eigth years from now" do
+          FatorVencimento.new(Date.parse("2020-02-01")).should eq "8152"
+        end
+
+        it "should calculate the days between expiration date formating with 4 digits" do
+          FatorVencimento.new(Date.parse("1997-10-08")).should eq "0001"
+        end
+      end
+    end
+  end
+end

data/spec/boleto_bancario/calculos/fatores_de_multiplicacao_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+module BoletoBancario
+  module Calculos
+    describe FatoresDeMultiplicacao do
+      context 'with factors of 2 and 1' do
+        let(:factors) { [2, 1] }
+
+        context 'with one digit' do
+          subject { FatoresDeMultiplicacao.new(1, fatores: factors) }
+
+          it { should eq [2] }
+        end
+
+        context 'with four digits' do
+          subject { FatoresDeMultiplicacao.new(1234, fatores: factors) }
+
+          it { should eq [1, 4, 3, 8] }
+        end
+
+        context 'with five digits' do
+          subject { FatoresDeMultiplicacao.new(11385, fatores: factors) }
+
+          it { should eq [2, 1, 6, 8, 10] }
+        end
+
+        context 'with ten digits' do
+          subject { FatoresDeMultiplicacao.new(1234567890, fatores: factors) }
+
+          it { should eq [1, 4, 3, 8, 5, 12, 7, 16, 9, 0] }
+        end
+      end
+
+      context 'with factors of 2..9' do
+        let(:factors) { (2..9).to_a }
+
+        context 'with one digit' do
+          subject { FatoresDeMultiplicacao.new(4, fatores: factors) }
+
+          it { should eq [8] }
+        end
+
+        context 'with four digits' do
+          subject { FatoresDeMultiplicacao.new(1864, fatores: factors) }
+
+          it { should eq [ 5, 32, 18, 8] }
+        end
+
+        context 'with ten digits' do
+          subject { FatoresDeMultiplicacao.new(1234567890, fatores: factors) }
+        end
+
+        context 'with bradesco documentation example' do
+          let(:bradesco_example) { '9999101200000350007772130530150081897500000' }
+          subject { FatoresDeMultiplicacao.new(bradesco_example, fatores: factors) }
+
+          it { should eq [36, 27, 18, 81, 8, 0, 6, 10, 0, 0, 0, 0, 0, 21, 30, 0, 0, 0, 14, 63, 56, 14, 6, 15, 0, 15, 6, 0, 8, 35, 0, 0, 32, 3, 16, 81, 56, 35, 0, 0, 0, 0, 0] }
+        end
+
+        context 'with itau documentation example' do
+          let(:itau_example) { '3419166700000123451101234567880057123457000' }
+          subject { FatoresDeMultiplicacao.new(itau_example, fatores: factors) }
+
+          it { should eq [12, 12, 2, 81, 8, 42, 36, 35, 0, 0, 0, 0, 0, 7, 12, 15, 16, 15, 2, 9, 0, 7, 12, 15, 16, 15, 12, 63, 64, 56, 0, 0, 20, 21, 2, 18, 24, 28, 30, 35, 0, 0, 0] }
+        end
+      end
+    end
+  end
+end

data/spec/boleto_bancario/calculos/linha_digitavel_spec.rb

@@ -0,0 +1,57 @@
+require 'spec_helper'
+
+module BoletoBancario
+  module Calculos
+    describe LinhaDigitavel do
+      context "using the Itau documentation example" do
+        subject { LinhaDigitavel.new('34196166700000123451091234567880057123457000') }
+
+        it { should eq '34191.09123 34567.880058 71234.570001 6 16670000012345' }
+      end
+
+      context "using the Bradesco documentation example" do
+        subject { LinhaDigitavel.new('99991101200000350007772130530150081897500000') }
+
+        it { should eq '99997.77213 30530.150082 18975.000003 1 10120000035000' }
+      end
+
+      context "using the HSBC documentation example" do
+        subject { LinhaDigitavel.new('39998100100000311551111122222500546666666001') }
+
+        it { should eq '39991.11119 22222.500542 66666.660015 8 10010000031155' }
+      end
+
+      context "using the Caixa documentation example" do
+        subject { LinhaDigitavel.new('10491107400000160000001100128701000901200200') }
+
+        it { should eq '10490.00118 00128.701000 09012.002003 1 10740000016000' }
+      end
+
+      describe "when 'codigo_de_barras' invalid" do
+        context "when is empty" do
+          subject { LinhaDigitavel.new('') }
+
+          it { should eq '' }
+        end
+
+        context "when nil" do
+          subject { LinhaDigitavel.new(nil) }
+
+          it { should eq '' }
+        end
+
+        context "when have less than 44 positions" do
+          subject { LinhaDigitavel.new('121212121') }
+
+          it { should eq '' }
+        end
+
+        context "when have more than 44 positions" do
+          subject { LinhaDigitavel.new('12345678901234567890123456789012345678901234567890') }
+
+          it { should eq '' }
+        end
+      end
+    end
+  end
+end