Gerador de Boleto Bancário (Flex)

TOTVS IP
28/04/2017
 Gerador Boleto Bancário (Flex) TOTVS IP

Sumário
1 INFORMAÇÕES E OBJETIVOS ......................................................................................................................................... 3
2 PRINCIPAIS RECURSOS ................................................................................................................................................ 3
3 INSTALAÇÃO .............................................................................................................................................................. 4
3.1 COMPOSIÇÃO DO PACOTE DE INSTALAÇÃO ................................................................................................................. 4
3.2 APLICAÇÃO DO UPDATE .......................................................................................................................................... 6
3.3 CONFIGURAÇÃO DOS MENUS DE USUÁRIOS ............................................................................................................. 10
4 ROTINAS................................................................................................................................................................. 12
4.1 CONFIGURAÇÃO DE BOLETOS BANCÁRIOS ................................................................................................................ 12
4.2 AMARRAÇÃO FILIAL X BOLETO ............................................................................................................................... 17
4.3 IMPRESSÃO DOS BOLETOS ..................................................................................................................................... 17
4.4 ENVIO DOS BOLETOS POR E-MAIL ............................................................................................................................ 19
4.5 MANUTENÇÃO DOS BOLETOS ................................................................................................................................ 21
5 CÓDIGO DE BARRAS, LINHA DIGITÁVEL E NOSSO NÚMERO ............................................................................................. 22
5.1 COMPOSIÇÃO DO CÓDIGO DE BARRAS ..................................................................................................................... 22
5.2 REPRESENTAÇÃO NUMÉRICA DO CÓDIGO DE BARRAS ( LINHA DIGITÁVEL ) .................................................................... 22
5.3 NOSSO NÚMERO ................................................................................................................................................. 23

2
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

1 Informações e objetivos

Nome Gerador de Boletos Bancários (Flex) TOTVS IP

Linha Protheus
O Acelerador de Manutenção de Boletos Bancários para o Protheus foi desenvolvido com o objetivo
de possibilitar a configuração de diversos boletos, de bancos distintos, sem a necessidade de edição
de códigos-fontes Advpl. Para tal, a concepção do acelerador foi baseada no recurso de macro-
Objetivos
substituição provido pela linguagem Advpl, onde é possível converter uma string em um comando da
linguagem. Esse recurso é muito utilizado no ERP Protheus, como por exemplo, nos Lançamentos
Padrões do módulo de Contabilidade.
Concepção FSW CPS -
FSW CPS -
Elaborado por
Carlos Eduardo Niemeyer Rodrigues carlos.niemeyer@totvs.com.br
Versão 2.56
Data 28/04/2017

2 Principais Recursos
 Configuração via interface de usuário;

 Os códigos fontes não possuem nenhum “If Banco”, ou seja, toda a inteligência de cada banco é configurável. Essa
característica permite que seja possível configurar diversos bancos sem precisar alterar nada nos códigos fontes;

 Amarração de Filiais x Boletos, possibilitando ao Gestor Financeiro controlar o envio de boletos para diversos Bancos
sem a necessidade de interferência direta por parte dos usuários que realizam a Geração/Impressão;

 Rotina de Manutenção, possibilitando a Exclusão, Re-Impressão e Restauração dos Boletos;

 Envio de boletos por e-mail;

 Instalação do Acelerador configurando as Tabelas a serem utilizadas;

 Execução de Macro Substituição de forma segura, apresentando o erro na fórmula ADVPL sem finalizar a aplicação

 Bancos Homologados:
 Banrisul (041) - Nº Seq. de 8 Dígitos – Nosso Número de 8 Dígitos + 2 Dígitos DV
 Banco do Brasil (001) - Carteira 01, 17 e 18 - Conv. 6 Dígitos (Nº Seq. De 5 Dígitos) - Nosso Número com
