Class: BoletoBancario::Core::Boleto Abstract

Inherits:
Object
  • Object
show all
Includes:
ActiveModel::Model, BoletoBancario::Calculos
Defined in:
lib/boleto_bancario/core/boleto.rb

Overview

This class is abstract.

Métodos { #codigo_banco, #digito_codigo_banco, #agencia_codigo_cedente, #nosso_numero, #codigo_de_barras_do_banco}

Métodos para serem escritos nas subclasses (exitem outros opcionais, conforme visto nessa documentação).

Direct Known Subclasses

BancoBrasil, Banrisul, Bradesco, Caixa, Hsbc, Itau, Real, Santander, Sicoob, Sicredi

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}, &block) ⇒ Boleto

Passing the attributes as Hash or block

For the options, waiting for the ActiveModel 4 and the ActiveModel::Model. :)

Exemplos

O recomendado é usar os boletos herdando de seu respectivo banco. Por exemplo:

class Itau < BoletoBancario::Itau
end

Agora você pode emitir um boleto usando a classe criada acima:

Itau.new(conta_corrente: '89755', agencia: '0097', :carteira => '195')

Você pode usar blocos se quiser:

Itau.new do |boleto|
  boleto.conta_corrente   = '89755'
  boleto.agencia          = '0097'
  boleto.carteira         = '198'
  boleto.numero_documento = '12345678'
  boleto.codigo_cedente   = '909014'
end

Parameters:

  • options (Hash) (defaults to: {}) —

    Passing a hash accessing the attributes of the self.

  • block (Proc) —

    Optional params. Passing a block accessing the attributes of the self.

Options Hash (options):

  • :cedente (String)
  • :codigo_cedente (String)
  • :documento_cedente (String)
  • :endereco_cedente (String)
  • :conta_corrente (String)
  • :agencia (String)
  • :data_vencimento (Date)
  • :numero_documento (String)
  • :valor_documento (Float)
  • :codigo_moeda (String)
  • :especie (String)
  • :especie_documento (String)
  • :sacado (String)
  • :documento_sacado (String)

Yields:

  • (_self)

Yield Parameters:



244
245
246
247
248
249
250
 
# File 'lib/boleto_bancario/core/boleto.rb', line 244

def initialize(options={}, &block)
  default_options.merge(options).each do |attribute, value|
    send("#{attribute}=", value) if respond_to?("#{attribute}=")
  end

  yield(self) if block_given?
end

Instance Attribute Details

#aceite ⇒ Object

Aceitar após o vencimento. Nessa gem utilizamos o campo aceite como Boolean. Obviamente, true para ‘S’ e false/nil para ‘N’.



162
163
164
 
# File 'lib/boleto_bancario/core/boleto.rb', line 162

def aceite
  @aceite
end

#agencia ⇒ Object

Número da agência. Campo auto explicativo.



82
83
84
 
# File 'lib/boleto_bancario/core/boleto.rb', line 82

def agencia
  @agencia
end

#carteira ⇒ String

Força a carteira a retornar o valor como string

Returns:

  • (String) 


78
79
80
 
# File 'lib/boleto_bancario/core/boleto.rb', line 78

def carteira
  @carteira
end

#cedente ⇒ Object

Nome/Razão social que aparece no campo ‘Cedente’ no boleto.



19
20
21
 
# File 'lib/boleto_bancario/core/boleto.rb', line 19

def cedente
  @cedente
end

#codigo_cedente ⇒ Object

Código do Cedente é o código do cliente, fornecido pelo banco.

Alguns bancos, dependendo do banco e da carteira, precisam desse campo preenchido. Em compensação, outros bancos (a minoria) não fazem utilização desse campo.



26
27
28
 
# File 'lib/boleto_bancario/core/boleto.rb', line 26

def codigo_cedente
  @codigo_cedente
end

#codigo_moeda ⇒ Object

