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, permitam-me 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 := 0 to FCount-1 do i begin PropName := Properties^[i].Name; opInfo := Get pI o(DestComp.ClassInfo, PropName);Pr Pro nf 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 (SourcePropObjectnil) and (DestPropObjectnil)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, adicion-los 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