FreeBoleto

Imprima voc mesmo seus boletos bancrios

Autor: Carlos Henrique Cantu www.firebase.com.br freeboleto.sf.net
Artigo originalmente publicado na revista ActiveDelphi.

Ooohhh no!!! Mais um componente de boleto???? Calma! Antes de tudo, permitamme explicar o porqu de mais um componente de boleto para Delphi: Aps testar
diversos componentes disponveis na internet, constatei que cada um deles tinha um
problema que impedia ou dificultava o uso na forma que eu desejava.
O componente mais conhecido para essa finalidade o gbBoleto. No entanto, encontrei
dois problemas nele:
1. Dependncia interna para o gerador de relatrios QuickReport, que eu
felizmente no uso.
2. Aparentemente o projeto andava (ou ainda anda) meio abandonado e confuso.
Quando testei, percebi que a gerao dos boletos para alguns bancos estava fora
do padro ou simplesmente geravam dados inconsistentes.
Sendo assim, decidi criar eu mesmo um componente para gerao de boletos, que
atendesse minhas necessidades: fosse confivel, leve e com o mnimo de dependncias.
Assim, nasceu o FreeBoleto.
O principal objetivo desse artigo, alm de apresentar o componente aos leitores, de
atrair mais pessoas para o desenvolvimento de novas units para os bancos que ainda no
so suportados, pois o FreeBoleto um projeto de cdigo aberto, gratuito, e que
depende da colaborao dos desenvolvedores para evoluir.
O FreeBoleto, em sua verso atual, suporta a emisso de boletos para os seguintes
bancos:

Ita
NossaCaixa
Santander Banespa
Unibanco
Real
Bradesco
Caixa Federal
Banco do Brasil
Santander

Uma das grandes vantagens do FreeBoleto que o componente de gerao dos dados de
cobrana (TFreeBoleto) no depende de qualquer componente externo ou de geradores
de relatrios! O pacote oferece um segundo componente (TFreeBoletoImagem) que
permite a gerao da imagem do boleto para visualizao, impresso ou gravao (em
formato jpg). Gravar a imagem em jpg pode ser til para quem deseja enviar os boletos
por e-mail, ou mesmo em cgis para uso em servidores web.

Note que o FreeBoleto no gera, pelo menos por enquanto, arquivos de transao
padro CNAB. Isso poder ser implementado no futuro (conforme houver necessidade),
e provavelmente ser atravs de novas classes, independentes das atuais.

Licena de uso
1. O FreeBoleto pode ser distribudo e utilizado livremente com qualquer tipo de
projeto, comercial ou no.
2. Componentes derivados do cdigo do FreeBoleto no podem ser vendidos,
devem manter os crditos originais, e devem estar compatveis com essa licena.
3. Qualquer alterao ou melhoria no cdigo do FreeBoleto deve ser enviada ao
autor para ser avaliada e, se possvel, incorporada ao cdigo oficial do
componente.
4. A incluso do suporte de novos bancos ao FreeBoleto deve ser notificada ao
autor, enviando juntamente o cdigo da unit do banco em questo. A criao de
uma nova unit de suporte a um novo banco dever ser feita em conjunto com a
criao dos testes unitrios (DUNITs) necessrios para garantir o correto
funcionamento das rotinas.
5. O autor no se responsabiliza por qualquer dano ou qualquer outro tipo de
problema originado pela utilizao desse componente, se isentando de qualquer
responsabilidade sobre a utilizao do mesmo.

Instalando o FreeBoleto
A instalao do FreeBoleto muito fcil e rpida! A primeira coisa que deve ser feita
baixar o componente do site oficial: http://freeboleto.sourceforge.net/
Depois, basta abrir o arquivo DPK correspondente a sua verso do Delphi, compilar, e
instalar na palheta de componentes (ver figura 1). O FreeBoleto roda em qualquer
verso do Delphi (Win32) a partir do Delphi 7. O pacote atualmente traz os DPKs para
Delphi 7, Delphi 2005 e Delphi 2006. Apesar de nunca ter testado, acredito que o
componente compile tambm no Delphi 5 e no Delphi 2007, sem maiores problemas.

Figura 1. Componentes do FreeBoleto na palheta do Delphi 7

Vale mencionar que o componente TFreeBoleto - responsvel por gerar as informaes
de cobrana - no utiliza componentes visuais, portanto bastante provvel que ele
possa ser compilado e instalado no Kylix ou mesmo no Delphi for .Net.

Informaes bsicas sobre boletos

Para aqueles que no esto familiarizados com o tema, um boleto nada mais do que
um ttulo de cobrana, que pode ser emitido por voc (cedente) ou pelo prprio banco.
Para o banco (entidade financeira altamente lucrativa) poder processar corretamente
os pagamentos, necessrio que voc solicite ao seu gerente a ativao da cobrana