Código da moeda. Campo auto explicativo. Padrão ‘9’ (Real).



91
92
93
 
# File 'lib/boleto_bancario/core/boleto.rb', line 91

def codigo_moeda
  @codigo_moeda
end

#conta_corrente ⇒ Object

Número da Conta corrente. Campo auto explicativo.



86
87
88
 
# File 'lib/boleto_bancario/core/boleto.rb', line 86

def conta_corrente
  @conta_corrente
end

#data_documento ⇒ Object

Data em que o documento foi gerado. Campo auto explicativo.



126
127
128
 
# File 'lib/boleto_bancario/core/boleto.rb', line 126

def data_documento
  @data_documento
end

#data_vencimento ⇒ Object

Data do vencimento do boleto. Campo auto explicativo.

Campo Obrigatório



47
48
49
 
# File 'lib/boleto_bancario/core/boleto.rb', line 47

def data_vencimento
  @data_vencimento
end

#documento_cedente ⇒ Object

Documento do Cedente (CPF ou CNPJ). OBS.: Esse campo não possui validação do campo. Caso você precise imeplemente na subclasse.

Esse campo serve apenas para mostrar no boleto no campo “CPF/CNPJ”.



33
34
35
 
# File 'lib/boleto_bancario/core/boleto.rb', line 33

def documento_cedente
  @documento_cedente
end

#documento_sacado ⇒ Object

Documento do sacado.

OBS.: Esse campo não possui validação do campo. Caso você precise imeplemente na subclasse.

Esse campo serve apenas para mostrar no boleto no campo “CPF/CNPJ”.



144
145
146
 
# File 'lib/boleto_bancario/core/boleto.rb', line 144

def documento_sacado
  @documento_sacado
end

#endereco_cedente ⇒ Object

Deve ser informado o endereço completo do Cedente. Se o título possuir a figura de Sacador Avalista o endereço informado deverá ser do Sacador Avalista, conforme Lei Federal 12.039 de 01/10/2009.

Campo Obrigatório



41
42
43
 
# File 'lib/boleto_bancario/core/boleto.rb', line 41

def endereco_cedente
  @endereco_cedente
end

#endereco_sacado ⇒ Object

Endereço do sacado.

OBS.: Esse campo não possui validação do campo. Caso você precise imeplemente na subclasse.

Esse campo serve apenas para mostrar no boleto no campo “Sacado”.



152
153
154
 
# File 'lib/boleto_bancario/core/boleto.rb', line 152

def endereco_sacado
  @endereco_sacado
end

#especie ⇒ Object

Essencial para identificação da moeda em que a operação foi efetuada.

Padrão ‘R$’ (Real).



97
98
99
 
# File 'lib/boleto_bancario/core/boleto.rb', line 97

def especie
  @especie
end

#especie_documento ⇒ Object

Normalmente se vê neste campo a informação “DM” que quer dizer duplicata mercantil, mas existem inúmeros tipos de espécie, neste caso é aconselhável discutir com o banco qual a espécie de documento será utilizada, a identificação incorreta da espécie do documento não vai impedir que o boleto seja pago e nem que o credito seja efetuado na conta do cliente, mas pode ocasionar na impossibilidade de se protestar o boleto caso venha a ser necessário.

Segue a sigla e descrição do campo especie do documento:

 ---------------------------------
| Sigla  | Descrição             |
----------------------------------
|  NP    | Nota Promissória      |
|  NS    | Nota de Seguro        |
|  CS    | Cobrança Seriada      |
|  REC   | Recibo                |
|  LC    | Letras de Câmbio      |
|  ND    | Notas de débito       |
|  DS    | Duplicata de Serviços |
|  DM    | Duplicata Mercantil   |
---------------------------------|

Padrão ‘DM’ (Duplicata Mercantil)



122
123
124
 
# File 'lib/boleto_bancario/core/boleto.rb', line 122

def especie_documento
  @especie_documento
end

