Emissão de Boletos Bancários em Ruby
Ruby
Latest commit 617d419 Aug 28, 2015 @tomas-stefano Update readme

README.markdown

Boleto Bancario

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:

Instalação

gem install boleto_bancario

Documentação

Seguimos todas as documentações descritas abaixo:

Se você tiver uma documentação do boleto, mais atualizada, gostaria de pedir que você me enviasse. :)

Bancos Suportados

Para todos os bancos e carteiras implementadas, seguimos as documentações que estão dentro do repositório:

Nome do Banco Carteiras Suportadas Testada/Homologada no banco
Banco do Brasil 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. Esperando Contribuição
Banrisul 00, 08. Esperando Contribuição
Bradesco 03, 06, 09, 19, 21, 22. Esperando Contribuição
Caixa 14, 24. Esperando Contribuição
HSBC CNR. Esperando Contribuição
Itaú 107, 109, 122, 142, 143, 126, 174, 175, 196, 198, 131, 146, 150, 168. Esperando Contribuição
Real 00, 20, 31, 42, 47, 85. Esperando Contribuição
Santander 101, 102, 121. Esperando Contribuição
Sicoob 1, 9. Esperando Contribuição
Sicredi 03, C. Esperando Contribuição

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

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:

boleto_itau = BoletoItau.new do |boleto|
  boleto.conta_corrente        = '89755'
  boleto.agencia               = '0097'
  boleto.carteira              = '198'
  boleto.cedente               = 'Razao Social da Empresa'
  boleto.codigo_cedente        = '90901'
  boleto.endereco_cedente      = 'Rua nome da rua, 9999'
  boleto.numero_documento      = '12345678'
  boleto.sacado                = 'Nome do Sacado'
  boleto.documento_sacado      = '35433793990'
  boleto.data_vencimento       = Date.tomorrow
  boleto.valor_documento       = 31678.99
  boleto.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

Formatos (HTML, PDF e PNG)

Objetivos para as próximas versões: criar os formatos dos boletos de:

  • HTML
  • PDF
  • PNG

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 do boleto.

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!)