atravs de boletos nas contas correntes que desejar. Sero solicitadas algumas
informaes, entre elas se a carteira utilizada ser com ou sem registro. Carteiras com
registro so aquelas onde os ttulos so gerados (registrados) pelo banco, portanto o
banco sabe da existncia dos mesmos, e poder inclusive envi-los para protesto, caso
no sejam pagos at o vencimento e assim for instrudo. Carteiras sem registro so
aquelas onde o banco s toma conhecimento da existncia do boleto quando o mesmo
pago.
Todo boleto possui um campo (numrico inteiro) chamado Nosso Nmero. Esse campo
que identifica o boleto no banco e na empresa. O ideal que este nmero nunca se
repita, caso contrrio vai ser difcil identificar qual boleto foi pago.
Quando um boleto pago, o banco fornece uma relao dos ttulos que foram
liquidados, contendo o Nosso Numero, valor, data de baixa, etc. Com isso, voc poder
identificar facilmente os ttulos pagos.

Usando o FreeBoleto
A melhor forma de aprender a usar o FreeBoleto estudar o projeto de demonstrao
(demo.dpr) que acompanha o pacote (ver figura 2).

Figura 2. Tela inicial do programa de demonstrao do FreeBoleto

Os campos indicados com fundo vermelho so obrigatrios. Os campos com fundo
amarelo podem ou no ser obrigatrios, dependendo do banco para o qual est sendo

gerado o boleto. Por exemplo, o campo Modalidade da Conta s exigido nos

boletos da NossaCaixa. J o campo Convnio necessrio para o Banco do Brasil.
Infelizmente, os bancos no gostam de facilitar a vida dos programadores. Cada um
deles tem suas prprias necessidades e podem exigir informaes diferentes para gerar
os boletos. Felizmente, a maior parte das informaes comum entre os bancos.
Clicando no boto Gerar Dados, o cdigo apresentado na listagem 1 ser executado.
Basicamente, o cdigo associa as informaes digitadas nos edits s suas respectivas
propriedades no componente TFreeBoleto (no exemplo, chamado de B).
O mtodo LimparTudo reseta o componente para seu estado inicial. Como podemos
usar uma nica instncia do componente B para gerar diversos boletos, necessrio
reinici-lo antes de gerar um novo boleto, garantindo que as informaes anteriores
foram descartadas.
O mtodo Preparar deve ser chamado depois que as informaes necessrias para gerar
o boleto j foram atribudas ao componente. Esse mtodo que vai gerar a informao
da Linha Digitvel (propriedade LinhaDigitavel) e do Cdigo de Barras (propriedade
CodigoBarras). Ele tambm faz a checagem se todas as informaes essenciais para a
gerao do boleto para o banco em questo esto presentes e no formato/tamanho
esperado.
Diferente do que muita gente imagina, para pagar um boleto via Internet s necessrio
a informao da Linha Digitvel. Ou seja, s necessrio imprimir o boleto no papel
caso pretenda-se paga-lo diretamente nos bancos, ou nos caixas eletrnicos (com leitor
de cdigo de barras). A linha digitvel contm todas as informaes necessrias (ex:
valor, vencimento, Nosso Nmero, etc) para a correta identificao e baixa do ttulo pelo
banco.
Por fim, os dados gerados so inseridos no TMemo, para que possam ser visualizados
na tela.
procedure TForm1.Button1Click(Sender: TObject);
begin
B.LimparTudo;
B.Cedente.Agencia := edAgencia.text;
B.Cedente.CodigoBanco := edBanco.text;
B.Moeda := '9';
B.Cedente.Nome := edNomeCede.text;
B.DataDocumento := trunc(dtpEmissao.date);
B.Documento := edDocumento.text;
B.Vencimento := dtpVencimento.date;
b.Cedente.CodigoCedente := edCodCedente.text;
b.Valor := StrToFloat(edValor.Text);
b.NossoNumero := edNNum.text;
B.Cedente.ContaCorrente := edContaCorrente.text;
if edDigitoCC.text <> '' then
B.Cedente.DigitoContaCorrente := edDigitoCC.text[1];
B.carteira := edCarteira.text;
B.Cedente.Banco151.ModalidadeConta := edModeloCarteira.text;
B.Cedente.Banco001.Convenio := edConvenio.text;
with B.sacado do
begin

Nome := edSacado.text;
Endereco := edEndereco.text;
Bairro := edBairro.text;
Cep := edCep.text;
Estado := edUF.text;
Cidade := edCidade.text;
CNPJ_CPF := edCNPJ.text;
end;
B.preparar;
memo1.Lines.clear;
with memo1.lines do
begin
Add('AgenCodCedente:' + b.DadosGerados.AgencCodigoCedente);
Add('Nome Banco:' + b.DadosGerados.NomeDoBanco);
Add('Num. bancario:' + b.DadosGerados.NumeroBancario);
Add('Digitavel:' + b.DadosGerados.LinhaDigitavel);
Add('Barras:' + b.DadosGerados.CodigoBarras);
end;
end;