#instrucoes1 ⇒ Object

Campos de instruções. São permitidas até seis linhas de instruções a serem mostradas no boleto



167
168
169
 
# File 'lib/boleto_bancario/core/boleto.rb', line 167

def instrucoes1
  @instrucoes1
end

#instrucoes2 ⇒ Object

Campos de instruções. São permitidas até seis linhas de instruções a serem mostradas no boleto



167
168
169
 
# File 'lib/boleto_bancario/core/boleto.rb', line 167

def instrucoes2
  @instrucoes2
end

#instrucoes3 ⇒ Object

Campos de instruções. São permitidas até seis linhas de instruções a serem mostradas no boleto



167
168
169
 
# File 'lib/boleto_bancario/core/boleto.rb', line 167

def instrucoes3
  @instrucoes3
end

#instrucoes4 ⇒ Object

Campos de instruções. São permitidas até seis linhas de instruções a serem mostradas no boleto



167
168
169
 
# File 'lib/boleto_bancario/core/boleto.rb', line 167

def instrucoes4
  @instrucoes4
end

#instrucoes5 ⇒ Object

Campos de instruções. São permitidas até seis linhas de instruções a serem mostradas no boleto



167
168
169
 
# File 'lib/boleto_bancario/core/boleto.rb', line 167

def instrucoes5
  @instrucoes5
end

#instrucoes6 ⇒ Object

Campos de instruções. São permitidas até seis linhas de instruções a serem mostradas no boleto



167
168
169
 
# File 'lib/boleto_bancario/core/boleto.rb', line 167

def instrucoes6
  @instrucoes6
end

#local_pagamento ⇒ Object

Descrição do local do pagamento.



156
157
158
 
# File 'lib/boleto_bancario/core/boleto.rb', line 156

def local_pagamento
  @local_pagamento
end

#logo ⇒ Object

Caminho do logo do banco.



176
177
178
 
# File 'lib/boleto_bancario/core/boleto.rb', line 176

def 
  @logo
end

#numero_documento ⇒ Object

Número do documento que será mostrado no boleto. Campo de resposabilidade do Cedente e cada banco possui um tamanho esperado.



52
53
54
 
# File 'lib/boleto_bancario/core/boleto.rb', line 52

def numero_documento
  @numero_documento
end

#sacado ⇒ Object

Nome do sacado.

O sacado é a pessoa para o qual o boleto está sendo emitido, podemos resumir dizendo que o sacado é o cliente do Cedente, ou aquele para o qual uma determina mercadoria foi vendida e o pagamento desta será efetuado por meio de boleto de cobrança.

Campo Obrigatório.



136
137
138
 
# File 'lib/boleto_bancario/core/boleto.rb', line 136

def sacado
  @sacado
end

#valor_documento ⇒ Object

Valor total do documento. Campo auto explicativo.

Campo Obrigatório.



58
59
60
 
# File 'lib/boleto_bancario/core/boleto.rb', line 58

def valor_documento
  @valor_documento
end

Class Method Details

.valor_documento_tamanho_maximo ⇒ Float

Tamanho maximo do valor do documento do boleto. Acredito que não existirá valor de documento nesse valor, porém a biblioteca precisa manter a consistência.

No código de barras o valor do documento precisa ter um tamanho de 8 caracteres para os reais (acrescentando zeros à esquerda), e 2 caracteres nos centavos (acrescentando zeros à esquerda).

Returns:

  • (Float) —

    99999999.99



188
189
190
 
# File 'lib/boleto_bancario/core/boleto.rb', line 188

def self.valor_documento_tamanho_maximo
  99999999.99
end

Instance Method Details

#aceite_formatado ⇒ String

Se o aceite for ‘true’, retorna ‘S’. Retorna ‘N’, caso contrário.

Returns:

  • (String) 


377
378
379
380
381
382
383
 
# File 'lib/boleto_bancario/core/boleto.rb', line 377

