================================================================================

DELPHI-BOLETO
Pacote de componentes para cobrana bancria em Delphi (gerao de boletos bancrios completos incluindo cdigo de barras, gerao de arquivo remessa e processamento de arquivo retorno)

Verso atual: 2.1

================================================================================

AUTOR ORIGINAL DO PACOTE DE COMPONENTES DELPHI-BOLETO
Autor : Genilton Barbosa
E-mail: genilton@hotmail.com
Site  : www.gbimoveis.com/genilton

================================================================================

NDICE

1. Descrio
2. Licena
3. Instalao
4. Componentes
   4.1 TgbTitulo
   4.2 TgbCobranca
5. Classes auxiliares
   5.1 TgbCobCodBar
   5.2 TgbEndereco
   5.3 TgbBanco
   5.4 TgbContaBancaria
   5.5 TgbPessoa
   5.6 TgbCedente
   5.7 TgbTituloList
6. Como incluir novos bancos
7. Tarefas que ainda precisam ser iniciadas, melhoradas ou completadas
8. Histrico do desenvolvimento do pacote Delphi-Boleto
================================================================================

1. DESCRIO

O Delphi-Boleto  composto por 2 componentes:

1.1 TGBTITULO:
a - Imprime boleto bancrio (incluindo cdigo de barras) para diversos bancos (usa o QuickReport);
b - Gera imagem completa do boleto (TImage);
c - Envia imagem do boleto por e-mail (usa o componente TNMSMTP);
d - Gera imagem da Ficha de Compensao - TImage (aquela parte que tem o cdigo de barras). Nesse caso, voc pode criar um relatrio incluindo os dados da cobrana e incluir a Ficha de Compensao no rodap do relatrio. Algo parecido com o que  feito com as contas de telefone, por exemplo.
 
1.2 TGBCOBRANCA:
a - Gera arquivo remessa para o banco (Suponha um componente gbCobranca1 do tipo TgbCobranca. Voc l o seu banco de dados e atribui o valor de cada cobrana a um componente TgbTitulo - Ex.: gbTitulo1. Depois, usa gbCobranca1.Titulos.Add(gbTitulo1) para inserir o ttulo na coleo. Para terminar, voc usa gbCobranca1.GerarRemessa);
b - L arquivo retorno - recebido do banco (gbCobranca1.LerRetorno). Depois, para cada titulo da coleo TgbCobranca, voc procura o NossoNumero no banco de dados (gbCobranca1.Titulos[i].NossoNumero) e atribui aos campos do banco de dados os valores informados pelo banco: descontos, acrscimos, juros, data do recebimento, etc... (gbCobranca1.Titulos[i].ValorDescontos, gbCobranca1.Titulos[i].ValorAcrescimos ....)

================================================================================

2. LICENA:

Este componente foi desenvolvido por GENILTON BARBOSA (www.gbimoveis.com/genilton) e  aperfeioado com apoio dos membros do grupo DELPHI-BOLETO. O grupo DELPHI-BOLETO foi criado e  coordenado por Genilton Barbosa.
O componente  open source e voc poder alter-lo e distribu-lo livremente desde que inclua na distribuio o texto integral desta licena, sem alteraes.
Para contribuir com a comunidade Open Source e com o grupo Delphi-Boleto em particular, peo que todas as contribuies (sugestes, alteraes no cdigo, etc...) sejam enviadas para o grupo Delphi-Boleto.
Inscreva-se gratuitamente no grupo Delphi-Boleto e voc ter acesso a todas as verses atualizadas dos componentes, alm de poder contribuir para o aperfeioamento dos componentes e participar da nossa lista de discusso sobre eles. Para se cadastrar no grupo, visite o site www.gbimoveis.com/genilton.

================================================================================

3. INSTALAO

2.1. Descompacte o arquivo delphi_boleto_2_1.zip;
2.2. Usando o Delphi, abra o arquivo gbCobX.dpk, onde X  a verso do Delphi que voc usa (4, 5, 6 ou 7);
2.3. Clique na opo Compilar;
2.4. Clique na opo Instalar;
2.5. Adicione $DELPHI\Source\ToolsAPI no caminho de pesquisa do Delphi (menu Tools / Environment Options / Library / Search Path);
2.6. Antes de usar o programa de demonstrao que est no subdiretrio DEMO, voc dever criar o alias GBFINANCAS e apont-lo para o subdiretrio DEMO\DADOS.