Listagem 1. Cdigo associado ao boto Gerar Dados

Aps gerar as informaes do boleto, podemos clicar no boto Adicionar Boleto, cujo
cdigo pode ser visto na listagem 2, e que basicamente cria um novo objeto do tipo
TFreeBoleto (chamado simplesmente de x) na memria, e copia as informaes do
objeto B para ele. A cpia feita atravs de uma rotina especial chamada
CloneProperties (ver Listagem 3). Essa rotina pode ser usada sempre que se desejar
copiar as propriedades de qualquer objeto para outro do mesmo tipo.
Aps feita a clonagem do componente B para o X, este ltimo adicionado
uma lista de boletos associada ao componente Img (do tipo TFreeBoletoImagem). O
componente Img responsvel por gerar a imagem grfica do boleto, possibilitando sua
visualizao, impresso ou gravao, bem como manter uma lista de boletos que
podero ser impressos de uma nica vez, ou visualizados na tela de preview. Agora voc
entendeu porque todo esse trabalho de clonar os componentes, afinal, eles devem
continuar existindo na memria para posterior impresso, at que no sejam mais
necessrios.
procedure TForm1.Button3Click(Sender: TObject);
var x:TFreeBoleto;
begin
x:=TFreeBoleto.create(nil);
CloneProperties(B,x);
Img.ListaBoletos.Add(x);
end;

Listagem 2. Cdigo associado ao boto Adicionar Boleto

procedure CloneProperties(SourceComp, DestComp: TObject);
var
Propinfo: PPropInfo;
Properties: PPropList;
FCount: Integer;
FSize: Integer;
i: Integer;
PropName: String;
SourcePropObject: TObject;
DestPropObject: TObject;

begin
FCount := GetPropList(SourceComp.ClassInfo, tkAny, nil);
FSize := FCount * SizeOf(Pointer);
GetMem(Properties, FSize);
GetPropList(SourceComp.ClassInfo, tkAny, Properties);
for i := 0 to FCount-1 do
begin
PropName := Properties^[i].Name;
PropInfo := GetPropInfo(DestComp.ClassInfo, PropName);
if (PropInfo = nil) or (UpperCase(PropName) = 'NAME') then
Continue;
case PropType(SourceComp, PropName) of
tkInteger,
tkWChar,
tkSet,
tkChar:
SetOrdProp(DestComp,PropName,GetOrdProp(SourceComp,PropName));
tkString,tkLString,tkWString:
SetStrProp(DestComp,PropName,GetStrProp(SourceComp,PropName));
tkEnumeration:
SetEnumProp(DestComp,PropName,GetEnumProp(SourceComp,PropName));
tkFloat:
SetFloatProp(DestComp,PropName,GetFloatProp(SourceComp,PropName));
tkClass:
begin
SourcePropObject := GetObjectProp(SourceComp,PropName);
DestPropObject := GetObjectProp(DestComp,PropName);
if (SourcePropObject<>nil) and (DestPropObject<>nil)and
(SourcePropObject.ClassType.ClassParent.ClassName='TPersistent') then
CloneProperties(SourcePropObject,DestPropObject)
else
SetObjectProp(DestComp,PropName,GetObjectProp(SourceComp,PropName));
end;
end;
end;
if Properties <> nil then FreeMem(Properties, FSize);
end;

Listagem 3. Cdigo para copiar as propriedades de um objeto para outro

Aps clicar no boto Adicionar Boleto, j possvel visualizar a imagem do boleto na
tela. Para isso, basta clicar no boto Preview de Boletos (ver figura 3). Atravs da
barra de navegao, podemos percorrer todos os boletos que tenham sido adicionados
lista, imprimi-los ou gravar suas imagens em arquivos.

Figura 3. Imagem do boleto sendo visualizada na tela

Sendo assim, repetindo os passos anteriores, podemos gerar diversos boletos, adicionlos a lista de boletos do componente Img, e depois visualiz-los na tela de preview. O
boto Gerar e Adicionar pode ser usado para simplificar a operao, fazendo a funo
do boto Gerar e Adicionar Boleto em um nico click.
O terceiro boto, Limpar lista, remove todos os componentes que foram adicionados

lista
de
boletos
do
componente
Img,
atravs
da
chamada
Img.ListaBoletos.Clear;

O componente Img (classe TBoletoImagem) possui uma propriedade do tipo boolean