def aceite_formatado
  if @aceite.present?
    'S'
  else
    'N'
  end
end

#agencia_codigo_cedente ⇒ String

Agência, código do cedente ou nosso número. Esse campo é específico para cada banco.

Returns:

  • (String) —

    • Corresponde aos campos “Agencia / Codigo do Cedente”.

Raises:

  • (NotImplementedError) —

    Precisa implementar nas subclasses.



316
317
318
 
# File 'lib/boleto_bancario/core/boleto.rb', line 316

def agencia_codigo_cedente
  raise NotImplementedError.new("Not implemented #agencia_codigo_cedente in #{self}.")
end

#carteira_formatada ⇒ String

Embora o padrão seja mostrar o número da carteira no boleto, alguns bancos requerem que seja mostrado um valor diferente na carteira. Para essas exceções, sobrescreva esse método na subclasse.

Returns:

  • (String) —

    retorna o número da carteira



368
369
370
 
# File 'lib/boleto_bancario/core/boleto.rb', line 368

def carteira_formatada
  carteira
end

#codigo_banco ⇒ String

Código do Banco. Esse campo é específico para cada banco.

Returns:

  • (String) —

    Corresponde ao código do banco.

Raises:

  • (NotImplementedError) —

    Precisa implementar nas subclasses.



287
288
289
 
# File 'lib/boleto_bancario/core/boleto.rb', line 287

def codigo_banco
  raise NotImplementedError.new("Not implemented #codigo_banco in #{self}.")
end

#codigo_banco_formatado ⇒ String

Formata o código do banco com o dígito do código do banco. Método usado para o campo de código do banco localizado no cabeçalho do boleto.

Returns:

  • (String) 


306
307
308
 
# File 'lib/boleto_bancario/core/boleto.rb', line 306

def codigo_banco_formatado
  "#{codigo_banco}-#{digito_codigo_banco}"
end

#codigo_de_barras ⇒ String

Código de Barras

O código de barras contêm exatamente 44 posições nessa sequência:

 ____________________________________________________________
| Posição  | Tamanho | Descrição                            |
|----------|---------|--------------------------------------|
| 01-03    |  03     | Código do banco                      |
| 04       |  01     | Código da moeda                      |
| 05       |  01     | Dígito do código de barras (DAC)     |
| 06-09    |  04     | Fator de vencimento                  |
| 10-19    |  10     | Valor do documento                   |
| 20-44    |  25     | Critério de cada Banco (Campo livre) |
-------------------------------------------------------------

Returns:

  • (String) —

    Código de barras com 44 posições.



411
412
413
 
# File 'lib/boleto_bancario/core/boleto.rb', line 411

def codigo_de_barras
  "#{codigo_de_barras_padrao}#{codigo_de_barras_do_banco}".insert(4, digito_codigo_de_barras)
end

#codigo_de_barras_do_banco ⇒ String

Segunda parte do código de barras. Esse campo é específico para cada banco.

Returns:

  • (String) —

    25 últimas posições do código de barras.

Raises:

  • (NotImplementedError) —

    Precisa implementar nas subclasses.



430
431
432
 
# File 'lib/boleto_bancario/core/boleto.rb', line 430

def codigo_de_barras_do_banco
  raise NotImplementedError.new("Not implemented #codigo_de_barras_do_banco in #{self}.")
end

#codigo_de_barras_padrao ⇒ String

Primeira parte do código de barras. Essa parte do código de barras é padrão para todos os bancos..

Returns:

  • (String) —

    Primeiras 18 posições do código de barras (Não retorna o DAC do código de barras).



420
421
422
 
# File 'lib/boleto_bancario/core/boleto.rb', line 420

def codigo_de_barras_padrao
  "#{codigo_banco}#{codigo_moeda}#{fator_de_vencimento}#{valor_formatado_para_codigo_de_barras}"
end

#data_vencimento_deve_ser_uma_data ⇒ Object

