boleto_bancario 0.0.1.beta

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.DS_Store

data/.rspec

@@ -0,0 +1 @@
+--color -f d

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.9.3@boleto_bancario --create

data/Changelog.markdown

@@ -0,0 +1,6 @@
+# development
+
+* Implementado Banco do Brasil.
+* Implementado Santander.
+* Implementado Bradesco.
+* Implementado Itaú.

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Tomas D'Stefano http://successoft.com
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Planning.markdown

@@ -0,0 +1,131 @@
+# BoletoBancario
+
+Emissão de Boletos Bancários em Ruby. Simples, fácil e principalmente, flexível.
+
+## Alternativas
+
+Essa biblioteca é baseada em outras **ótimas** bibliotecas (**Recomendo analisar muito bem cada solução e usar a que resolver o seu problema!**):
+
+* Stella Caelum [http://stella.caelum.com.br/](http://stella.caelum.com.br/)
+* Novo Gateway de Pagamentos da Locaweb [http://www.locaweb.com.br/produtos/gateway-pagamento.html](http://www.locaweb.com.br/produtos/gateway-pagamento.html)
+* Brcobranca [https://github.com/kivanio/brcobranca](https://github.com/kivanio/brcobranca)
+* Boleto Php [http://boletophp.com.br/](http://boletophp.com.br/)
+* Gem de Boleto Bancário (essa gem) [https://github.com/tomas-stefano/boleto_bancario](https://github.com/tomas-stefano/boleto_bancario)
+
+## Instalação
+
+    gem install boleto_bancario
+
+## Bancos Suportados
+
+* TODO: Precisa escrever essa parte
+
+## Usage
+
+Você pode usar as próprias classes da gem, porém, **recomendo criar uma subclasse** para os bancos que você gostaria de desenvolver.
+
+Exemplo:
+
+```ruby
+  class Itau < BoletoBancario::Itau
+  end
+
+  class Santander < BoletoBancario::Santander
+  end
+
+  class Bradesco < BoletoBancario::Bradesco
+  end
+
+  class BancoBrasil < BoletoBancario::BancoBrasil
+  end
+```
+
+## Attributos
+
+* TODO: Precisa escrever essa parte
+
+## Internacionalização (i18n)
+
+* TODO: Precisa escrever essa parte
+
+## Validações
+
+* TODO: Precisa escrever essa parte
+
+## Código do Banco
+
+* TODO: Precisa escrever essa parte
+
+## Agência / Código do Cedente
+
+* TODO: Precisa escrever essa parte
+
+## Nosso Número
+
+* TODO: Precisa escrever essa parte
+
+## Código de Barras
+
+* TODO: Precisa escrever essa parte
+
+## Linha digitável
+
+* TODO: Precisa escrever essa parte
+
+## Documentação
+
+* TODO: Precisa escrever essa parte
+
+## Formatos
+
+* TODO: Essa parte ainda pode mudar até a versão 0.0.1.
+
+HTML 5 é o formato suportado por enquanto. Para usar em Html, você precisa usar a gem **[boleto_bancario_html](https://github.com/tomas-stefano/boleto_bancario_html)**:
+
+    gem install boleto_bancario_html
+
+E colocar na classe:
+
+```ruby
+  class Itau < BoletoBancario::Itau
+    def format
+      BoletoBancario::HTML5
+    end
+  end
+```
+
+Para renderizar o html:
+
+```ruby
+   itau = Itau.new
+
+   itau.render # Irá chamar o método render da instância do objeto passado no método format.
+```
+
+### Criando um novo Formato
+
+Em relação a parte de formatos a gem de boleto bancário é extremamente flexível.
+
+Basta criar um objeto que responda ao método **render**:
+
+```ruby
+   module BoletoBancario
+     module Formato
+       class Pdf < Boleto
+         def render(*args)
+           # ...
+         end
+       end
+     end
+   end
+```
+
+## Contribuições
+
+Seja um contribuidor. Você pode contribuir de N formas. Seguem elas:
+
+* Homologando boletos junto ao banco.
+* Fornecendo documentações mais atualizadas dos Bancos.
+* Escrevendo novos formatos (PDF, PNG), e me avisando para divulgar no Readme.
+* Refatorando código!!
+* Fornecendo Feedback construtivo! (Sempre bem vindo!)

data/README.markdown

@@ -0,0 +1,208 @@
+# BoletoBancario
+
+Emissão de Boletos Bancários em Ruby.
+
+Foi colocado um esforço enorme para tornar a gem **simples e principalmente, flexível**.
+
+## Versão Beta
+
+Essa gem ainda está em versão beta. Algumas coisas podem mudar até que a versão oficial seja lançada.
+
+## Alternativas
+
+Essa biblioteca é baseada em outras **ótimas** bibliotecas.
+**Recomendo analisar muito bem cada solução**:
+
+* Stella Caelum [http://stella.caelum.com.br/](http://stella.caelum.com.br/)
+* Novo Gateway de Pagamentos da Locaweb [http://www.locaweb.com.br/produtos/gateway-pagamento.html](http://www.locaweb.com.br/produtos/gateway-pagamento.html)
+* Brcobranca [https://github.com/kivanio/brcobranca](https://github.com/kivanio/brcobranca)
+* Boleto Php [http://boletophp.com.br/](http://boletophp.com.br/)
+* Gem de Boleto Bancário (essa gem) [https://github.com/tomas-stefano/boleto_bancario](https://github.com/tomas-stefano/boleto_bancario)
+
+## Instalação
+
+    gem install boleto_bancario
+
+## Documentação
+
+Seguimos todas as documentações que estão dentro do repositório:
+
+* [Bradesco](https://github.com/tomas-stefano/boleto_bancario/tree/master/documentacoes_dos_boletos/bradesco)
+* [Banco do Brasil](https://github.com/tomas-stefano/boleto_bancario/tree/master/documentacoes_dos_boletos/banco_brasil)
+* [Itaú](https://github.com/tomas-stefano/boleto_bancario/tree/master/documentacoes_dos_boletos/itau)
+* [Santander](https://github.com/tomas-stefano/boleto_bancario/tree/master/documentacoes_dos_boletos/santander)
+
+Se você tiver uma documentação do boleto, **mais atualizada**, venha contribuir para a gem. :)
+
+## Bancos Suportados
+
+Para todos os bancos e carteiras implementadas, **seguimos as documentações** que estão dentro do repositório:
+
+<table>
+  <tr>
+    <th>Nome do Banco</th>
+    <th>Carteiras Suportadas</th>
+    <th>Testada/Homologada no banco</th>
+  </tr>
+  <tr>
+    <td>Banco do Brasil</td>
+    <td>
+      12 com código do cedente de 6 dígitos,
+      16 e 18 com código do cedente de 4 dígitos,
+      16 e 18 com código do cedente e nosso número de 17 dígitos,
+      16 e 18 com código do cedente de 6 dígitos,
+      16, 17 e 18 código do cedente de 7 e 8 dígitos.
+    </td>
+    <td>Esperando Contribuição</td>
+  </tr>
+  <tr>
+    <td>Itaú</td>
+    <td>107, 109, 122, 142, 143, 126, 174, 175, 196, 198, 131, 146, 150, 168.</td>
+    <td>Esperando Contribuição</td>
+  </tr>
+  <tr>
+    <td>Bradesco</td>
+    <td>03, 06, 09, 19, 21, 22.</td>
+    <td>Esperando Contribuição</td>
+  </tr>
+  <tr>
+    <td>Santander</td>
+    <td>101, 102, 121.</td>
+    <td>Esperando Contribuição</td>
+  </tr>
+</table>
+
+**OBS.: Caso a homologação seja aceita junto ao banco, contribua e mude a seção acima. Caso recuse alguma carteira acima, por favor me avise, para tirar dessa lista.**
+
+## Homologação no Banco
+
+Uma ótima forma de contribuir para a gem, é validar junto ao banco os boletos implementados acima.
+
+## Usage
+
+Você pode usar as próprias classes da gem, porém, **recomendo criar uma subclasse** para os bancos que você gostaria de desenvolver.
+
+### Exemplo
+
+```ruby
+  class BoletoItau < BoletoBancario::Itau
+  end
+
+  class BoletoSantander < BoletoBancario::Santander
+  end
+
+  class BoletoBradesco < BoletoBancario::Bradesco
+  end
+
+  class BoletoBancoBrasil < BoletoBancario::BancoBrasil
+  end
+```
+
+Segue os attributos dos boletos:
+
+* Agência
+* Dígito da agência
+* Conta Corrente
+* Dígito da Conta Corrente
+* Carteira
+* Cedente
+* Código do Cedente
+* Documento do Cedente
+* Endereço do Cedente
+* Sacado
+* Documento do Sacado
+* Código da Moeda
+* Data do documento
+* Data do vencimento
+* Número do documento
+* Valor do documento (valor do boleto)
+* Espécie
+* Espécie do documento
+
+### Criando os boletos / Validações
+
+Agora você pode emitir um boleto, **usando a classe criada no exemplo acima**:
+
+    BoletoItau.new(conta_corrente: '89755', agencia: '0097', :carteira => '195')
+
+Você pode usar blocos se quiser:
+
+    BoletoItau.new do |boleto|
+      boleto_itau.conta_corrente        = '89755'
+      boleto_itau.digito_conta_corrente = '1'
+      boleto_itau.agencia               = '0097'
+      boleto_itau.carteira              = '198'
+      boleto_itau.cedente               = 'Razao Social da Empresa'
+      boleto_itau.codigo_cedente        = '90901'
+      boleto_itau.endereco_cedente      = 'Rua nome da rua, 9999'
+      boleto_itau.numero_documento      = '12345678'
+      boleto_itau.sacado                = 'Nome do Sacado'
+      boleto_itau.documento_sacado      = '35433793990'
+      boleto_itau.data_vencimento       = Date.tomorrow
+      boleto_itau.valor_documento       = 31678.99
+      boleto_itau.seu_numero            = 1234
+    end
+
+**Cada banco possui suas próprias validações de campo e de tamanho**.
+Primeiramente, **antes de renderizar qualquer boleto você precisar verificar se esse o boleto é válido**.
+
+    if boleto_itau.valid?
+       # Renderiza o boleto itau
+    else
+       # Trata os erros
+    end
+
+### Campos do Boleto
+
+Segue abaixo os métodos para serem chamados, no momento de renderizar os boletos. Os campos são de mesmo nome:
+
+    boleto_itau.codigo_banco_formatado # Retorna o código do banco, junto com seu dígito
+
+    boleto_itau.codigo_de_barras
+
+    boleto_itau.linha_digitavel
+
+    boleto_itau.nosso_numero
+
+    boleto_itau.agencia_codigo_cedente
+
+    boleto_itau.carteira_formatada # Formata a carteira, para mostrar no boleto.
+
+    boleto_itau.numero_documento
+
+    boleto_itau.valor_documento
+
+    boleto_itau.especie
+
+    boleto_itau.especie_documento
+
+## Sobrescrevendo comportamentos
+
+Você pode sobrescrever os comportamentos na subclasse.
+
+Por exemplo, imagine que você quer sobrescrever a forma como é tratada a segunda parte do código de barras.
+**Seguindo a interface da classe BoletoBancario::Boleto** fica bem simples:
+
+    class BoletoItau < BoletoBancario::Itau
+       def codigo_de_barras_do_banco
+         # Sua implementação ...
+       end
+    end
+
+## O que a gem não faz
+
+A gem não trata os arquivos de remessa e os arquivos de retorno do banco.
+
+Na minha opinião não deveria ser responsabilidade dessa gem.
+Essa gem **apenas emite o boleto**, com todas as informações necessárias para o pagamento.
+
+## Contribuições
+
+Seja um contribuidor. Você pode contribuir de N formas. Seguem elas:
+
+* Homologando boletos junto ao banco.
+* Fornecendo documentações mais atualizadas dos Bancos.
+* Escrevendo novos formatos (PDF, PNG), e me avisando para divulgar no Readme.
+* Refatorando código!!
+* Fornecendo Feedback construtivo! (Sempre bem vindo!)
+

data/Rakefile

@@ -0,0 +1,9 @@
+# encoding: utf-8
+require 'bundler/gem_tasks'
+require 'yard'
+
+desc 'Generate documentation'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', 'LICENSE']
+  t.options = ['--main', 'README.markdown', '--no-private', '--title', "Boleto Bancário #{BoletoBancario::VERSION}"]
+end

data/TODO.markdown

@@ -0,0 +1,5 @@
+* 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).

data/boleto_bancario.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/boleto_bancario/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Tomas D'Stefano"]
+  gem.email         = ["tomas_stefano@successoft.com"]
+  gem.description   = %q{Emissão de Boletos Bancários em Ruby}
+  gem.summary       = %q{Emissão de Boletos Bancários em Ruby}
+  gem.homepage      = "https://github.com/tomas-stefano/boleto_bancario"
+
+  gem.files         = `git ls-files`.split($\).reject { |f| File.extname(f) == '.pdf' }
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "boleto_bancario"
+  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_development_dependency "valid_attribute", "~> 1.3"
+  gem.add_development_dependency "pry", "~> 0.9"
+  gem.add_development_dependency "simplecov", "~> 0.2"
+  gem.add_development_dependency "simplecov-html", "~> 0.7"
+end

data/lib/boleto_bancario/calculos/digitos.rb

@@ -0,0 +1,35 @@
+# encoding: utf-8
+require 'active_support/core_ext/enumerable'
+
+module BoletoBancario
+  module Calculos
+    # Classe responsável por lidar com os dígitos dos módulos.
+    #
+    class Digitos
+      # @param [Integer] number Número que servirá para os cálculo com os dígitos desse número.
+      #
+      def initialize(number)
+        @number = number
+      end
+
+      # Soma cada dígito do número passado no #initialize.
+      # Alguns bancos requerem esse tipo estranho de cálculo em alguns módulos.
+      # @return [Fixnum] Resultado da soma de cada dígito.
+      #
+      # @example
+      #
+      #    Digitos.new(12).sum
+      #    # => 3
+      #
+      #    Digitos.new(2244).sum
+      #    # => 12
+      #
+      #    Digitos.new(90123451).sum
+      #    # => 25
+      #
+      def sum
+        @number.to_s.split('').collect { |number| number.to_i }.sum
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/fator_vencimento.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+module BoletoBancario
+  module Calculos
+    # Classe responsável pelo cálculo de Fator de Vencimento do boleto bancário.
+    #
+    # === Descricão
+    #
+    # Conforme Carta-circular 002926 do Banco Central do Brasil, de 24/07/2000, recomenda-se a indicação do Fator de Vencimento no Código de Barras.
+    # A partir de 02/04/2001, o Banco acolhedor/recebedor não será mais responsável por eventuais diferenças de recebimento de BOLETOs fora do prazo,
+    # ou sem a indicação do fator de vencimento.
+    #
+    # === Forma para obtenção do Fator de Vencimento
+    #
+    # Calcula-se <b>o número de dias corridos</b> entre a data base (<b>“Fixada” em 07/10/1997</b>) e a do vencimento desejado:
+    #
+    #    Vencimento desejado:   04/07/2000
+    #    Data base          : - 07/10/1997
+    #    # => 1001
+    #
+    # === Atenção
+    #
+    # Caso ocorra divergência entre a data impressa no campo “data de vencimento” e a constante no código de barras,
+    # o recebimento se dará da seguinte forma:
+    #
+    # * Quando pago por sistemas eletrônicos (Home-Banking, Auto-Atendimento, Internet, SISPAG, telefone, etc.), prevalecerá à representada no “código de barras”;
+    # * Quando quitado na rede de agências, diretamente no caixa, será considerada a data impressa no campo “vencimento” do BOLETO.
+    #
+    # @return [String] retorna o resultado do cálculo. <b>Deve conter 4 dígitos</b>.
+    #
+    # @example
+    #
+    #    FatorVencimento.new(Date.parse("2012-12-02"))
+    #    #=> "5535"
+    #
+    #    FatorVencimento.new(Date.parse("1997-10-08"))
+    #    #=> "0001"
+    #
+    #    FatorVencimento.new(Date.parse("2012-12-16"))
+    #    #=> "5549"
+    #
+    #    FatorVencimento.new(Date.parse("2014-12-15"))
+    #    #=> "6278"
+    #
+    class FatorVencimento < String
+      attr_reader :base_date
+      # @param [Date] expiration_date
+      # @param [Date] base_date
+      # @return [String] retorna o resultado do cálculo. <b>Deve conter 4 dígitos</b>.
+      # @example
+      #    FatorVencimento.new(Date.parse("2012-09-02"))
+      #    #=> "5444"
+      #
+      #    FatorVencimento.new(Date.parse("1999-10-01"))
+      #    #=> "0724"
+      #
+      #    FatorVencimento.new(Date.parse("2022-12-16"))
+      #    #=> "9201"
+      #
+      def initialize(expiration_date, base_date = Date.new(1997, 10, 7))
+        @base_date       = base_date
+        @expiration_date = expiration_date
+
+        if @expiration_date.present?
+          super(calculate)
+        end
+      end
+
+      # Cálculo da data de vencimento com a data base.
+      #
+      # @return [String] exatamente 4 dígitos
+      #
+      def calculate
+        expiration_date_minus_base_date.to_s.rjust(4, '0')
+      end
+
+      # @api private
+      #
+      # Cálculo da data de vencimento com a data base.
+      # Chamando #to_i para não retornar um Float.
+      # @return [Integer] diff between this two dates.
+      #
+      def expiration_date_minus_base_date
+        (@expiration_date - @base_date).to_i
+      end
+    end
+  end
+end

data/lib/boleto_bancario/calculos/fatores_de_multiplicacao.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+module BoletoBancario
+  module Calculos
+    # Classe responsável por multiplicar cada dígito pelos fatores de multiplicação passado como argumento.
+    #
+    # Imagine que temos o número <b>'2468'</b> e os fatores de multiplicação <b>[2, 1]</b>.
+    #
+    # Será calculado da seguinte maneira:
+    #
+    #      2   4   6   8
+    #      *   *   *   * ===> Multiplicação
+    #      1   2   1   2
+    #
+    #      #=> [2,  8,  6,  16]
+    #
+    # Você pode passar outros fatores de multiplicação se você precisar.
+    # Por exemplo, dado o número '1234567890' e os fatores de multiplicação: <b>[2, 3, 4, 5, 6, 7, 8, 9]</b>.
+    # Será calculado da seguinte maneira:
+    #
+    #      1   2    3   4   5   6   7   8   9   0
+    #      *   *    *   *   *   *   *   *   *   *
+    #      3   2    9   8   7   6   5   4   3   2
+    #
+    #      #=> [3,  4,  27, 32, 35, 36, 35, 32, 27,  0]
+    #
+    # @param  [String] O número que será usado para multiplicar cada dígito.
+    # @param [Hash] Os fatores de multiplicação que irão ser calculados na ordem reversa.
+    #
+    # @example Calculo
+    #
+    #    BoletoBancario::Calculos::FatoresDeMultiplicacao.new(123, fatores: [2, 1])
+    #    # => [1, 2, 6]
+    #
+    #    BoletoBancario::Calculos::FatoresDeMultiplicacao.new(123, fatores: [2, 3, 4, 5, 6, 7, 8, 9])
+    #    # => [4, 6, 6]
+    #
+    #    BoletoBancario::Calculos::FatoresDeMultiplicacao.new(809070608090, fatores: [9, 8, 7, 6, 5, 4, 3, 2])
+    #    # => [48, 0, 72, 0, 14, 0, 24, 0, 48, 0, 72, 0]
+    #
+    class FatoresDeMultiplicacao < Array
+      # @param [String || Integer] number
+      # @param [Hash] options
+      # @option options [Array] :fatores
+      # @return [Array]
+      # @example
+      #
+      #    FatoresDeMultiplicacao.new(12, fatores: [2, 1])
+      #    # => [1, 4]
+      #
+      #    FatoresDeMultiplicacao.new(1864, fatores: [2, 3, 4, 5, 6, 7, 8, 9])
+      #    # => [5, 32, 18, 8]
+      #
+      def initialize(number, options)
+        @number  = number.to_s.reverse.split('')
+        @factors = options.fetch(:fatores).cycle.take(@number.size)
+        super(calculate)
+      end
+
+      # Para cada número realiza a multiplicação para cada dígito.
+      # @return [Array]
+      #
+      def calculate
+        @number.collect.each_with_index { |n, index| n.to_i * @factors[index] }.reverse
+      end
+    end
+  end
+end