chamada DestruirBoletos. Quando true, no momento em que a lista de boletos for
destruda (atravs da chamada ao mtodo clear), os boletos associados a lista sero
tambm destrudos, liberando portanto a memria consumida. Se estiver false, em
algum outro momento ser necessrio destruir os boletos para evitar os famosos (e
indesejveis) memory leaks.

Adicionando novos bancos

Se o seu banco preferido no faz parte da lista atual de bancos suportados pelo
FreeBoleto, est a a sua chance de contribuir para o projeto!
Criar uma nova unit para suportar um novo banco, do ponto de vista de programao,
no difcil. O pacote FreeBoleto j traz um modelo padro de unit (no arquivo
uFreeBoletoBASE.pas) que pode ser usada com base para gerar novas units para outros
bancos. Leia os comentrios do arquivo para entender como e o que deve ser feito. A
primeira tarefa solicitar ao banco o manual de cobrana, onde vai constar todas as

informaes para gerar o cdigo de barras e a linha digitvel no padro do banco em

questo.
Desabafo: At hoje, no encontrei um manual de cobrana que prestasse! So todos
mal escritos! Alguns apresentam inconsistncias onde os prprios exemplos
apresentados contradizem algumas informaes do prprio manual. Em suma, um
horror! Ligar no 0800 para tirar alguma dvida to catico quanto conversar com
algum que no fale a sua lngua.
Uma das preocupaes ao criar o projeto foi garantir que mudanas feitas por outros
usurios no quebrassem o cdigo j existente e testado. Para isso, criei alguns casos
de teste, tambm chamados de testes unitrios, ou DUnits. Eles executam as
principais rotinas dos componentes, e verificam se a informao retornada/gerada por
elas foi a esperada, ou seja, est corretada. Se algum fizer alguma alterao que altere
as informaes essenciais geradas, o teste vai quebrar, indicando que um possvel erro
foi detectado.
Sendo assim, peo que todos aqueles que criarem units para novos bancos, que criem
tambm os respectivos casos de teste. Quem nunca fez isso no perder mais que 10
minutos para estudar e entender o cdigo dos testes j existentes. realmente muito
simples! Apesar de ser uma tarefa sacal, garanto que um trabalho importante e que
pode poupar muitos problemas (e horas de debug) no futuro.
Depois, basta enviar o cdigo gerado para o meu e-mail, para que seja includo no
projeto e assim permita que outras pessoas se beneficiem das melhorias. Aqueles que se
tornarem colaboradores freqentes, podero ganhar direito de commit diretamente no
repositrio do SourceForge.
A unit uFreeBoleto.pas, que contm o cdigo base do principal componente
(TFreeBoleto), geralmente no precisa ser alterada, a no ser pela incluso da unit de
um novo banco na sua clusula uses.
Os boletos seguem um padro de formatao para o Cdigo de Barras e Linha
Digitvel, definido pela Febraban. No entanto, este padro possui um Campo Livre, que
usado pelos bancos para armazenar qualquer tipo de informao que lhes interesse.
As units responsveis pela gerao das informaes especficas de cada banco (Campo
Livre) so nomeadas seguindo o padro uFreeBancoXXX.pas, onde XXX o nmero
oficial do respectivo banco no Brasil (ex: Banco do Brasil = 001, Banespa = 033, etc).
Estas units tambm contem o cdigo de consistncia das informaes necessrias para
gerar o boleto, bem como as rotinas de formatao de alguns dados, seguindo o padro
de cada banco.

Suporte
Desculpe, eu no tenho condies para dar suporte aos usurios do FreeBoleto, seja ele
via e-mail ou qualquer outro mtodo.
Para isso, foi criada uma lista de discusso no YahooGroups, onde os usurios podero
trocar experincias e solucionar suas dvidas e possveis problemas, lembrando que o

suporte da lista voluntrio, portanto no reclame se sua dvida demorar a ser

respondida, pois os que esto ali ajudando o fazem por livre e espontnea vontade, sem
ganhar por isso. O endereo da lista http://br.groups.yahoo.com/group/freeboleto
No enviem dvidas para meu e-mail pessoal, pois elas sero ignoradas.

Concluso
Espero que esse artigo tenha sido til, e que voc tenha gostado do FreeBoleto.
Independente de decidir usar ou no o componente, o cdigo serve como uma boa base
para aqueles programadores que ainda no dominam alguns conceitos de orientao
objetos, como herana, etc.
A proposta do componente ser simples, leve, rpido, confivel e verstil. Como
qualquer projeto Open Source, ele depende da ajuda de todos para evoluir e crescer. E
que venham novos (e bons) desenvolvedores para o projeto ;-)
Up the Irons!
Carlos H. Cantu
www.firebase.com.br / www.warmboot.com.br
blog.firebase.com.br / freeboleto.sf.net
www.firebirdnews.org / www.firebirddevelopersday.com.br