boleto_bancario 0.0.1.beta

data/lib/boleto_bancario/core/santander.rb

@@ -0,0 +1,274 @@
+# 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>
+      # O padrão é zero.
+      #
+      # @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.1.beta'
+end

data/lib/boleto_bancario.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+require 'boleto_bancario/version'
+require 'active_model'
+require 'active_support/core_ext/class'
+require 'active_support/core_ext/enumerable'
+require 'active_support/core_ext/object'
+require 'active_support/core_ext/string'
+
+# Copyright (C) 2012 Tomás D'Stefano <http://successoft.com>
+#
+# @author Tomás D'Stefano <tomas_stefano@successoft.com>
+#
+# == Boleto Bancário
+#
+# Emissão de Boletos Bancários em Ruby. Simples e principalmente, flexível.
+#
+# Essa biblioteca é baseada em outras <b>ótimas</b> bibliotecas.
+# Recomendo analisar muito bem cada solução!
+#
+# * Novo Gateway de Pagamentos da Locaweb: http://www.locaweb.com.br/produtos/gateway-pagamento.html
+# * Brcobranca: https://github.com/kivanio/brcobranca
+# * Boleto Php: http://boletophp.com.br
+# * Stella Caelum: http://stella.caelum.com.br
+#
+# === Coreuições
+#
+# Você pode contribuir de N formas. Seguem elas:
+#
+# * Homologando os boletos junto aos bancos (Super importante!!! :] ).
+# * Fornecendo documentações mais atualizadas dos Bancos.
+# * Escrevendo novos formatos (PDF, PNG), e me avisando para divulgar no Readme.
+# * Refatorando código!! (Sempre bem vindo!)
+# * Fornecendo Feedback construtivo! (Sempre bem vindo!)
+#
+# === Instalação via Rubygems
+#
+#   gem install boleto_bancario
+#
+# === Instalar via Bundler
+#
+# Coloque no Gemfile:
+#
+#   gem 'boleto_bancario'
+#
+# Depois de colocar no Gemfile:
+#
+#   bundle install
+#
+module BoletoBancario
+  # Modulo responsável por guardar todas as regras dos campos de
+  # todos os Boletos Bancários. <b>Contribuicões com novas documentações dos
+  # bancos e homologação dos boletos são extremamente bem vindas!</b>
+  #
+  # Esse módulo também é responsável por guardar todas as regras de validação dos boletos e
+  # contém a forma de chamar os objetos necessários para renderização
+  # dos formatos (pdf, html, etc) e internacionalização dos boletos (caso
+  # 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'
+  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'
+  end
+
+  include Core
+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

data/spec/boleto_bancario/calculos/modulo10_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+module BoletoBancario
+  module Calculos
+    describe Modulo10 do
+      it "should accept the examples by the 'Itau documentation'" do
+        Modulo10.new('341911012').should eq  '1'
+        Modulo10.new('3456788005').should eq '8'
+        Modulo10.new('7123457000').should eq '1'
+      end
+
+      it "returns zero when number is 0" do
+        Modulo10.new('0').should eq '0'
+      end
+
+      it "returns zero when mod 10 is zero" do
+        Modulo10.new('99906').should eq '0'
+      end
+
+      it "calculate when number had 1 digit" do
+        Modulo10.new('1').should eq '8'
+      end
+
+      it "calculate when number had 2 digits" do
+        Modulo10.new('10').should eq '9'
+      end
+
+      it "calculate when number had 3 digits" do
+        Modulo10.new('994').should eq '4'
+      end
+
+      it "calculate when number had 5 digits" do
+        Modulo10.new('97831').should eq '2'
+      end
+
+      it "calculate when number had 6 digits" do
+        Modulo10.new('147966').should eq '6'
+      end
+
+      it "calculate when number had 10 digits" do
+        Modulo10.new('3456788005').should eq '8'
+      end
+
+      it "should accept numbers too" do
+        Modulo10.new(12345).should eq '5'
+      end
+    end
+  end
+end

data/spec/boleto_bancario/calculos/modulo11_fator_de2a7_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+
+module BoletoBancario
+  module Calculos
+    describe Modulo11FatorDe2a7 do
+      context 'with Bradesco documentation example' do
+        subject { Modulo11FatorDe2a7.new('1900000000002') }
+
+        it { should eq '8' }
+      end
+
+      context 'with Bradesco example that returns P' do
+        subject { Modulo11FatorDe2a7.new('1900000000001') }
+
+        it { should eq 'P' }
+      end
+
+      context 'with Bradesco example that returns zero' do
+        subject { Modulo11FatorDe2a7.new('1900000000006') }
+
+        it { should eq '0' }
+      end
+
+      context "when have two digits" do
+        subject { Modulo11FatorDe2a7.new('20') }
+
+        it { should eq '5' }
+      end
+
+      context "when have two digits (more examples)" do
+        subject { Modulo11FatorDe2a7.new('26') }
+
+        it { should eq '4' }
+      end
+
+      context "more examples" do
+        subject { Modulo11FatorDe2a7.new('64') }
+
+        it { should eq '7' }
+      end
+    end
+  end
+end