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:
- Stella Caelum http://stella.caelum.com.br/
- 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/
- Gem de Boleto Bancário (essa gem) https://github.com/tomas-stefano/boleto_bancario
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
- 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!)