Verifica e valida se a data do vencimento deve ser uma data válida. Precisa ser uma data para o cálculo do fator do vencimento.



553
554
555
 
# File 'lib/boleto_bancario/core/boleto.rb', line 553

def data_vencimento_deve_ser_uma_data
  errors.add(:data_vencimento, :invalid) unless data_vencimento.kind_of?(Date)
end

#default_options ⇒ Hash

Opções default.

Caso queira sobrescrever as opções, você pode simplesmente instanciar o objeto passando a opção desejada:

class Bradesco < BoletoBancario::Bradesco
end

Bradesco.new do |bradesco|
  bradesco.codigo_moeda      = 'outro_codigo_da_moeda'
  bradesco.especie           = 'outra_especie_que_nao_seja_em_reais'
  bradesco.especie_documento = 'outra_especie_do_documento'
  bradesco.data_documento    = Date.tomorrow
  bradesco.aceite            = false
end

Returns:

  • (Hash) —

    Código da Moeda sendo ‘9’ (real). Espécie sendo ‘R$’ (real).



269
270
271
272
273
274
275
276
277
278
 
# File 'lib/boleto_bancario/core/boleto.rb', line 269

def default_options
  {
    :codigo_moeda      => '9',
    :especie           => 'R$',
    :especie_documento => 'DM',
    :local_pagamento   => 'PAGÁVEL EM QUALQUER BANCO ATÉ O VENCIMENTO',
    :data_documento    => Date.today,
    :aceite            => true
  }
end

#deve_validar_agencia? ⇒ True

Método usado para verificar se deve realizar a validação de tamanho do campo ‘agência’. Sobrescreva esse método na subclasse, caso você mesmo queira fazer as validações.

Returns:

  • (True) 


510
511
512
 
# File 'lib/boleto_bancario/core/boleto.rb', line 510

def deve_validar_agencia?
  true
end

#deve_validar_carteira? ⇒ True

Método usado para verificar se deve realizar a validação do campo ‘carteira’. Sobrescreva esse método na subclasse, caso você mesmo queira fazer as validações.

Returns:

  • (True) 


546
547
548
 
# File 'lib/boleto_bancario/core/boleto.rb', line 546

def deve_validar_carteira?
  true
end

#deve_validar_codigo_cedente? ⇒ True

Método usado para verificar se deve realizar a validação de tamanho do campo ‘codigo_cedente’. Sobrescreva esse método na subclasse, caso você mesmo queira fazer as validações.

Returns:

  • (True) 


528
529
530
 
# File 'lib/boleto_bancario/core/boleto.rb', line 528

def deve_validar_codigo_cedente?
  true
end

#deve_validar_conta_corrente? ⇒ True

Método usado para verificar se deve realizar a validação de tamanho do campo ‘conta_corrente’. Sobrescreva esse método na subclasse, caso você mesmo queira fazer as validações.

Returns:

  • (True) 


519
520
521
 
# File 'lib/boleto_bancario/core/boleto.rb', line 519

def deve_validar_conta_corrente?
  true
end

#deve_validar_numero_documento? ⇒ True

Método usado para verificar se deve realizar a validação de tamanho do campo ‘numero_documento’. Sobrescreva esse método na subclasse, caso você mesmo queira fazer as validações.

Returns:

  • (True) 


537
538
539
 
# File 'lib/boleto_bancario/core/boleto.rb', line 537

def deve_validar_numero_documento?
  true
end

#digito_codigo_banco ⇒ String

Dígito do código do banco. Esse campo é específico para cada banco.

Returns:

  • (String) —

    Corresponde ao dígito do código do banco.

Raises:

  • (NotImplementedError) —

    Precisa implementar nas subclasses.



297
298
299
 
# File 'lib/boleto_bancario/core/boleto.rb', line 297

def digito_codigo_banco
  raise NotImplementedError.new("Not implemented #digito_codigo_banco in #{self}.")