11 Dígitos + DV
 Banco do Brasil (001) - Carteira 01, 17 e 18 - Conv. 7 Dígitos - Nosso Número com 17 Dígitos + DV
 Banco Bradesco (237) - Carteira 2 Dígitos - Nosso Número 11 dígitos + DV
 Banco CEF (104) - Carteira 14 / 24 – Nosso Número 17 dígitos + DV (SIGCB)
 Banco CEF (104) - CEF Rápida - Carteira CR (12/14) - Nosso número 10 dígitos + DV
 Banco HSBC (399) - Carteira CSB - Nosso Número 10 dígitos + DV)
 Banco Itaú (341) - Carteira 110 – Nosso Número 8 Dígitos + DV
 Banco Santander (033) - CNAB 200 – Nº Seq. de 12 Dígitos) – Carteira 101 (RCR), 102 (CSR) e 201 (Penhor
Rápida com Registro) – Nosso Número com 12 Dígitos + DV
 SICREDI (748) – Nosso Número com 5 Dígitos + DV

3
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

3 Instalação

3.1 Composição do Pacote de Instalação

O Pacote de Instalação do Acelerador possui os seguintes diretórios/arquivos:

 Instalacao

Contém os arquivos a serem colocados na pasta “\protheus_data\boletos_totvsip\”:

o configuracoes: Armazena as Configurações de Boletos pré-definidas e arquivos XML e o Arquivo ConfigBancos.ini (

utilizado para preenchimento automático do digito verificador dos Códigos dos Bancos )

o email: Controle de envio de e-mail. Possui também o arquivo email_boletos.html para personalização do corpo dos
e-mails.

o logotipos: Arquivos no formato bitmap dos logotipos dos bancos.

 patches: Patches contendo os programas-fonte Advpl utilizados pelo Acelerador para Protheus 11 e Protheus 12,
divididos patches do Acelerador e Patches dos pontos de entrada (PE) padrões do Protheus usados pelo Acelerador (No
Kit acompanha os fontes desses PEs para possíveis customizações). Entretanto, para correto funcionamento do
Acelerador é necessário aplicar os patches do componente LibTOTVSIP e do Componente IPLicense, disponíveis em
seus respectivos Kits de Entrega, a parte, pois possuem evoluções separadas do Acelerador.

 funções_aux: Funções Auxiliares para integração com o Acelerador

 menus: Arquivo XNU contendo as configurações de Menus do Acelerador para rápida implantação
 Pontos de Entrada Padrões Usados: Fontes com sugestões de Pontos de Entrada de rotinas padrões para integração
com o Acelerador. Em Patches pode ser encontrado o patches dos pontos de entrada para fácil aplicação no ambiente.

IMPORTANTE:

4
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

O ACELERADOR NÃO SUPORTA AMBIENTES PROTHEUS SEM BANCO DE

DADOS RELACIONAL.

5
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

Criação do Diretório do Acelerador

O Acelerador irá acessar a pasta boletos_totvsip que deverá ser copiada abaixo do RootPath ( protheus_data ) do Protheus,
conforme exemplo abaixo:

3.2 Aplicação do Update

Após a aplicação do patch do Acelerador (P11-tttp110-GeradorBoletos-2016-12-09V2.52 ou P12-tttp120-GeradorBoletos-
2016-12-09V2.52 ou versão superior), bem como dos componentes relacionados (IPLicense e LibTOTVSIP), executar via
Programa Inicial a função de compatibilização dos dicionários de dados u_UpdBolet(), conforme exemplo abaixo:

6
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

O sistema irá exibir o dialogo abaixo:

Após a confirmação, será necessário escolher as empresas para Instalação do Acelerador:

7
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

As definições das tabelas serão armazenadas em parâmetros personalizados do acelerador (ZZ_BLPACFG, ZZ_BLPAINS,
ZZ_BLPABAR, ZZ_BLPATAB, ZZ_BLPAFIL e ZZ_BLPABOL).

Ao término da Instalação um Log da Atualização será exibido.

Se os componentes IPLicense e LibTOTVSIP não estiverem aplicados serão registrados erros no log do AppServer onde o
SmartClient do Protheus está sendo executado (console.log na pasta \bin\appserver\). Para ambientes Cloud verifique se o
AppServer está configurado para gerar Logs , pois pode estar desabilitado.

8
Versão 2.56
Gerador Boleto Bancário (Flex) TOTVS IP

9
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

3.3 Configuração dos Menus de Usuários

Após conclusão da atualização um log apresentado com os parâmetros processados.