Ser criada uma paleta chamada GBSOFT na barra de componentes do Delphi, com 2 componentes: TgbTitulo e TgbCobranca.

OBS.: O componente TgbCobranca (gera remessa e l retorno de cobrana) no est disponvel para Delphi 4.

================================================================================

4. COMPONENTES

4.1 TGBTITULO

Representa um ttulo e todas as rotinas associadas}

4.1.1 Propriedades

TipoOcorrencia : TTipoOcorrencia; {Indica o que dever ser feito com o ttulo: registrar, cancelar, baixa, etc...) 
MotivoRejeicaoComando : string; {Caso uma ocorrncia no seja aceita pelo bancos, aqui mostra qual foi o motivo)
LocalPagamento : string; {Local onde o ttulo dever ser pago. Ex.: 'Pagvel em qualquer banco at o vencimento'}
Cedente : TgbCedente; {Aquele que emitiu o ttulo}
Sacado  : TgbPessoa; {Cliente que dever pagar a conta}
SeuNumero, {Nmero que identifica o ttulo na empresa}
NossoNumero, {Nmero que identifica o ttulo no banco}
DigitoNossoNumero,
Carteira: string; {Carteira do ttulo, conforme informado pelo banco. Ex.: 175, SR}
AceiteDocumento : TAceiteDocumento;
DataProcessamento : {Data em que o ttulo foi impresso}
DataDocumento, {Data do documento que originou a cobrana (nota fiscal, etc...}
DataVencimento, {Data do vencimento do ttulo}
DataRecebimento, {Data em que o ttulo foi pago pelo sacado}
DataCredito : TDateTime; {Data em que o banco liberar o dinheiro para o cedente}
DataAbatimento : TDateTime; {Data mxima para conceder abatimentos ao sacado}
DataDesconto : TDateTime; {Data mxima para conceder desconto ao sacado}
DataMoraJuros : TDateTime; {Data a partir da qual sero cobrados juros}
DataProtesto : TDateTime; {Data em que o ttulo dever ser protestado}
DataBaixa : TDateTime; {Data em que o ttulo dever ser baixado (desativado))
ValorDocumento, {Valor do ttulo}
ValorDespesaCobranca : Currency; {Valor cobrado pelo banco para fazer a cobrana do ttulo}
Instrucoes : TStringList; {Informaes que sero includas na rea de instrues do boleto}
EmissaoBoleto : TEmissaoBoleto; {Indica quem dever imprimir / enviar o ttulo: cliente ou banco}
ImagemBoleto : TImage; {Imagem do boleto como seria impresso}
ImagemFichaCompensacao : TImage; {Imagem da Ficha de Compensao (parte do boleto que contm o cdigo de barras). Pode ser usada para gerao de boletos personalizados. Inclua os dados desejados no relatrio e coloque a imagem no rodap do relatrio}

{As propriedades abaixo sero preenchidas quando for feita a leitura do arquivo retorno recebido do banco e contero informaes fornecidas pelo banco}
ValorDespesaCobranca, {Valor que o banco cobrou pelo servio de cobrana}
ValorAbatimento, {Valor do abatimento concedido ao sacado}
ValorDesconto, {Valor do desconto concedido ao sacado}
ValorMoraJuros, {Valor dos juros / multa cobrados do sacado pelo banco}
ValorIOF, {Valor do Imposto sobre Operaes Financeiras}
ValorOutrasDespesas, {Valor de outras despesas cobradas pelo banco: protesto de ttulos, por exemplo}
ValorOutrosCreditos : Currency; {Outros acrscimos informados pelo banco e que sero includos no valor repassado ao cedente}

4.1.2 Mtodos

Create(AOwner: TComponent); {Cria uma nova instncia do componente}
Destroy; {Destri uma instncia do componente}
Assign(ATitulo: TgbTitulo); {Atribui os valores de um componente TgbTitulo a outro componente TgbTitulo. Ex.: gbTitulo2.Assign(gbTitulo1);
EnviarPorEMail(Host, LoginUsuario : string; Porta :integer; Assunto : string; Mensagem : TStringList); {Envia imagem do boleto como anexo de e-mail.}
   Host = nmero ou nome do servidor de e-mail. Ex.: '200.225.175.1' ou 'www.xyz.com.br'. 
   LoginUsuario = Login do usurio no servidor de e-mail. Ex.: 'joao';
   Porta = Porta do servidor utilizada para e-mail. Ex.: 25
   Assunto = Ttulo da mensagem. Ex.: 'Envio de boleto bancrio';
   Mensagem = Corpo da mensagem. Ex.: 'Estamos enviando anexo a cobrana referente  primeira parcela da assinatura da revista XYZ';
Visualizar; {Mostra na tela o boleto e permite imprimi-lo}
Imprimir; {Imprime o boleto}


4.2 TGBCOBRANCA

Representa um conjunto de ttulos que sero tratados juntos em alguma rotina. Por exemplo: processamento de arquivo retorno e gerao de arquivo remessa

4.2.1 Propriedades

NomeArquivo : string; {Nome do arquivo remessa ou retorno}
NumeroArquivo : integer; {Nmero seqencial do arquivo remessa ou retorno}
DataArquivo : TDateTime; {Data da gerao do arquivo remessa ou retorno}
LayoutArquivo : TLayoutArquivo; {Layout dos arquivos remessa/retorno: CNAB240, CNAB400...}
TipoMovimento : TTipoMovimento; {Tipo de movimento desejado: Remessa, Retorno ...};
Titulos : TgbTituloList; {Ttulos includos no arquivo remessa ou retorno}
Relatorio : TStringList; {Relatrio com os dados contidos no arquivo retorno, porm com formato mais apropriado para a leitura.}





4.2.2 Mtodos

Create(AOwner: TComponent); override;
Destroy; override;
LerRetorno : boolean;
GerarRemessa : boolean;

================================================================================

5 CLASSES AUXILIARES

5.1 TGBCOBCODBAR

Classe para gerar cdigo de barras para boletos.

5.1.1 Propriedades

Codigo, {Dgitos contidos no cdigo de barras}
LinhaDigitavel : string; {Dgitos da linha digitvel. Usada quando no se consegue ler o cdigo de barras}
Imagem    : TImage; {Imagem contendo o cdigo de barras propriamente dito}

5.1.2 Mtodos

Create;
Destroy;

5.2 TGBENDERECO

Representa o endereo de cedentes ou sacados

5.2.1 Propriedades

Rua,
Numero,
Complemento,
Bairro,
Cidade,
Estado,
CEP,
EMail : string;

5.2.2 Mtodos

Assign(AEndereco: TgbEndereco); {Atribui um objeto TgbEndereo a outro. Ex.: Endereco2.Assign(Endereco1);

5.3 TGBBANCO

Informaes sobre o banco

5.3.1 Propriedades

Codigo, {Cdigo do banco na cmara de compensao. Ex.: '341'}
Digito, {Dgito do cdigo do banco. Ex.: '7', no caso do banco '341-7'}
Nome   : string; {Nome do banco. Ex.: 'Banco Ita S.A'}

5.3.2 Mtodos

Assign(ABanco: TgbBanco); {Atribui um objeto TgbBanco a outro. Ex.: gbBanco2.Assign(gbBanco1);

5.4 TGBCONTABANCARIA

Dados da conta bancria de cedentes ou sacados

5.4.1 Propriedades

Banco : TgbBanco; {Banco onde a pessoa tem conta}
CodigoAgencia, {Cdigo da agncia}
DigitoAgencia, {Dgito verificador do nmero da agncia}
NumeroConta,   {Nmero da conta}
DigitoConta,   {Dgito verificador do nmero da conta}
NomeCliente : string; {Nome do cliente titular da conta}

5.4.2 Mtodos

Create; {Cria uma nova instncia de objeto TgbContaBancaria}
Destroy; {Destri uma instncia de TgbContaBancaria}
Assign(AContaBancaria: TgbContaBancaria); {Atribui um objeto TgbContaBancaria a outro. Ex.: gbContaBancaria2.Assign(gbContaBancaria1);

5.5 TGBPESSOA

Dados sobre os cedentes ou sacados

5.5.1 Propriedades

TipoInscricao, {'01' - CPF / '02' - CNPJ}
NumeroCPFCGC ,
Nome         : string;
Endereco     : TgbEndereco;
ContaBancaria: TgbContaBancaria;

5.5.2 Mtodos

Create;
Destroy;
Assign(APessoa: TgbPessoa);

5.6 TGBCEDENTE

Dados completos sobre o cedente - Classe derivada de TgbPessoa. Portanto, tem todos os mtodos e propriedades de TgbPessoa, alm dos listados abaixo.

5.6.1 Propriedades

CodigoCedente, {Cdigo que identifica o cedente junto ao banco. Em muitos casos,  igual o nmero da conta, mas nem sempre.}
DigitoCodigoCedente : string;

5.6.2 Mtodos

Assign(ACedente: TgbCedente);


5.7 TGBTITULOLIST

Coleo de objetos do tipo TgbTitulo - Classe descendente de TOjbectList

5.7.1 Propriedades

Items[Index : integer] : TgbTitulo; {Coleo de objetos do tipo TgbTitulo}

5.7.2 Mtodos

Create;
Add(ATitulo : TgbTitulo) : integer; {Insere um ttulo no final e retorna o ndice relativo  posio dele na coleo}
Remove(ATitulo : TgbTitulo): Integer; {Remove o ttulo ATitulo da coleo}
IndexOf(ATitulo : TgbTitulo): Integer; {Retorna o ndice do ttulo ATitulo na coleo}
FindInstanceOf(AClass: TClass; AExact: Boolean = True; AStartAt: Integer = 0): Integer;
Insert(Index: Integer; ATitulo : TgbTitulo); {Insere o ttulo ATitulo na posio especificada por Index}

================================================================================

6. COMO INCLUIR NOVOS BANCOS
As rotinas especficas de cada banco, esto includas em units chamadas GBCOBXXX.PAS, onde XXX  o cdigo do banco. Veja alguns exemplos de nomes de units de bancos:
GBCOB001.PAS - Banco 001 - Banco do Brasil
GBCOB237.PAS - Banco 237 - Bradesco
GBCOB341.PAS - Banco 341 - Banco Ita

Para incluir um novo banco, faa o seguinte:
6.1 Abra o pacote Delphi-boleto (arquivo GBCOB.BPR);
6.2 Copie uma das units de bancos existentes e salve com o nome apropriado para o novo banco (GBCOBXXX.PAS, onde XXX  o cdigo do novo banco). Use como modelo o arquivo GBCOB104.PAS (referente  Caixa Econmica Federal).
6.3 Faa as alteraes necessrias na unit, seguindo a documentao fornecida por cada banco (rotinas para calcular dgito do nosso nmero, layout do cdigo de barras, layouts dos arquivos remessa e retorno, etc...). Voc pode conseguir alguns desses documentos no site www.gbimoveis.com/genilton. Caso precise de alguma documentao que no se encontre no site, entre em contato com o banco em questo.
6.4 Abra o arquivo GBCOBRANCA.PAS, localize a seo IMPLEMENTATION e inclua o nome da unit do novo banco na clusula USES da seo IMPLEMENTATION. Vai ficar assim:
***************************************
Unit gbCobranca.pas
INTERFACE
...
USES...
...
IMPLEMENTATION
...
USES gbCob001, gbCob021, gbCob104...
...
***************************************
6.5 Compile o pacote Delphi-Boleto e corrija os erros detectados;
6.6 Faa cada um dos testes na ordem a seguir e, se detectar erros, corrija-os antes de passar para o prximo teste:
6.6.1 Imprima alguns boletos bancrios para o novo banco e faa uma anlise visual para ver se parecem estar corretos. Se possvel, compare com outros boletos que voc tenha em mos.
6.6.2 Teste a leitura do cdigo de barras em um caixa eletrnico ou pea ao gerente do seu banco para testar no caixa. Lembre-se de cancelar a operao antes de terminar.
6.6.4 Entregue os boletos ao gerente do banco para que ele envie ao departamento responsvel para testes completos. Eles testaro diversas coisas como leitura do cdigo de barras, os dados do cedente, linha digitvel, etc...
6.6.5 Pea para o banco gerar um arquivo retorno referente aos ttulos testados acima. Quando receber o arquivo retorno, teste a leitura dele para ver se est tudo certo. Talvez a forma mais simples de fazer isso seja usar a propriedade Relatrio, do componente TgbCobranca. Ela retorna uma lista de strings, apresentando o contedo do arquivo retorno em um formato mais agradvel para a leitura humana. Se voc quiser, pode salvar o contedo com a seguinte seqncia de comandos:
************************
gbCobranca1.LerRetorno(NomeArquivoRetorno); {NomeArquivoRetorno  o nome completo do arquivo de retorno que deve ser analisado. Ex: 'C:\COBRANCA\RETORNO.TXT')
gbCobranca1.Relatorio.SaveToFile(NomeArquivoRelatorio); {NomeArquivoRelatorio  o nome completo do arquivo onde ser gravado o texto do relatrio. Ex.: 'C:\COBRANCA\RELATORIO.TXT');
************************
6.6.6 Gere um arquivo remessa e envie ao banco para testes. Lembre-se de avisar ao banco que  apenas para teste. Se voc no avisar, talvez eles processem os ttulos, pensando que eles so pra valer. Dependendo do tipo de cobrana que voc vai usar, talvez no seja necessrio gerar arquivo remessa. Por exemplo, se voc vai usar cobrana simples, sem registro (os ttulos no ficam registrados no banco) e voc mesmo vai imprimir os boletos, voc no precisar gerar arquivo remessa.

================================================================================

7. TAREFAS QUE AINDA PRECISAM SER INICIADAS, MELHORADAS OU COMPLETADAS

A - Programa DEMO. Peguei um exemplo de programa de contas a receber que tinha desenvolvido para ilustrar o uso de TUPDATESQL e TACTION e aproveitei para a demonstrao dos componentes. Talvez esse no seja o programa demo mais apropriado. O ideal seria um programa usando TTABLE e que no tivesse nenhuma detalhe de programao que muitos programadores no esto acostumados a usar.

B - Talvez fosse conveniente no usar componentes de terceiros como o QuickReport e NMSMTP. Esses componentes esto sendo usados para imprimir o boleto e para envi-lo por e-mail. Isso pode algum problema com verses diferentes do Delphi (que tenham verses diferentes dos componentes ou que no tenham esses componentes)

C - Qualidade da imagem gerada. As propriedades que exibem imagens do boleto (TgbTitulo.Imagem e TgbTitulo.ImagemFichaCompensacao) usam a funo GetPage() do QuickReport. Porm, a qualidade da imagem  visivelmente inferior quela mostrada na tela. Eu imprimi alguns boletos usando TgbTitulo.Imprimir (usa QuickReport.Print), testei no banco Ita e a leitura do cdigo de barras foi aprovada. Eu gerei a imagem dos mesmos boletos usando TgbTitulo.Imagem (usa a funo Getpage do QuickReport), imprimi a imagem, qualidade ficou visivelmente inferior (parece problema de resoluo), testei no Banco Ita e NO CONSEGUIU ler o cdigo de barras. A imagem do boleto  usada no mtodo TgbTitulo.EnviarBoletoPorEmail e tambm na propriedade TgbTitulo.ImagemFichaCompensacao.

================================================================================

8. HISTRICO DO DESENVOLVIMENTO DO PACOTE DELPHI-BOLETO
--------------------------------------------------------------------------------
02/Junho/2003 - Genilton Barbosa - www.gbimoveis.com/genilton
Verso 2.1
   Disponibilizao de verso para Delphi 7
   Correo do clculo do dgito verificador para boletos do Banco do Brasil
--------------------------------------------------------------------------------
17/Novembro/2002 - Genilton Barbosa - www.gbimoveis.com/genilton
Verso 2.1 - Beta 3
   Pequenas correes
--------------------------------------------------------------------------------
13/Novembro/2002 - Genilton Barbosa - www.gbimoveis.com/genilton
Verso 2.1 - Beta 2
   Pequenas correes
--------------------------------------------------------------------------------
14/Maio/2002 - Genilton Barbosa - www.gbimoveis.com/genilton
Verso 2.0
   Acrscimo de propriedades em TgbTitulo (TipoOcorrencia, MotivoRejeicaoComando, EspecieDocumento, AceiteDocumento, EmissaoBoleto).
   Acrscimo de propriedades em TgbCobranca (LayoutArquivo, TipoMovimento).
   Correo de bugs.

--------------------------------------------------------------------------------

12/Abril/2002 - Genilton Barbosa - www.gbimoveis.com/genilton
Verso 2.0 beta
   Separao das rotinas especficas de cada banco em units diferentes, chamadas GBCOBXXX.PAS, onde XXX  o cdigo do banco.
Ex.:
GBCOB001.PAS - Banco 001 - Banco do Brasil
GBCOB237.PAS - Banco 237 - Bradesco
GBCOB341.PAS - Banco 341 - Banco Ita

--------------------------------------------------------------------------------

31/Outubro/2001 - Genilton Barbosa - www.gbimoveis.com/genilton
Verso 1.0
   Verso inicial do pacote de componentes Delphi-Boleto   

================================================================================

Genilton Barbosa
Criador do pacote de componentes Delphi-Boleto e criador / moderador do grupo Delphi-Boleto
genilton@hotmail.com
www.gbimoveis.com/genilton
