KillBill
========

Cria boleto com código de barras, usando o prawn (https://github.com/sandal/prawn/tree)
e o barby (https://github.com/toretore/barby/tree).

Baseado e inclusive muitos métodos copiados por inteiro do
acts_as_payment (http://github.com/kivanio/acts_as_payment/tree). O
autor original é Kivanio
(http://www.kivanio.com.br/home/post/58-plugin-para-pagamentos-actsaspayment.html)

Para execução, necessita das Gems instaladas:

prawn = (0.8.4)
prawn-layout = (0.8.4)
prawn-security = (0.8.4)
prawn-fast-png = (0.2.1)
barby = (0.3.2)
rmagick = (2.9.1)

Além disso, instale o ImageMagick na sua máquina. Se você usar o Ubuntu:

$ sudo aptitude install imagemagick libmagick9-dev

Para testes necessita das Gems instaladas:

rspec = (1.3.0)

Nota: O RMagick é uma necessidade do prawn-fast-png e ajuda a aumentar a
velocidade de renderização de arquivos PNG que contém transparência. A leitura
do AlphaChannel do PNG em Ruby puro estava muito lenta.

Usando
======

Vamos supor que eu tenha um _controller_ Billing e que a _action_ show desse
_controller_ exibe o boleto no padrão Itau. Para fins de exemplo, consideramos
que o modelo Billing possui um método de instância to_bill que possui todos
os campos necessários ao preenchimento do boleto no formato do Itaú.

A action ficaria então assim:

def show
 @billing = Billing.find params[:id]
 @boleto = Riopro::KillBill::Bank::Itau.new(@billing.to_bill)
 send_data @boleto.to_pdf, 
  :filename => "boleto_itau.pdf", 
  :type => "application/pdf"
end


No meu modelo Billing, o método to_bill seria assim

  def to_bill
    {
      :bank => self.bank,
      :our_number => self.our_number,
      :agency => self.agency,
      :account => self.account,
      :value => self.value,
      :due_on => self.due_on,
      :transferor => self.transferor,
      :quantity => 1,
      :document_number => self.invoice.id,
      :processed_at => self.created_at.to_date,
      :drawee => { 
        :name => self.user.name,
        :address1 => self.address,
        :address2 => self.address_complement
      },
      :instructions => self.instructions
    }
  end

Exemplo
=======

Os exemplos estão na pasta examples. Para usá-los, você precisa estar com as
gems instaladas e executar o exemplo desejado. O exemplo:

$ ruby examples/boleto_itau_examples.rb

Vai criar no diretório raiz um arquivo boleto_itau.pdf


Adicionando novos bancos ao KillBill
=================================================

Para entender melhor como incorporar o seu banco ao KillBill, comece olhando o 
arquivo lib/bank/itau.rb.

De cara você verá que o mesmo herda de Riopro::KillBill::Bank::Base. A classe 
base faz todas as instanciações padrão e contém os métodos mais comuns a todos
os bancos (como cálculo dos digitos verificadores do tipo 10 e 11).

Em seguida colocamos attr_accessor para cada campo que for específico do nosso
banco. No caso do itaú, são os campos :cpf_or_cnpj e :descriptions.

Em seguida temos o método initialize, onde instanciamos atributos para esse banco
(como o número e o nome do banco). É importante chamar self.process_options(options)
ao final do initialize para que o banco possa receber opções de inicialização através
de um hash.

O próximo método importante que varia de banco para banco é build_barcode. Cada 
banco determina como será a ordem de campos (e até mesmo quais são eles) para
o código de barras. Os 3 primeiros campos são fixos porém: 

#{self.bank_number}#{self.currency}#{verifyer_cd}

O primeiro é o número do banco 001 (banco do brasil), 341 (itaú),... O segundo é
a moeda de pagamento do boleto. Normalmente a forma de pagamento é em Reais, que
possui um id fixo entre os bancos = 9. Mas poderia ser dólar ou euro, ou se o país mudasse
de moeda para Reais Novos por exemplo, esse número mudaria.

O terceiro campo onipresente é o que calcula o dígito verificador para esse código
de barras. Mas essa forma de calcular vária de banco para banco. O que é fixo é
a posição.

Sem entrar muito em detalhes, o próximo passo é criar a imagem de fundo para o
seu boleto (com o logo do banco e todos os campos no alinhamento correto). Você pode
tomar como base o nosso arquivo do Gimp lib/images/bank_source.xcf e usá-lo
para gerar a sua imagem de background do boleto do seu banco. O importante é que
convencionamos que a imagem de fundo do boleto será chamada lib/images/nome_do_banco.jpg
Importante que nome_do_banco deve estar em minúsculo. Isso ajudará na padronização.

Em seguida, faça seus métodos pdf_parameters, to_pdf e to_pdf_file que fazem a 
renderização do boleto propriamente dita.


Melhorias desejadas e Roadmap
=============================

Seria importante que os métodos to_pdf e to_pdf_file chamassem um método
valid! que validaria se os campos estão corretos antes de tentar criar o pdf.

Isso porque acreditamos que um boleto só deve ser gerado se ele puder ser gerado.
Ou seja, se um campo obrigatório não foi preenchido (como o sacado por exemplo),
deve ser obrigatorio que a biblioteca levante um erro informando que atributo 
exatamente não foi preenchido ou foi preenchido incorretamente.

O objetivo agora é acrescentar o maior número possível de bancos, sem desvirtuar
o conceito de simplicidade do KillBill.

consulte também o arquivo CHANGELOG para ver as modificações em cada versão.

Bancos Suportados e Comentários
===============================

Atualmente, o KillBill suporta os seguintes bancos:

* Itaú - tanto para geração de boleto quanto para tratamento de arquivo
    de retorno;
* Bradesco - tanto para geração de boleto quanto para tratamento de arquivo
    de retorno, apenas registros de transação Tipo 1. Ou seja, não suporta
    os registros de rateio entre empresas;


Agradecimentos
=============================
* Kivanio Pereira Barbosa (kivanio at gmail dot com) pela troca de idéias e pela
criação do acts_as_payment, no qual o KillBill se baseou inicialmente.

* Felipe Cruxen Godinho (felipecruxen at turboseg dot com dot br) por parte do
código para implementar os boletos do banco Bradesco.

Copyright (c) 2008 Riopro Informática Ltda, released under the MIT license