As seguintes rotinas podem ser acessadas via Menus de Usuário:

Configuração dos Boletos ( Função de Usuário MANCFGBOL )

10
Versão 2.56
Gerador Boleto Bancário (Flex) TOTVS IP

Amarração Filiais x Boletos ( Função de Usuário FILIAISBOL )

Impressão dos Boletos ( Função de Usuário IMPRIMEBOL )

Manutenção dos Boletos ( Função de Usuário MANBOLETOS )

11
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

Sugere-se a criação de um grupo Boletos Bancarios no módulo Financeiro ( SIGAFIN.xnu ) abaixo da pasta Atualizações,
conforme abaixo:

4 Rotinas

4.1 Configuração de Boletos Bancários

Através da rotina de Configuração de Boletos Bancários é possível definir as particularidades de cada banco.
Todos os campos impressos no boleto são definidos através de fórmulas Advpl.
O objeto do Boleto (oBol) possui um método getValue() que deve ser usado para recuperar o conteúdo de um campo das tabelas
nativas do acelerador (ZB1 a ZB6) e caso sejam alteradas na instalação para usar outras tabelas o método terá a inteligência de
buscar o conteúdo na tabela correta mesmo que o prefixo do nome do campo não seja alterado nas configurações do boleto,
possibilitando reaproveitar as configurações em XML dos bancos sem a necessidade de modificar os campos no código ADVPL.

CONTA BANCÁRIA

Definição dos dados da Conta Bancária cadastrada no Protheus. Será necessário ter um Parâmetro de Bancos (Tabela SEE)
cadastrado para relacionamento.

12
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

CAMPOS DO BOLETO

Definição dos Campos a serem Impressos no Boleto através de Fórmulas Advpl.

LOGOTIPO

Definição do Logotipo a ser Impresso no Boleto

13
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

IMPRESSÃO DO CÓDIGO DE BARRAS

Definição da Impressão do Código de Barras

OUTRAS CONFIGURAÇÕES

Definição de Configurações Adicionais.

Imp. Titulos: Fórmula para Validação da Geração de um Boleto para um Título. Caso nenhum valor for informado nesse campo a
rotina irá apenas consistir o Portador vinculado ao Título.

Grv. N. Num: Fórmula para Gravação do Nosso Número no campo E1_NUMBCO. Se não informado nenhum valor ira gravar
apenas o Sequencial utilizado para geração do Nosso Número ( campo EE_FAXATU da Tabela SEE- Parâmetros Bancários ).

Imp Dv N Num: Indica se o digito do Nosso Número será impresso.

Imp Vlr Cobr: Indica se o campo Valor Cobrado será impresso.

Imp Num Bco: Código do Banco na câmara de compensação caso seja diferente do código do Banco da Conta Bancária (casos
de bancos correspondentes). Se não informado assume o Código e o Digito do Banco informados na pasta Conta Bancária.

14
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

INSTRUÇÕES DE COBRANÇA

Definição das Instruções de Cobrança. Cada linha do getdados corresponde a sequencia de linhas a serem impressas.

CAMPO L IVRE DO CÓDIGO DE BARRAS

Definição do Campo Livre do Código de Barras. Essa opção será detalhada no tópico 4.1 desse manual.

15
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

TABELAS POSICIONADAS

Definição de Posicionamento de Tabelas para utilização nas Fórmulas da Configuração

IMPORTAÇÃO / EXPORTAÇÃO DE CONFIGURAÇÕES

As Configurações de Boletos podem ser Exportadas e Importadas através de Arquivos XML

Nota: A partir da versão 2.50 do Boleto foi criado o método ::getValue() no objeto do boleto, podendo ser usado em
substituição ao Alias e nome do campo para as tabelas do Boleto, criado para flexibilizar o uso das tabelas sem a
necessidade de mudar os nomes originais das tabelas do boleto. Entretanto, o uso do Alias->Campo também pode ser
utilizado, mas no Kit de Entrega os modelos XML estarão utilizando o novo método.

Exemplo:
ZB1->ZB1_VALOR => oBol:getValue(“ZB1_VALOR”)

16
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

4.2 Amarração Filial x Boleto

 Possibilita a definição de uma Configuração de Boleto para uma Filial do Protheus. Através dessa definição a rotina