end

#digito_codigo_de_barras ⇒ String

Dígito verificador do código de barras (DAC).

Por definição da FEBRABAN e do Banco Central do Brasil, na 5º posição do Código de Barras, deve ser indicado obrigatoriamente o “dígito verificador” (DAC), calculado através do módulo 11.

OBS.: Para mais detalhes deste cálculo, veja a descrição em BoletoBancario::Calculos::Modulo11FatorDe2a9.

Returns:

  • (String) —

    Dígito calculado do código de barras.



445
446
447
 
# File 'lib/boleto_bancario/core/boleto.rb', line 445

def digito_codigo_de_barras
  Modulo11FatorDe2a9.new("#{codigo_de_barras_padrao}#{codigo_de_barras_do_banco}")
end

#fator_de_vencimento ⇒ String

Fator de vencimento que é calculado a partir de uma data base. Veja FatorVencimento para mais detalhes.

Returns:

  • (String) —

    4 caracteres.



390
391
392
 
# File 'lib/boleto_bancario/core/boleto.rb', line 390

def fator_de_vencimento
  FatorVencimento.new(data_vencimento)
end

#linha_digitavel ⇒ String

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.

OBS.: 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 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)        |
-------------------------------------------------------------------------------------------------------|

Returns:

  • (String) —

    Contêm a representação numérica do código de barras formatado com pontos e espaços.



483
484
485
 
# File 'lib/boleto_bancario/core/boleto.rb', line 483

def linha_digitavel
  LinhaDigitavel.new(codigo_de_barras)
end

#nosso_numero ⇒ String

O Nosso Número é o número que identifica unicamente um boleto para uma conta. O tamanho máximo do Nosso Número depende do banco e carteira.

Para carteiras registradas, você deve solicitar ao seu banco um intervalo de números para utilização. Quando estiver perto do fim do intervalo, deve solicitar um novo intervalo.

Para carteiras não registradas o Nosso Número é livre. Ao receber o retorno do banco, é através do Nosso Número que será possível identificar os boletos pagos.

Esse campo é específico para cada banco.

Returns:

  • (String) —

    Corresponde ao formato específico de cada banco.

Raises:

  • (NotImplementedError) —

    Precisa implementar nas subclasses.



334
335
336
 
# File 'lib/boleto_bancario/core/boleto.rb', line 334

def nosso_numero
  raise NotImplementedError.new("Not implemented #nosso_numero in #{self}.")
end

#persisted? ⇒ False

Seguindo a interface do Active Model.

Returns:

  • (False) 


501
502
503
 
# File 'lib/boleto_bancario/core/boleto.rb', line 501

def persisted?
  false
end

#to_partial_path ⇒ String

Returns a string that identifying the render path associated with the object.

ActionPack uses this to find a suitable partial to represent the object.

Returns:

  • (String) 


493
494
495
 
# File 'lib/boleto_bancario/core/boleto.rb', line 493

def to_partial_path
  "boleto_bancario/#{self.class.name.demodulize.underscore}"
end

#valor_formatado_para_codigo_de_barras ⇒ String

Formata o valor do documentado para ser mostrado no código de barras e na linha digitável com 08 dígitos na casa dos Reais e 02 dígitos nas casas dos centavos.

Examples:


Bradesco.new(:valor_documento => 123.45).valor_formatado_para_codigo_de_barras
# => "0000012345"

Returns:

  • (String) —

    Precisa retornar 10 dígitos para o código de barras (incluindo os centavos).



348
349
350
351
352
 
# File 'lib/boleto_bancario/core/boleto.rb', line 348

def valor_formatado_para_codigo_de_barras
  valor_documento_formatado = (Integer(valor_documento.to_f * 100) / Float(100))
  real, centavos            = valor_documento_formatado.to_s.split(/\./)
  "#{real.rjust(8, '0')}#{centavos.ljust(2, '0')}"
end