de Impressão/Geração dos Boletos passa a sugerir automaticamente a Configuração.

4.3 Impressão dos Boletos

17
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

 Através da Informação de Parâmetros, permite selecionar os Títulos para Geração/Impressão dos Boletos Bancários

 Para personalização do Layout dos Boletos é possível criar o parâmetro ZZ_IMPBOL. Esse parâmetro deve
armazenar o nome da User Function a ser chamada para impressão dos boletos.

 Exemplo de conteúdo do parâmetro: u_MyImpBol(oBol)

 Note que o objeto oBol , que é uma instância da classe BoletosProtheus referente ao acelerador, está disponível para
uso.

18
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

4.4 Envio dos boletos por e-mail

Ao selecionar a opção E-mail a rotina irá disparar e-mails para os clientes com os boletos em anexo.

Os boletos serão agrupados por e-mail caso seja selecionado mais de um título para o mesmo cliente.

Por padrão os e-mails serão enviados para o e-mail cadastrado junto ao cliente (campo A1_EMAIL). Caso necessário, a
ferramenta dispõe do Ponto de Entrada BOLPEMAIL para personalização do destinatário de e-mail dos clientes. O PE será
chamado uma vez para cada título selecionado. As tabelas SE1 (Título a Receber) e SA1 (Clientes) estarão posicionadas de
acordo com o título que estiver sendo processado. O PE deve retornar uma string com o e-mail para envio do Título em questão.

O Ponto de Entrada BOLPEENVOK pode ser usado para realizar alguma ação após o envio dos e-mails. Esse PE recebe como
parâmetro um array com os Títulos enviados, onde:

aTitulos[nI,1] = Prefixo
aTitulos[nI,2] = Número
aTitulos[nI,3] = Parcela
aTitulos[nI,4] = Tipo

Sintaxe: u_BolPeEnvOk(aTitulos)

O Ponto de Entrada BOLPEHTML pode ser usado para modificar o HTML de Envio dos E-mail. A função deve retornar uma String
com o arquivo a ser anexado para cada título selecionado para envio do e-mail. Esse arquivo deve estar abaixo do rootpath do
Protheus.

Sintaxe: u_BolPeHtml(cPrefixo, cNumero, cParcela, cTipo)

O corpo da mensagem dos e-mails pode ser alterado editando o arquivo \boletos_totvsip\email\email_boletos.html

19
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

Para personalização do layout com macros, utilize o PE BOLPELAYOUT. Esse PE passa como parâmetro o objeto de
manipulação de e-mails e um array com os títulos que estão sendo enviados. Sintaxe: u_BolPeLayout(oMail, aTitulos)

Para alterar uma variável do layout utilize o método setValue() do objeto oMail.

Exemplo:

oMai:setValue(“sua_variavel“, xValor)
oMail:addTableValue(“suatabela.coluna“, xValor)

A variável %nomeEmpresa% será preenchida automaticamente de acordo com a Empresa/Filial que o usuário estiver utilizando o
campo M0_NOMECOM.

Nota: Para maiores informações consulte a documentações gerada com ProtheusDoc.

20
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

4.5 Manutenção dos Boletos

Atualizar: Atualiza a Tabela de Boletos Gerados ( ZB6 ) de acordo com a Tabela de Títulos a
Receber ( SE1 )

Re-Imprimir: Re-Impressão dos Boletos

E-mail: Envio dos Boletos por e-mail

Excluir: Exclusão de Boletos Individualmente ou por Borderôs

Restaurar: Restauração de Boletos Individualmente ou por Borderôs.

RESTAURAÇÃO DOS BOLETOS

A opção de Restauração dos Boletos foi desenvolvida porque eventualmente alguma rotina padrão pode limpar dados dos boletos
da tabela SE1 (Títulos a Receber) tornando, dessa forma, os boletos gerados inconsistentes. O kit de entrega da ferramenta
dispõe de algumas sugestões de Pontos de Entradas (Fontes e Patch em avulso) para Restauração Automática dos Boletos em
alguns eventos de rotinas padrões:

IMPORTANTE : OS PONTOS DE ENTRADA DEVEM SER HOMOLOGADOS ANTES DA COMPILAÇÃO EM AMBIENTES DE PRODUÇÃO .
VERIFIQUE TAMBÉM SE O CLIENTE JÁ NÃO POSSUI ALGUM PE COMPILADO .

21
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

5 Código de Barras, Linha Digitável e Nosso Número

5.1 Composição do Código de Barras

O Código de Barras de Boletos Bancários é composto por dois campos:

a) Campo obrigatório: determinado pelo BACEN e comum a todos os bancos;

b) Campo livre: determinado por cada banco de acordo com a modalidade de Cobrança utilizada pelo cliente;

Deve conter 44 posições, disposto da seguinte forma:

Posição Tamanho Picture Conteúdo
01 a 03 03 9(03) Código do Banco na Câmara de Compensação = '001'
04 a 04 01 9(01) Código da Moeda = 9 (Real)
05 a 05 01 9(01) Digito Verificador (DV) do código de Barras
06 a 09 04 9(04) Fator de Vencimento
10 a 19 10 9(08)V(2) Valor
20 a 44 03 9(03) Campo Livre

O acelerador exposto nesse manual permite a configuração dos campos livres de cada banco.

As demais informações, por serem comuns a todos os bancos, são fixas dentro dos códigos fontes.

5.2 Representação Numérica do Código de Barras ( Linha Digitável )

A representação numérica do código de barras é distribuída em 5 partes, sendo os 3 primeiros consistidos por DV (Módulo 10) e,
entre cada campo, espaço equivalente a uma posição. No quarto campo é indicado, isoladamente, o DV (Módulo 11) do código de
barras:

AAABC.CCCCX DDDDD.EEEEEY FFFFF.GGGGGZ K UUUUVVVVVVVVVV

Campo 1 Campo 2 Campo 3 4 Campo 5

a) Campo 1: AAABC.CCCCX
AAA = Código do banco na Compensação
B = Código da moeda ( sempre 9 – Real )
CCCCC = Posições 20 a 24 do código de barras
X = DV do Campo 1 ( Módulo 10 )
b) Campo 2: DDDDD.EEEEEY
DDDDD = Posições 25 a 29 do código de barras
EEEE = Posições 30 a 34 do código de barras
Y = DV do Campo 2 (Módulo 10)
c) Campo 3: FFFFF.GGGGGZ
FFFFF = Posições 35 a 39 do código de barras
GGGG = Posições 40 a 44 do código de barras
Z = DV do Campo 3 (Módulo 10)
d) Campo 4: K
K = DV do código de barras (Módulo 11)
e) Campo 5: UUUUVVVVVVVVVV
UUUU = Fator de Vencimento
VVVVVVVVVV = Valor do título (com duas casas decimais, sem ponto e vírgula. Em caso de utilização de
moeda variável, informar zeros).

22
Versão 2.56
 Gerador Boleto Bancário (Flex) TOTVS IP

No acelerador a composição da Linha Digitável é tratada automaticamente baseando-se nas fórmulas para montagem do Código
de Barras.

5.3 Nosso Número

O Nosso Número dos Boletos Bancários é o código e controle pelo qual o Banco e o cliente identificam os dados da cobrança que
deu origem ao boleto. Cada banco determina como esse campo será montado.

Um ponto a ser destacado é o Cálculo do Dígito Verificador do Nosso Número.

Para atender as particularidades de cada banco, o acelerador faz uso do método getMod11 da Classe utilizada para
gerenciamento da Impressão/Manutenção dos Boletos.

Abaixo a documentação do Método getMod11 (Para os demais método vide Documentação ProtheusDoc que acompanha o Kit de
entrega do Acelerador):

Exemplo de utilização para Cálculo do DV do Nosso Número do Banco do Brasil:

oBol:GetMod11(&(ZB1->ZB1_NOSSON), 9, 9, .F., .T., {10}, "X")

Exemplo de utilização para Cálculo do DV do Nosso Número do Bradesco:

oBol:GetMod11(AllTrim(ZB1->&ZB1_CARTEI)+Right(oBol:GetNumeroBanco(), 11), 7, 2, .T., .F., {10,11}, {"P","0"})

23
Versão 2.56