CashFlow

Módulo responsável por gerenciar o sistema fluxo financeiro do caixa da empresa.

Requisitos

Folhas de Cheque

1. Para as contas do tipo 'Conta Bancária' o sistema deve permitir que sejam cadastradas folhas de cheque. O usuário deve inserir a numeração da primeira e última folha e o sistema deve criar um objeto (CashFlowCheckVO) para cada uma das folhas de cheque.
2. Cada folha de cheque deve ter os seguintes estados:
   1. NEW: Estado inicial para as folhas de cheques recém criadas e ainda não utilizadas.
   2. EMITED: Estado que indica que a folha de cheque foi usada e deve estar associada ao pagamento de algum lançamento financeiro.
   3. COMPENSED: Este estado indica que a folha de cheque já foi compensado (Foi encontrado no extrato do banco durante a conciliação bancária).
   4. DISCARDED: Marca que a folha de cheque foi rasurada e descartada. Uma folha de cheque nesse estado nunca deve ser encontrada no Extrato do banco.
3. Cheques podem ser predatados, a data de predatado quando presente deve ser usada como a data de previsão que o saldo precisa estar na conta para planejamento financeiro.

Fundo Comprometido Quando um cheque é emitido para pagar uma conta (um lançamento financeiro), ele automaticamente é "dado baixa". Afinal, na prática o lançamento já foi pago e deixa de ser uma conta a pagar para ser uma conta paga. No entanto, enquanto o cheque não for compensado o dinheiro continuará aparecendo no extrato bancário como dinheiro. Mas para efeitos de previsão e simulação de saldo para planejamento na hora de pagar as contas é importante que o sistema saiba o quanto de cheques estão "voando" e com data para serem compensados.

Extrato Bancário

Contas bancárias costumam ter o extrato oferecido pelo banco. Atualmente há sempre a opção de baixar o extrato em algum formato de arquivo "importável" (txt, excel, csv, ofx, ofc, etc.). Por observação dos bancos que trabalho acredito que o arquivo OFX (usado pelo Money) é o mais popular que segue um formato padrão. Embora todos tenham arquivos txt, cada um usa um caracter diferente de separação de colunas, ou de formatação de valores, etc.

Inicialmente o sistema trabalhará apenas com a importação de arquivos OFX para simplificar. Informações sobre o formato podem ser encontradas em http://www.ofx.net/.

1. O sistema deve aceitar o upload de um arquivo OFX e converte-lo:
2. Ao fazer o upload o usuário deve informar a conta bancária em que este extrato deverá ser importado.
   1. A maioria dos arquivos OFX de extrato vêm com a informação da agência e conta corrente. Assim, na UI o sistema deve tentar lêr essa informação e se encontrar já sugerir ou simplesmente usar essa informação para realizar a importação. No Core, mesmo que o usuário forneça a conta em que deseja a importação o sistema deve validar e prevenir que o usuário importe o extrato de uma conta dentro de outra.
   2. O sistema deve validar se o período do extrato sendo importado coincide de alguma forma com os dados já existentes no banco de dados. De forma e evitar que o usuário importe um arquivo com poucos dias e "fiquem faltando" registros entre as importações. Ex.: Se já existe no banco a movimentação entre as datas 01/01/2015 e 25/02/2015, o sistema não deve permitir que o usuário importe um arquivo cuja data inicial seja maior ou igual à 25/02/2015. Evitando que registros fiquem sem importação. Neste caso o arquivo sendo importado deve no mínimo começar no dia 24/02/2015. Embora a validação seja "burlável" editando-se o arquivo OFX, a intenção é evitar erros do usuário não a preocupação de total imunidade a falhas.
   3. Caso os períodos do banco e do arquivo se sobreponham em parte, o sistema deve avaliar os registros 1 a 1 para evitar a inserção de dados duplicados. No final retornar a quantidade de novos registros importados (apenas para notificação do usuário).

Manipulação de Arquivo e Classe Utilitária Como a UI e o Core vão precisar extrair as informações do OFX (dados do cabeçalho e conteúdo do extrato), os métodos de manipulação do arquivo e criação dos CashFlowBankStatementVO devem ser criados em uma classe utilitária acessível por ambas as camadas.

TODO Task No futuro podemos implementar regras de conciliação automatizadas. Mesmo que cada banco escreva de um jeito no extrato e que mesmo eles de vez em quando troquem a descrição. Seria possível permitir que o usuário criasse regras para conciliação automaticamente.Por exemplo: caso o cliente não faça controle dos seus recebíveis de cartões, tíquetes, etc., mas queira que um lançamento seja gerado automaticamente para os valores depositados constarem no seu caixa. O sistema poderia identificar o lançamento, soma-los e criar um lançamento na categoria correta de lançamento; O sistema poderia identificar automaticamente lançamentos de compensação de folhas de cheque e conciliar com o cadastro de folhas de cheque voando e marca-los como compensados, bem como validar e alertar se alguma folha rasurada foi compensada; Analisar lançamentos de boletos recebidos e dar baixa nas dívidas de contas a receber; Igualmente para a contas a pagar pagas por malote eletrônico que muitas vezes vem somadas no extrato em um lançamento único, o sistema poderia ser capaz de procurar pela data e pelos lotes gerados e conciliar o lançamento do extrato com todas as contas a pagar de uma única vez.

Categoria de Lançamentos

A categoria de lançamentos tem a função de agrupar e totalizar diferentes lançamentos em grupos para simplificar relatórios de fechamentos por período e avaliação do fluxo financeiro da empresa.

1. As categorias se organizam de forma hierárquica, isto é, permite que uma categoria esteja dentro da outra. Por exemplo, podemos ter uma categoria chamada 'Receitas', e dentro categorias como 'Vendas à Vista', 'Cartões Crédito', 'Cartões de Débito', 'Encomendas e Entregas', etc.
2. As categorias devem ter uma definição se aceitam ou não que lançamentos sejam associados à elas. Categorias que não restringem a associação de lançamentos diretamente terão a função apenas de agrupas categorias filhas e exibir seu total.
3. Categorias com lançamentos anexos não podem ser excluídas.
4. Não há necessidade de desabilitar a categoria, pois basta restringir a associação de novos lançamentos à categoria para que ela não seja mais usada.
5. Não tendo movimentação dentro da categoria ou em suas filhas a categoria não deve aparecer em relatórios (impressos ou em tela).
6. Quando um lançamento é alterado, se ele já estava em uma categoria que tem restrição de associação (tendo sido associado em algum momento em que a associação não era restrita), a confirmação de alteração deve continuar permitindo que o lançamento continue na categoria restrita. A ideia é que se for necessário corrigir algum problema em lançamento passado, seja possível corrigir apenas o desejado sem cair em uma restrição do presente.

Lançamentos Financeiros

1. Os lançamentos financeiros são o registro de qualquer movimentação financeira da empresa. Podendo ser a pagar ou a receber, já efetuada ou futura.
2. O usuário de conseguir cadastrar um lançamento a pagar/receber futuro. Devendo preencher sempre a data vencimento. Mas sem a necessidade de informar de qual conta financeira será paga/recebida.
3. Ao pagar/receber a conta, torna-se obrigatório associa-la a uma conta financeira para indicar a movimentação naquela conta.
4. Um lançamento pode ter diversas parcelas com diferentes valores e datas de vencimentos. Podendo ainda ser pago de formas diferente. Ex: A primeira no dinheiro, a segunda e terceira no cheque predatado, e as outras no boleto. Por fim o usuário ainda esqueceu de pagar um dos boletos e teve que transformar o pagamento em um TED ou depósito para quitar a parcela.
5. Em alguns momentos uma compra ou venda pode ser faturada em momentos diferentes e ter mais de um documento gerador (Ex: Nota Fiscal) e ter apenas 1 pagamento somando os documentos ao fim de um período. Ex: Uma venda de móveis com entrega em 3 etapas, com 3 notas diferentes, mas apenas 1 conta para pagar. Ou ainda, o valor total dividido em 5 parcelas iguais. Neste caso o lançamento deve permitir a associação de vários documentos de origem (NF) e permitir o cadastro de vários pagamentos.
6. Todo lançamento deve estar associado à uma categoria para correta sumarização do fluxo financeiro.
7. É obrigatório definir a linha de exibição do lançamento. Mesmo que a UI ofereça essa descrição para alguns casos, como por exemplo, se o lançamento de uma conta a pagar está sendo gerada a partir de uma entrada de NFe, ou de um código de barras de conta de concessionárias, etc.
8. Mesmo não sendo obrigatório cadastrar a conta financeira de onde a conta será paga, deve ser permitido. Neste caso funcionará como uma previsão de planejamento para aquela conta específica.
9. Os lançamentos podem ser de diversos tipos. Cada tipo tem sua característica própria, como por exemplo validações diferentes, atributos obrigatórios diferentes, diferentes tratamentos para malote eletrônico, etc.. Entre os tipos de lançamentos a serem definidos:
   1. [Versão Futura] Salários: Enviado por malote eletrônico ou pago em conta local. Exige número do banco, da agência e conta corrente. Nome e CPF do funcionário. Além do tipo de pagamento: Salário, Adiantamento, Férias, 13°, Rescião Contratual, Vale Transporte, etc.
   2. Boletos de Concessionárias: Boletos de contas de consumo como telefonia, luz, gás e normalmente impostos municipais como TFA, IPTU, etc. Devem conter um código de barras válido, valor e data de vencimento.
   3. Boletos Cobrança: Boletos mais comuns associados a compras e faturamento de produtos e serviços. Exige código de barras, vencimento, valor.
   4. GPS: Guia de Recolhimento de INSS. Exige data de competência, vencimento, validade, etc. (Rever)
   5. DARF: Guia de Recolhimento de DARF/IRRF. Exige data de competência, vencimento, validade, etc. (Rever).
   6. Depósito/Transferência/TED/DOC: Pagamento por depósito em conta. Exige banco, agência e conta corrente. Se pago de uma conta bancária de mesmo banco, é uma trasnferência/depósito eletrônico, se for de banco diferente é um TED/DOC. É necessário rever a integração bancária para análise de como enviar trasnferência e TED/DOC para os bancos por malote eletrônico.
10. Caso o lançamento recebido pelo core para ser inserido ou alterado tenha um PersonVO sem ID, o sistema deve verificar se tem o CPF/CNPJ definido e tentar procurar no BISCore a existência deste Person por esta chave. Caso não encontre, o sistema deve tentar criar esse novo PersonVO automaticamente antes de criar o lançamento.
    1. Caso ocorra um erro ao salvar o PersonVO o sistema deve retornar o problema, não persistir o lançamento se parte das informações (a associação da PJ/PF) não serão salvas adequadamente.

Conciliação Bancária

A conciliação bancária tem a finalidade de sincronizar as informações oferecidas pelo banco (importado no sistema através de arquivo), com os lançamentos do sistema. Essa sincronização é a forma de garantir que todos os lançamentos bancários estão corretamente lançados na contabilidade da empresa. Ajudando a encontrar falhas de lançamentos e diferenças de caixa. Com o adendo de que lançamentos bem feitos resultam em dados mais confiáveis.

1. O sistema deve oferecer uma interface que permita mapear as 'parcelas' dos lançamentos do sistema com os registros presente no extrato da conta bancária. O mapeamento entre o lançamento e o registro bancário é feito através de outro objeto: o 'CashFlowStatementInstallmentBankStatementVO'.
2. O mapeamento entre lançamentos do extrato e do sistema deve ser do tipo 1:N, ou N:1 pois podemos ter:
   1. múltiplos lançamentos no sistema e um único lançamento no extrato, como boletos pagos em malote eletrônico; e,
   2. ter um único lançamento no sistema para múltiplos no extrato, como por exemplo os créditos de cartões de crédito de um período que não são controlados no sistema, e o usuário simples soma todos para realizar um único lançamento de crédito mensal.
3. O sistema jamais deve permitir que uma 'conciliação bancária' seja do tipo N:N.
4. Ao validar os valores do mapeamento o sistema deve garantir que o status do objeto seja definido adequadamente.

Contas a Pagar & Receber

O sistema deve ter uma UI que permita o usuário prever as contas que tem a pagar e receber em alguma forma de "timeline" que facilite a visualização dos saldos das contas dia a dia. Com a previsão do à pagar e o à receber, salientando os dias em que o saldo previsto está no vermelho, ou no "amarelo" quando o saldo previsto não é vermelho mas está muito perto do vermelho. O calculo do valor do amarelo deve ser vinculado proporcionalmente aos valores de contas a receber com algum índice de inadimplência (a brotar de algum lugar no futuro) ou na média dos valores a receber. Pois se alguma conta a receber não entrar, por atraso ou qualquer outro problema a previsão vai por água abaixo.

1. Mesmo sem a UI idealizada ainda, ao definir que os pagamentos serão feitos em uma conta do tipo 'bancária' a UI deverá exibir a opção de "Pagar por Malote Eletrônico". Ao escolher essa opção a UI deve enviar para o Core a solicitação de gerar o arquivo de Lote passado a coleção de IDs dos lançamentos que serão pagos por malote eletrônico, uma lista de mesmo tamanho e mesma ordem com as datas de pagamento planejadas e de qual conta o pagamento será realizado. Para gerar o arquivo o core deve validar:
   1. Se os pagamentos ainda não estão pagos, nem em estado de 'enviado' em algum lote anterior.
   2. Validar se todos os pagamentos foram solicitados no malote eletrônico são suportados por aquele banco. Caso algum não seja o sistema deve abortar e retornar exceção. Para que fique o mais claro que algum pagamento não será enviado no malote e não deixar um pagamento sem ser feito.
   3. Validar se todas as datas de vencimento são do dia atual ou futura.
2. O sistema deve permitir que um arquivo de lote possa ser baixado mais de uma vez, caso o usuário "perca" o arquivo, mas só no mesmo dia. Impedir que o usuário baixe o arquivo de lote do dia anterior para evitar que o usuário tente enviar para o banco um arquivo de lote com datas de pagamento possivelmente erradas.

Entidades

CashFlowCategoryVO - Categorias de Lançamentos

• As categorias de lançamentos são usadas para totalizar os lançamentos por grupos de interesse, de forma a mostrar relatórios de fluxo de caixa.
• As categorias devem ter uma estrutura hierárquica, de forma que o usuário possa criar sua árvore da maneira como achar conveniente ter os totais e subtotais.

As categorias devem ter os seguintes campos:

• Nome: Nome da categoria dada pelo usuário.
• Categoria Pai: A categoria pai define onde essa categoria será utilizada.
• Permite Lançamento: Define se essa categoria permite que sejam colocados lançamentos nela ou se não. Categorias que não permitem o lançamento direto nela podem ser usadas como categorias pais apenas para a sumarização das categorias abaixo dela.

  • Em caso de alteração, que proíba novos lançamentos na categoria, os lançamentos antigos continuarão lançados sem problema.

    Categorias com lançamentos e lançamentos filhos devem ter os totais das filhas e dela própria sumarizados. Mesmo que sejam exibidos separados de alguma forma.

TODO Task Como forma de auxiliar o usuário a "não esquecer de pagar as contas", no futuro as categorias podem ter regras de 'lançamentos esperados'. Essas regras serviriam para registrar que alguns lançamentos são esperados dentro dessa categoria, assim quando o lançamento não existir o sistema poderia notificar que falta o lançamento. Muito útil por exemplo para mensalidades, contas de consumo ou qualquer outra que tenha alguma frequência quinzenal, mensal, anual, etc. O sistema poderia avaliar não só se há o lançamento para ajudar a encontrar erros da contabilidade (seja falta do lançamento seja lançado na categoria errada), como também avisar antes do vencimento que nem o lançamento como "contas a pagar" foi realizado até o momento.

CashFlowStatementVO - Lançamentos Financeiros

• Os lançamentos financeiros são usados para registrar as movimentações financeiras das empresa. Qualquer saída ou entrada de dinheiro deve ter um lançamento correspondente.
• Um lançamento financeiro pode representar tanto uma conta já paga/recebida quanto um lançamento futuro de recebimento/pagamento.

Os lançamentos devem possuir os seguintes atributos e relacionamentos:

• Empresa: Indicando à qual empresa esse lançamento pertence. [Obrigatório]
• Categoria: Categoria de pagamentos, para sumarização dos pagamentos.
• Beneficiário/Pagador: Associa uma Pessoa como Beneficiário/Pagador ao lançamento. Não deve ser obrigatório, mas permitir a associação para facilitar a busca dos pagamentos/recebimentos por cliente, fornecedor, funcionário, etc. (PersonVO)
• Documento(s) de Origem: Permite a associação de documentos que geraram o lançamento, como NFe, Guias de Impostos, Contas de Consumo, etc. Pode ser uma maneira de arquivar a guia (como arquivo binário, ou como referência para o cadastro da NFe no sistema). Algumas vezes um mesmo lançamento de pagamento (por exemplo mesmo boleto, ou mesma transferência) pode abrange a união de vários Documentos de Origem, por isso um lançamento deve permitir a associação de múltiplos documentos.
• Operação do Lançamento: Define a operação desse lançamento: [Enum]
  • DEBIT: Uma saída, valor removido do caixa: conta a pagar como um boleto de fornecedor, pagamento de salário, etc.
  • CREDIT: Uma entrada, valor removido do caixa: conta a receber como um boleto emitido para um convênio, recebíveis de cartões de crédito e débito, etc..
  • FUNDTRANSFER: Transferência de fundos entre uma conta e outra.
  • FUNDFIX: Lançamento usado para fazer correções de caixa em últimos casos. Quando não se encontra mais o problema, ou mesmo para correções de "imperfeições monetárias" como arredondamentos dos centavos durante os pagamentos em moeda.
• Tipo do Lançamento: Permite definir alguns tipos diferentes de lançamentos: [Enum]
  • UNIQUE Define um pagamento único. Como o pagamento de uma nota avista, um serviço de conserto prestado, etc.
  • INSTALLMENTS Define que é um pagamento parcelado. Como uma nota com o valor dividido em 3 vezes em 3 boletos, ou um pagamento de maquinário em várias parcelas.
• Nome de Exibição: Descrição 'curta' dado pelo usuário para descrever o lançamento. Este nome que será usado para exibir em telas e relatórios (como extratos das contas) que permita que o usuário identifique o pagamento.
• Observações: Campo que permita que o usuário escreva qualquer detalhamento mais específico sobre o lançamento.

CashFlowStatementInstallmentVO - Parcelas do Lançamento

O objeto "parcela do lançamento" indica as informações sobre o pagamento. Como um mesmo lançamento pode conter pagamentos parcelados e serem pagos de formas diferentes as informações sobre pagamentos ficam um objeto separado. Para lançamentos sem parcelamento (pagamento único) deve conter apenas "uma parcela" associada.

• Origin Account: Quando o lançamento for um pagamento ou transferência de fundos, é obrigatório associar a conta para indicar de onde foi tirado o valor para pagamento/transferência.
• Recipient Account: Quando o lançamento for um recebimento ou transferência de fundos, é obrigatório associar à uma conta para indicar para onde foi o valor recebido.
• Lançamento: Associa a parcela ao lançamento.
• Comprovante de Pagamento: Permite anexar o documento (arquivo) com o comprovante de pagamento.
• Cheque: Caso o pagamento seja feito com folha de cheque, a associação ao objeto que representa a folha de cheque deve ser informada.
• Dados Bancários: Em caso de pagamento com depósito, transferência essa associação é obrigatória. Assim como a informação do PersonVO (o destinatário do pagamento). Para pagamentos com boletos o Person é obrigatório, mas a informação bancária não. A informação bancária pode ser obtida de alguns boletos automaticamente.
• Forma de Pagamento: Define a forma como a conta à pagar ou receber é realizada. (não usado para lançamentos do tipo FUNDTRANSFER, neste caso sempre lançar OTHER)
  • [VERSÃO FUTURA] PAYROLL: Pagamento de folha de pagamento de funcionários. (Somente Débito) Folha de pagamento é o pagamento usado por malote eletrônico ou similar.
  • PUBLICSERVICES: Pagamento através de Boletos de concessionárias de serviços como telefonia, luz, gás, etc.
  • PAYMENTSLIP_DARF Pagamento através de guia de pagamento DARF
  • PAYMENTSLIP_GPS Pagamento através de guia de pagamento GPS
  • BOLETOS: Pagamento através de boletos de pagamentos em geral
  • DEPOSIT: Pagamento através de depósitos
  • CHECK: Pagamento com folha de cheque
  • OTHER: Pagamento feito diretamente do caixa, em dinheiro outra forma diferente das controladas pelo sistema.
• Estatus do Lançamento: Define o "passo" ou estado em que o lançamento se encontra:
  • PLANNED: O pagamento está planejado (lançado no sistema) e aguardando para pagamento/recebimento.
  • SENT: Estado usado para contas que são pagas por malote eletrônico, ou cobranças por geração de boleto, e indicam que já foram incluídas em um lote para enviar para o banco. Neste estado a conta já deve estar associada à uma conta bancária.
  • ERROR: Estado usado para contas que foram enviadas ao banco por malote eletrônico e retornaram com algum tipo de erro da instituição bancária.
  • PAID: Estado indicando que o lançamento já foi realizado. Isto é, o pagamento efetuado ou o recebível em caixa. Neste estado a associação da conta é obrigatória.
• Data de Vencimento: Data máxima para pagamento sem penalidades de multas, juros e protestos. Obrigatório
• Data de Execução: Data em que a ação de pagamento/recebimento realmente ocorreu.
• Data de Compensação: Data em que o valor realmente entrou no caixa. Normalmente a data é uma duplicata do valor de 'data de execução', no entanto para recebíveis de cartões, boletos, e cheques depositados essa data pode ser diferente da data de execução devido ao processo de compensação. Este campo nunca deve ser nulo para lançamentos 'executados' (que já ocorreram). Em casos de compensação imediata, duplicar o valor de 'data de execução' para simplificar consultas do banco de dados.
• Valor Original: Valor do lançamento. (Seguindo sempre a convenção de que todo pagamento é salvo como valor negativo no banco, e todo recebimento é salvo como valor positivo. - Nos casos de lançamentos de transferência de fundos, sempre lançar o valor positivo)
• Valor Multas: O valor de multas é aplicado para contas pagas com atraso ou outros acréscimos.
• Valor Descontos: O valor de descontos concedidos nos boletos que devem ser decrescidos do valor original do boleto.
• Valor Final: O valor final é o valor que realmente entrou ou saiu da Conta. Esse valor pode ser diferente do original devido a multas, descontos, taxas de recebíveis, etc.
• Campos do Malote Eletrônico: Abaixo está a relação de alguns campos usados no malote eletrônico.
  • Mensagem de Retorno: Campo de texto livre para salvar a mensagem de retorno do banco. Esta mensagem é usada pelo sistema apenas para exibição para o usuário.
  • Número de Lote: Identificador do lote de pagamento gerado pelo sistema. Quando o arquivo de lote é gerado o sistema deve definir o ID do Lote único para identificar o arquivo gerado. Esse id deve ser salvo para referência futura do retorno e para regerar o arquivo caso o usuário deseje.
  • Data de Geração do Lote: Define a data de geração do lote.
  • ID Pagamento: Todo pagamento enviado para em um malote eletrônico deve ter um ID único "na vida". Que não deve ser repetido preferencialmente nem em outros arquivos de Lote. Para evitar conflitos caso pagamentos de um mesmo lote tenham retorno em lotes diferentes. Esse ID é normalmente usado pelo sistema do banco.
  • Número Validação: Número de validação retornado pelo banco ao autorizar um pagamento. Diferente para cada sistema bancário.
• Código de Barras: Valor do Código de barras da guia de pagamento dos pagamentos que dispõe de código de barras.
• Representação Numérica: Numeração da representação numérica do código de barras. Quando o usuário digita 1 ou outra informação o sistema deve gerar a outra automaticamente.

CashFlowAccountVO - Contas

Contas são usadas para lançar as entradas e saídas financeiras da empresa. Facilitando o controle dos saldos e valores financeiros da empresa.

Cada conta cadastrada deve ter os seguintes atributos:

• Nome: Para o usuário nomear e identificar a conta.
• Tipo da Conta:
  • Conta Local: Usada para lançamento manuais de caixas locais.
  • Conta Bancária: Usada para controle de contas bancárias como corrente ou conta investimento. Esse tipo de conta permitirá a conciliação de extrato bancário, bem como a exportação de “malote eletrônico” (CNAB?) para envio de pagamentos para o banco. Para contas bancárias temos os seguintes atributos adicionais:
    • Banco: Número do banco (listagem já pré existente do sistema, por causa do PersonBankDataVO).
    • Agência: Agência da conta.
    • Número da Conta: Número da conta corrente.
    • Contato Agência: Permite anexar um contato (PersonVO) da agência.
    • Contato do Gerente: Permite anexar um contato (PersonVO) do gerente da conta.
  • [VERSÃO FUTURA] Cartão BNDES: Usada para controlar compras e fluxo do cartão BNDES. (Para Implementação Futura)
  • [VERSÃO FUTURA] Cartão de Crédito: Usada para controlar e registrar fluxos de pagamento em cartão de crédito. (Para Implementação Futura)
  • [VERSÃO FUTURA] Administradoras de Cartão: Conta com a função de gerenciar os lançamentos de vendas com cartão de crédito. Para calcular taxas e saber o saldo de recebíveis, taxas e etc.. Ao receber no banco, marcamos como "Transferência de Fundos" entre as contas de administradoras e do extrato bancário.
  • [VERSÃO FUTURA] Conta Aplicação: Conta usada para gerenciar os fundos de aplicações da empresa.

CashFlowBankStatementVO - Extrato Bancário

Este objeto representa um lançamento do extrato bancário, oferecido pela instituição financeira (banco).

Atributos do objeto:

• Conta Bancária: Todo lançamento obrigatoriamente deve estar associado à uma conta (CashFlowAccountVO) do tipo 'Conta Bancária'.
• Operação: Define o tipo da operação: Crédito ou Débito.
• Valor: Valor da operação financeira. Toda a operação de crédito deve ter o valor positivo, todo débito deve manter o valor negativo.
• Linha de Exibição: Descrição como exibida pela instituição financeira.
• ID Lançamento: Os extratos bancários costumam (não é regra) ter um ID que identifica aquele lançamento, permitindo que o sistema reconheça o lançamento do banco com os já existentes no sistema evitando duplicatas. Na ausência desse ID a tríade Data + Descrição + Valor deve ser usada para reconhecer o lançamento. (Embora em casos raros possa existis o lançamento exatamente igual no extrato).

CashFlowStatementInstallmentBankStatementVO - Conciliação Bancária

Este VO de nome pomposo representa a associação entre o lançamento financeiro do sistema e o extrato bancário. Além dos mapeamentos entre os objetos, este VO tem apenas mais 1 atributo: Status do Mapeamento.

• NONE: Significa que nenhum mapeamento foi feito. No banco esse estado é definido pela ausência do Vo de mapeamento.
• INCOMPLETE: Significa que algum mapeamento já foi feito entre os lançamentos e o extrato, mas os valores não estão batendo.
• DONE: Mostra que o mapeamento está completo e "satisfeito" quanto aos valores.

Métodos de Fachada

Métods de CRUD

Métodos de CRUD são os métodos de Insert, Update, Delete e os métodos de find padrão do BIS. São esperados métodos de CRUD pada as seguintes entidades:

• CashFlowCategoryVO
• CashFlowAccountVO
• CashFlowStatementsVO - Este objeto valida e persiste os seguintes objetos em cascata:
  • CashFlowStatementDocVO
  • CashFlowStatementInstallmentVO

Métodos de Serviços

São métodos com lógica de negócio publicados na fachada com funções específicas diferentes do padrão do 'CRUD':

Integer importBankStatementOFXFile(byte[] ofxfile, Long idcashflowaccount) throws BISException

@param ofxfile conteúdo do arquivo OFX.
@param idcashflowaccount ID da Conta Bancária que estamos tentando importar os lançamentos.
@return Total de registros importados.

Este método recebe o conteúdo de um arquivo OFX para importa-lo como sendo o extrato de uma determinada conta bancária (CashFlowAccountVO).
Regras de negócio:

1. Caso o banco, agência e conta esteja disponível no OFX recebido, previne que o usuário importe um arquivo de extrato de um banco na conta errada.
2. Só permite a importação caso a conta ainda não tenha nenhum lançamento importado, ou caso o o arquivo OFX tenha no mínimo a data inicial 1 dia anterior ao maior registro da base. Por exmeplo: Caso na base já existam os registros de 01/01/2015 à 21/01/2015. O OFX deve no mínimo ter seu primeiro registro com a data de 20/01/2015. A ideia é prevenir que o usuário "perca" registros no meio do seu extrato.
   1. Para evitar um "gap" entre registros no passado, deve-se validar quando a data inicial do OFX for menor que a data inicial da base: se a data final do OFX é no mínimo 1 dia maior que a primeira data da base.

   O objetivo em sobrepor sempre 1 dia é que se o usuário exportar o OFX até o "dia atual", o OFX conterá apenas os registros do dia até o momento em que é exportado. Movimentações posteriores a exportação acabariam sendo perdidas se o sistema aceitar importar arquivo apenas com a presente data.

3. Os registros do OFX devem ser convertidos em objetos CashFlowBankStatementVO. E persistidos no banco. Os registros idênticos devem ser simplesmente ignorados, não causando nenhum erro.
4. Ao importar um extrato com sucesso, o saldo mais recente deve ser atualizado no campo "saldo" do CashFlowAccount.

void createCheckBook(Long idaccount, Long startnumber, Long endnumber) throws BISException

@param idaccount ID da conta em que os cheques serão associados.
@param startnumber Numeração do primeiro cheque do talão.
@param endnumber Numeração da última folha de cheque do talão.

Este método criar novas folhas de cheque no sistema. Folhas recém criadas ganham o estatus de 'NEW', que significa que a folha está disponível para emissão na empresa mas ainda não foi utilizada para nada. Uma maneira de controlar quantas folhas estão disponíveis para na empresa. Regras de Negócio:

1. O sistema só deve permitir a crição de um talão de cheques para contas do tipo 'bancárias'.
2. Validar se as folhas de cheque (mesmos números) já existem para a mesma conta bancária.

byte[] createBankDirectionFile(Lond idaccount, List<Long> idstatementinstallmentlist) throws BISException

@param idaccount ID da conta bancária que desejamos gerar o arquivo
@param idstatementinstallmentlist Lista de IDs das 'parcelas' dos lançamentos a serem pagas.

@return Conteúdo do arquivo gerado a se enviado para o banco.

Este método gera um arquivo com as instruções de pagamento/recebimento para ser enviado ao banco correspodente. Regras de Negócio:

1. O método deve validar se a conta passada é uma conta bancária.
2. Para abstrair a implementação da geração de arquivo de cada banco deve-se usar o pattern de "Factory". Este deve devolver a implementação da interface 'BankDirections' de acordo com o número de banco passado, ou uma exceção de que o número de banco passado. No objeto recebido chamar o método da interface com a mesma assinatura deste método para obter o arquivo gerado corretamente.

Métodos Utilitários

String convertDigitedCodeToCodeBar(String digitedcode) throws BISException

@param digitedcode Linha digitável exibida na guia/boleto.

Este método recebe a numeração da linha digitável valida e converte para o valor do código de barras.

String convertCodeBarToDigitedCode(String codebar) throws BISException

@param codebar Código de barras da guia/boleto.

Este método faz o oposto do convertDigitedCodeToCodeBar(...), recebe o código de barras, valida e converte para a numeração numérica da linha digitável.

BankSlipDataBean createBankSlipDataFromCodeBar(String codebar) throws BISException

@param codebar Código de barras da guia/boleto.

Extrai as informações básicas e padrão de todos os boletos/guias. Como por exemplo, em todos os boletos os primeiros 3 dígitos é o número do banco, o 4° dígito a moeda do boleto, etc.

1. Em seguida, depois de extraída o número do banco tenta usar o Factory do BankDirections para extrair as informações do código particular do próprio banco. Isso porque parte do código do boleto é de livre uso das instituições financeiras e cada banco utiliza um padrão próprio para a geração e identificação dos seus boletos.

void isServiceCodeBarValid(String codebar) throws BISException

@param codebar Código de barras da guia/boleto de consecionária

Valida se o valor passado é um código de barras válido para um boleto de concessionária. Para ser válido as regras são:

• Apenas dígitos
• Tamanho exato de 44 algarismos
• O primeiro dígito é "8"
• Se o DV Geral é válido
• Se o campo "segmento" tem um valor válido
• Se o campo "Identificação do valor real ou referência" tem um valor válido

Veja mais detalhes em Especificação de Guias e Boletos.

void isBoletoCodeBarValid(String codebar) throws BISException

@param codebar Código de barras do boleto

Valida se o valor passado é um código de barras válido para um boleto. Para ser válido as regras são:

• Apenas dígitos
• Tamanho exato de 44 algarismos
• Se o DV geral é válido.
• Se o código do banco não está zerado
• Se o campo código da moeda é 9 (Não conhecemos outro valor, então se não é 9 é inválido!)

Veja mais detalhes em Especificação de Guias e Boletos.

void isServiceNumericLineValid(String numericline) throws BISException

@param numericline Representação numérica da guia/boleto de concessionária

Valida se o valor passado é uma representação numérica válida para um boleto de concessionária. Para ser válido as regras são:

• Apenas dígitos
• Tamanho exato de 48 algarismos
• O primeiro dígito é "8"
• Se o DV de cada bloco é válido
• Se o DV Geral é válido
• Se o campo "segmento" tem um valor válido
• Se o campo "Identificação do valor real ou referência" tem um valor válido

Veja mais detalhes em Especificação de Guias e Boletos.

void isBoletoNumericLineValid(String numericline) throws BISException

@param numericline Representação numérica da guia/boleto do boleto

Valida se o valor passado é um código de barras válido para um boleto. Para ser válido as regras são:

• Apenas dígitos
• Tamanho:
  • tamanho == 33 [sem o último bloco], OU
  • tamanho > 33 && tamanho <= 36 && dígitos da posição 33 até o final serem zerados [Não permite que o último bloco com menos de 4 dígitos possa ser interpretado como o fator de vencimento, que deve sempre ter 4 dígitos], OU
  • tamanho >= 37 && tamanho <= 47 [valor com o o bloco maior que o necessário para interpretação do fator de vencimento]
• Se o DV geral é válido.
• Se o código do banco não está zerado
• Se o campo código da moeda é 9 (Não conhecemos outro valor, então se não é 9 é inválido!)

Veja mais detalhes em Especificação de Guias e Boletos.

Validações

Além das validações "comuns" de campos obrigatórios, maxlenghts, validações específicas de campos, etc. Seguem outras validações de requisitos e funcionamento do módulo CashFlow.

CashFlowStatement

• Valida se o favorecido foi informado. Cadastra-lo caso seja novo, permitindo que o Core possa valida-lo.
• Valida se categoria foi definida
  • Valida se a categoria definida tem permissão de receber lançamentos.
• Valida se o quantidade de parcelas é >= 1

  Todo lançamento precisa de no mínimo uma parcela com as informações de pagamento.

• Valida se data de pagamento é <= hoje.

  Não aceita data de pagamento "futura". A data prevista para pagamento já existe, é o campo vencimento. O campo pagamento só deve ser preenchido depois que o lançamento foi realmente pago. Algo que não pode ter acontecido no futuro.

• Se operação é débito:
  • Valida se conta de origem foi definida
  • Valida se conta de origem pertente à Empresa associada no lançamento.
  • Se paykind = publicservices:
    • Validar se código de barras é único em relação aos objetos do banco e às parcelas deste objeto.
    • Validar se código de barras de todas as parcelas pertencem ao mesmo favorecido. Utilizar o campo 06 "Identificação do Órgão/Empresa", descrito aqui.
    • Verificar se a Identificação do Órgão/Empresa e Segmento não for conhecida de acordo com esta tabela, fazer um log de Warning para avisar os desenvolvedores de um novo tipo de boleto encontrado no cliente, aumentando a base de conhecimento e possíveis melhorias futuras. Incluir no Log o código de barras completo e a descrição usada pelo usuário para identificar o lançamento. Não lançar validação, pois o não conhecimento da empresa/órgão até o momento não atrapalha o funcionamento do sistema.
    • Validar se valor original é igual ao valor existente no código de barras, quando o código de barras contiver essa informação.

      Caso o boleto tenha um valor no seu código de barras, o valor deve ser mantido no campo valor original e impedir alterações. Isso porque ao enviar o boleto para pagamento por malote eletrônico a instituição pode contrastar as informações e não executar o pagamento.

    • Se Segumento = 5 (Órgãos Governamentais) e Órgão = "0179" (FGTS) ou = "0239" (FGTS Rescisório):
      • Validar se Vencmento é dia útil. Sendo dia útil neste caso de Segunda à Sexta e não feriados Municipais, Estaduais ou Federais. Caso não seja útil indicar a mensagem de que Guias de FGTS com vencimento em dia não útil deve ser apaga no dia útil ANTERIOR!

        Implementar apenas a validação de dia útil da semana. A implementação de dia ser feriado ficará para o futuro, provavelmente com algum serviço do BIS que oriente os feriados.

  • Se paykind = boletos:
    • Validar se Favorecido está associado.

      Se temos algum novo, caso PersonVO sem ID, tentar inseri-lo para que o Core faça sua validação.

    • Validar se código de barras + vencimento + valor final é único em relação aos objetos do banco e às parcelas deste objeto.

      Como alguns boletos não tem data de vencimento nem valor no código de barras, o mesmo código pode se repetir mensalmente para dívidas mensais, como cartões de crédito e outros prestadores de serviços.

    • Validar se Dados bancários extraídos do código de barras de todas as parcelas, não pertencem à outro favorecido.

      Caso ainda não sejam conhecidas, se preparar para associar e salvar no banco os novos dados associados à este favorecido.

    • Validar se Valor total = Valor Original + Multas/ Acréscimos - Descontos.
    • Validar se valor original é igual ao valor existente no código de barras, quando o código de barras contiver essa informação.

      Caso o boleto tenha um valor no seu código de barras, o valor deve ser mantido no campo valor original e impedir alterações. Isso porque ao enviar o boleto para pagamento por malote eletrônico a instituição pode contrastar as informações e não executar o pagamento.

  • Se paykind = DARF:
    • Validar se quantidade de parcelas é = 1

      DARF não suporta múltiplas parcelas.

    • Validar se vencimento + valor + código da receita + número referência é único em relação aos objetos do banco.
    • Validar se o campo cpfcnpj contém um CNPJ válido. Não aceita CPF.
      • Validar se o CNPJ informado em cpfcnpj é o mesmo do companyvo, caso o companyvo tenha um CNPJ cadastrado.
      • Uma empresa não deve pagar guias de outras empresas ou contas particulares de PF.
  • Se paykind = GPS:
    • Validar se quantidade de parcelas é = 1

      GPS não suporta múltiplas parcelas.

    • Validar se vencimento + valor + código do pagamento + identificador é único em relação aos objetos do banco.
    • Validar se dia e mês de competência = '31/12' ou se dia = '01'

      Todas as datas do GPS devem ser dia 1 do mês da competência. Só para a competência do 13° é que usaremos a data 31/12. Assim: 1/12/AAAA representa a competência '12/AAAA' e 31/13/AAAA representa a competência '13/AAAA'.

    • Validar se Valor total = Valor do INSS + Valor de Outras Entidades + ATM/Multa Juros.
    • Validar se Vencmento é dia útil. Sendo dia útil neste caso de Segunda à Sexta e não feriados Municipais, Estaduais ou Federais. Caso não seja útil indicar a mensagem de que GPS com vencimento em dia não útil deve ser apaga no dia útil ANTERIOR!

      Implementar apenas a validação de dia útil da semana. A implementação de dia ser feriado ficará para o futuro, provavelmente com algum serviço do BIS que oriente os feriados.

  • Se paykind = CHECK:
    • Valida se a folha de cheque associada não está em uso por outro lançamento já existente.
    • Valida se a folha de cheque associada não está em uso em mais de uma parcela deste pagamento.
  • Se paykind = DEPOSIT:
    • Valida se os dados bancários informados não pertencem à outro favorecido.
      • Se os dados bancários não pertencem a outro favorecido, cadastra-lo ao favorecido atual.

• Se operação é crédito
  • Valida se conta de destino foi definida

• Se operação é transferência
  • Valida se conta de destino foi definida
  • Valida se conta de origem foi definida

• Se documentos anexados
  • Se documento é NFe
    • Validar se NFe não está associada à nenhum outro lançamento.

BankDirections

BankDirections é uma "serviço" que permite a abstração e implementação de classes com as funções específicas de cada banco. O BankDirections é composto por 3 componentes descritos abaixo:

Interface BankDirection - br.com.biserp.bismodules.cashflow.bankdirection.BankDirection

A interface BankDirection terá os métodos descritos abaixo usada para abstrair a implementação dos métodos específicos de cada banco. Por exemplo, a geração do arquivo de malote (distinta para cada banco) ou a confecção/extração dos dados da numeração do código de barras do boleto.

Implementação não obrigatória Nenhuma classe é obrigada a implementar todos os métodos. Cada método é um caso separado para cada banco. No entanto, será obrigatório que os métodos não implementados lancem a exceção: BISUnsuportedFeatureException para sinalizar que aquele método não é suportado, e permitir que o método anterior consiga avaliar e tratar corretamente o retorno ou a exceção retornada.

byte[] createBankPaymentDirectionFile(Lond idaccount, List<Long> idstatementinstallmentlist) throws BISException

@param idaccount ID da conta bancária que desejamos gerar o arquivo
@param idstatementinstallmentlist Lista de IDs das 'parcelas' dos lançamentos a serem pagas.

@return Conteúdo do arquivo gerado a se enviado para o banco.

Este método gera um arquivo com as instruções de pagamento/recebimento para o banco à qual a classe implementa suporte. Regras de Negócio:

1. Cada pagamento solicitado deve ser avaliado e verificar se o banco suporta, caso apenas 1 deles não seja suportado deve ser lançada exceção.
   1. Caso o banco não suporte gerar um único arquivo com diferentes tipos de pagamentos (por exemplo boletos e guias de impostos) uma exceção deve ser lançada informando o problema.
2. Caso o pagamento esteja vencido e o banco não suporte boletos com datas vencidas uma exceção deve ser lançada.
3. Para os diferentes tipos de lançamentos a serem pagos a implementação de cada banco deve verificar se os campos necessários estão preenchidos adequadamente.
4. Caso algum dos métodos não seja suportado pela implementação do banco, uma exceção deve ser lançada.

BankSlipDataBean completeBankSlipData(BankSlipDataBean bean, String bankcode) throws BISException

@param bean Bean já completado com as informações básicas do boleto e que receberás a informações específicas da instituição.
@param bankcode Numeração do código de barras da conta que se deseja informação

Este método recebe um objeto já parcialmente completado com as informações padrões da guia e a parte do código de barras que é de uso da privado da instituição. Desse código é possível extrair algumas outras informações úteis da guia/boleto que podem otimizar o uso para o usuário. Toda a informação adicional que for possível extrair deverá ser completada no Bean e retornado.

Verificação do Código de Barras Ao escrever a implementação deste método para cada banco procure validar as informações específicas de cada banco. Por exemplo: caso dentro do campo livre o banco use DVs próprios para validar seus próprios campos, implemente a mesma validação para garantir que o código de barras que você está interpretando tem o layout exato que você espera; caso dentro do campo livre o banco especifique a codificação de "Carteiras", verifique se a carteira passada é conhecida, caso contrário não extraia os dados. Em geral carteiras diferentes tem layouts diferentes por terem finalidades diferentes e informações diferentes. Uma interpretação errada do código de barras poderá fazer com que o BIS comece a gerar dados bancários inválidos para o PersonVO e depois será difícil de corrigi-los misturados com os dados corretos.

Factory BankDirectionFactory - br.com.biserp.bismodules.cashflow.bankdirection.BankDirectionFactory

O factory como de costume deve ter apenas o método:

public final static BankDirection getBankDirection(int bankcode) throws BISException { ... }

O método deverá retornar uma instância que implemente a interface BankDirection de acordo com o código do banco recebido.

Lançará uma exceção BISUnsuportedFeatureException caso o Factory não tenha uma instância válida para o código do banco recebido.

Construtor Privado Para evitar erros de desenvolvimento, é uma boa prática definir os construtores de todas as Factory como privado. Assim eles não poderão ser instanciados.

Implementações da Interface BankDirection

Para cada banco existente, e que o sistema der suporte, deverá haver uma implementação da interface BankDirection específica para o banco. As implementações devem ser retornas a partir do 'Factory'.

Esta mesma interface será usada para qualquer serviço bancário a ser implementado no futuro como geração de instruções de cobrança (Boletos), ou geração de instrução para pagamentos de salários, etc.

Os arquivos de implementação devem ser colocados no package br.com.biserp.bismodules.cashflow.bankdirection.impl para não misturarem com as classe do próprio sistema, e devem seguir o padrão de nome: <Nome do Banco>BankDirection, devendo evitar abreviatura no nome do banco para que o nome classe seja o mais clara possível sobre qual instituição a mesma dá suporte. Ex:

• ItauBankDirection
• BradescoBankDirection
• BancoDoBrasilBankDirection
• CaixaEconomicaFederalBankDirection
• etc.

UI Vaadin

Este tópico registra as definições para a UI padrão do BIS. Com telas e requisitos.

Lançar Débito Financeiro

Component CashFlowDebitComponent Todo o conteúdo descrito nesta sessão deve ser criado dentro de um componente chamado CashFlowDebitComponent. Para permitir a reutilização do conteúdo desta tela em outras telas distintas. O mesmo conteúdo de criar um novo lançamento será usado na tela de gerenciamento das contas, de gerenciamento de contas futuras, lançamento rápido, etc.. A criação da janela popup como sugerida nos screenshots pode ser feita para fins de testes de desenvolvimento já as telas que utilizarão este componente ainda não foram total definidas.

O sistema deve ter uma tela de entrada de débito financeiro. Essa tela basicamente lançar as "contas á pagar", só não chamamos de Contas à Pagar para evitar confusão, afinal contas à pagar são as contas que ainda não foram pagas, e a tela permite o lançamento de contas já pagas.

A tela terá alguns passos rápidos similar a um "wizard", permitindo que passo a passo o usuário faça os lançamentos desejados respondendo apenas os campos necessários, sem que tenha que enfrentar uma tela poluída de opções que o deixem perdido.

O primeiro passo é escolher um dos métodos disponíveis para lançar um débito financeiro. Para cada opção escolhida a tela terá um comportamento diferente.

Tela Inicial de Lançamento de Débito

Lançamento Manual

Ao escolher a opção de Lançamento Manual, a tela deve entrar na tela de edição "padrão", que permite que o usuário preencha campo a campo as informações do lançamento. Nesta tela teremos as seguintes regras:

• O Combobox Tipo de Pagamento deve exibir as seguintes opções: "Pagamento Único" e "Parcelado". Não exibir a opção em "branco" que equivale ao "null". Sempre exibir como valor inicial o valor "Pagamento Único". Tendo em vista que a maioria dos lançamentos tem um pagamento único, oferecer essa opção permite que o preenchimento seja mais rápido.
• O combobox Empresa, no caso de termos apenas uma empresa cadastrada, deve ser desabilitado e ter essa única opção já selecionada. Evitamos assim que o foco tenha que passar por este componente já que é obrigatório e não tem outra opção.
• O campo Favorecido é uma associação de um combo com um botão de busca. O combo permite que o usuário encontre o favorecido diretamente através do atributo "displayname" do PersonVO. Já o botão buscar abre o PersonPicker, que exibe uma lista dos PersonVO do sistema e permite uma busca mais detalhada, como busca por CPF/CNPJ, nome completo, nome fantasia, etc.
  • Sempre que o Favorecido for alterado E o campo Categoria estiver em branco, pesquisar no banco em qual categoria o último lançamento deste favorecido foi definida, e sugerir definindo a mesma categoria no campo Categoria. A ideia é otimizar e inclusive evitar confusões, uma vez que o mesmo favorecido geralmente faz sempre o mesmo tipo de venda/serviço. É comum que ele vá sempre na mesma categoria. Lembrar de validar se a categoria à qual o lançamento está associado ainda permite lançamentos nela.
• Categoria deve exibir todas as categorias cadastradas no sistema com o atributo "statementallowed" definido como true.

  

  Lançar Débito Manualmente

Lista de Parcelas A ideia é utilizar uma BISListTable ao invés do BISListSelect. Para permitir um visual melhor além de ícones que ajudem a identificar os tipos de pagamentos.

• Aba Fatura: Dentro da aba fatura estão as informações sobre o pagamento, ou pagamentos caso o Tipo de Pagamento tenha sido definido como "Parcelado".
  • Quando o Tipo de Pagamento for definido como "Parcelado", o sistema deve exibir o painel a esquerda para organizar os números de parcelas.
    • O botão "+" inclui uma nova parcela ao final da lista.
      • Ao clicar no botão "+" a nova parcela adicionada ao fim da lista deve se tornar visível na tela (caso tenha scroll) e automaticamente selecionada.
    • O botão "-" exclui a parcela atualmente selecionada.
      • Antes de excluir uma mensagem de confirmação deve ser exibida: "Tem certeza que deseja excluir a Parcela xxx?".
      • Ao excluir uma parcela, as parcelas seguintes devem ter seu índice atualizado para que não fique nenhum número "pulado".
  • O combo Conta Financeira deve exibir todas as contas de acordo com a Empresa selecionada. Para evitar que o usuário faça o pagamento de uma conta que não pertença a mesma empresa.
    • Embora este campo não esteja como obrigatório no banco de dados (por causa dos lançamentos de crédito) sua informação é obrigatória.
  • Forma de Pagamento: é parcialmente o campo do VO chamdo PAYKIND. No entanto as opções não devem ser copiadas do Enum, mas sim definidas manualmente e seletivamente:
    • Dinheiro / Outras Esta opção define no VO o valor PAYKIND.OTHER. Deve solicitar os campos Data de Vencimento, Data de Pagamento e Valor.

      

      Forma de Pagamento: Dinheiro / Outras

    • Cheque Esta opção define no VO o valor PAYKIND.CHECK. Deve solicitar os campos Data de Vencimento, Data de Pagamento, Valor e Folha de Cheque.
      • Folha de Cheque um combo que deve exibir as folhas de cheque cadastradas no sistema que ainda não foram emitidas em outro pagamento.

      

      Forma de Pagamento: Cheque

    • Depósito Esta opção define no VO o valor PAYKIND.DEPOSIT. Devendo solicitar os campos Data de Vencimento, Data de Pagamento, Valor e Dados Bancários de Destino.
      • Banco: Campo para entrada/escolha da instituição financeira de destino.
      • Agência: Agência da conta bancária de destino.
      • Conta Corrente: Conta corrente do destinatário.
      • Botão Procurar: O botão procurar abre uma tela de PersonBankDataPicker para escolha da conta corrente de destino.

        Caso o Favorecido já esteja preenchido na tela de lançamento, defini-lo também no PersonBankDataPicker para que ele só exiba os dados bancários do favorecido selecionado. Caso o favorecido do lançamento esteja desabilitado (impedido de ser trocado), configurar o DataPicker para também desabilitar o campo de filtro do favorecido para o usuário não possa troca-lo. Caso nenhum favorecido esteja definido no lançamento atualmente, não informar nenhum favorecido para o DataPicker, no entanto, ao confirmar o valor do DataPicker definir o favorecido do lançamento igual ao favorecido da conta recebido do DataPicker.

      

      Forma de Pagamento: Depósito

    • Boleto Bancário Esta forma de pagamento solicita os campos Código de Barras / Linha Digitável, Data de Vencimento, Data de Pagamento e Valor. Nesta forma de pagamento o Boleto o código do boleto é solicitado antes dos outros campos para induzir o usuário a informa-lo primeiro, já que a partir desta informação podemos definir o vencimento e valor.
      • O valor definido no VO deve ser definido como nulo quando esta opção for selecionada, para evitar que algum valor anterior fique definido por acidente. O valor correto só serrá definido de acordo com o conteúdo informado no campo Código de Barras / Linha Digitável.
      • Código de Barras / Linha Digitável este campo receberá tanto a representação numérica quanto o valor do código de barras do boleto. Deverá identifica-la e caso o valor entrado seja de um código de barras, converte-lo para a representação numérica adequada. A representação numérica deve ser formatada de acordo com o tipo de guia.
        • Quando um código é informado os valores possíveis devem ser extraídos e realizada as seguintes operações:
          • Caso a validade esteja disponível, defini-la no campo vencimento.
          • Caso o valor esteja disponível, defini-lo no campo valor.
          • Caso a agência e conta estejam disponíveis, procurar o favorecido (PersonVO) através de seus dados bancários.
            • Caso encontre o PersonVO, e o campo Favorecido já estiver preenchido e estiver habilitado, substituir o Favorecido Atual.
            • Caso encontre o PersonVO, e o campo Favorecido já estiver preenchido e estiver desabilitado, verificar se é o mesmo favorecido, se diferente emitir um erro informando que os dados bancários do boleto pertencem a outro favorecido (Exibir o nome favorecido ao qual os dados bancários estão vinculados). Limpar o conteúdo do campo não permitindo que o boleto seja anexado.
            • Caso não encontre o PersonVO, e ainda não tenha um favorecido definido, não fazer mais nada além do listado acima.
            • Caso não encontre o PersonVO, e tenha um um favorecido definido, criar um PersonBankDataVO e associar ao Favorecido (PersonVO).
        • De acordo com o tipo de guia definir o VO com os valores PAYKIND.BOLETOS ou PAYKIND.PUBLICSERVICES.

      

      Forma de Pagamento: Boleto

  • Comprovante de Pagamento Esta seção oferece alguns comandos para anexar o comprovante de pagamento da parcela.
    • Quando não há nenhum comprovante anexado, a seção deve exibir um label com a informação "Nenhum comprovante anexado!", e do lado o botão Anexar Comprovante.
      • Habilitar o drag 'n' drop de arquivo externo para anexar o comprovante. Habilitar o Drag and Drop no painel todo da parcela.

        Só permitir o upload de arquivos com a extensão pdf, jpg, jpeg e png. Com o tamanho máximo de 500KB.

    • Quando houver um comprovante anexado, a seção deve exibir um label com a informação "Comprovante anexado!", e do lado os botões Visualizar, Download e Excluir.
      • O botão visualizar deve abrir um popup com o conteúdo do arquivo para exibição no próprio browser.
      • O botão Download deve iniciar o download do arquivo diretamente.
      • O botão excluir deve exibir uma mensagem de confirmação, e se confirmado remover o comprovante anexado à parcela.

    

    Comprovante Anexado

    

    Sem Comprovante

• Aba Documentos
  • Quando não houver documento associado, a tela deve exibir dois botões:
    • Enviar Arquivo: permitirá o upload de um arquivo externo ou a vinculação de uma NFe existente no sistema.
      • Permitir que o arquivo seja arrastado (drag'n'drop) no painel para fazer o upload do arquivo.

        Só permitir o upload de arquivos com a extensão pdf, jpg, jpeg e png. Com o tamanho máximo de 2MB.

    • Associar NFe. Permite que uma NFe seja escolhida e associada ao lançamento.
  • Quando houver documento associado:
    • a aba deve exibir um preview do arquivo associado (Trabalhar nisso ainda)
    • deve exibir os botões:
      • Visualizar: Abre um popup com a visualização no browser do documento, se for NFe abre o componente de visualização da NFe.
      • Baixar Documento: inicia o download do arquivo imediatamente. (Só exibir no caso de arquivo enviado, não usado para NFe).
      • Excluir: Remove a associação entre o lançamento e a NFe, ou excluí o arquivo no caso de arquivo enviado.

Sem Documento

Documento Anexado

Lançamento a partir de NFe de Compra

Lançamento a partir de NFe

Ao fazer um lançamento a partir de uma NFe, o sistema deve questionar pela chave de acesso da NFe já que é um identificador único do documento. Como alternativa o sistema deve exibir um botão de buscar a NFe, abrindo o NFePicker.

• O sistema só deve permitir avançar para o próximo passo caso a NFe seja encontrada no sistema.
• Ao selecionar a NFe e confirmar a UI já deve validar se a NFe selecionada já está associada a outro lançamento. Cada NFe só deve ter um lançamento de pagamento. Não faz sentido ter a mesa NFe em múltiplos lançamentos e isso evita erros de lançamentos duplicados.
  • Caso o lançamento seja encontrado, notificar e questionar se gostaria de editar o lançamento já existente. A ideia é não permitir que o usuário complete todo o lançamento para só depois validar que este documento já está lançado, evitando esforço e perda de tempo.
• Se não paramos em validação, criar um novo lançamento e avançar para a tela de edição do "lançamento manual" com as seguintes condições:
  • A tela de edição não permitirá que a associação dessa NFe seja desfeita, embora permita a associação de outras NFes (para o caso de múltiplas NFes em um mesmo boleto). As NFes associadas adicionalmente poderão ser removidas.
  • A tela deve ler as informações dos campos de "Faturamento" do XML para obter o valor e as parcelas. Com essas informações já gerar os objetos de parcelamento.
  • Obter o Favorecido (PersonVO) pelo CNPJ da empresa e já deixar associado ao lançamento. Também desabilitar o campo para que não seja possível alterar/remover a associação do Favorecido.
    • Caso o PersonVO com o CNPJ não exista a UI deve gerar um novo objeto e já preenche-lo com todas as informações disponíveis no XML da NFe. Posteriormente ao confirmar o lançamento o Core deverá fazer o cadastro do PersonVO no BISCore antes de persistir o lançamento.
  • Ao tentar confirmar a tela deve validar:
    • Se os valores das parcelas lançadas para pagamento bate com o total da NFe.
    • Se a todas as NFes Associadas foram emitidas para a Empresa associada ao lançamento. Além de evitar fraude, e pagamento de NFes que não são da empresa, evita o erro de pagamento de uma NFe emitida para uma empresa ser paga por outra.

      • No futuro, confirmar se as NFes de uma filial podem ser pagas na conta da Matriz (e vice-versa). Caso não tenha nenhum problema contábil nessa ação essa validação precisará ser alterada para verificar apenas o prefixo do CNPJ, permitindo filiais diferentes.

Cuidado com os Totais O sistema em geral deve tomar cuidado com os totais apresentados na NFe e os valores a pagar. A NFe pode apresentar um valor no seu campo total e nem por isso é o valor correto a ser pago. Isso porque produtos em uma mesma NFe podem ter CFOP diferentes, alguns de venda, outros de troca, brinde, amostra, comodato, etc.. Talvez no futuro seja "legal" criar algum sistema que valide o CFOP e o valor sendo pago, mesmo que só para um alerta, já que algumas notas são pagas em dinheiro e nem sempre o recebedor se atenta (ou se quer sabe) sobre o CFOP bonificado no meio da nota. Permitindo que o entregador aja de má fé e não seja descoberto. O problema é gerenciar os milhares de CFOPs existentes.

Lançamento com Código de Barras

Lançamento de Débito Financeiro a Partir de Código de Barras de Guias

Quando o usuário digitar (ou ler no leitor o código de barras) o sistema deve identificar e descobrir o tipo de documento que foi lido. Para cada tipo de documento teremos um tratamento diferenciado.

Para validar e descobrir o tipo de informação passada, se é um código de barras ou a representação numérica, e se é um boleto ou uma guia de "arrecadação", verifique a sugestão de algorítimo em Especificação de Guias e Boletos.

Boletos

Caso seja um Boleto, devemos tentar extrair as informações do boleto utilizando o método da classe Utils que extrai o máximo de informações possíveis do código de barras. (Clique aqui para ver a especificação). Avançar para a tela de lançamento manual e executar as seguintes ações:

• Se a informação de agência e conta foram extraídas:
  • Procuramos no banco de dados se sabemos quem é o dono (PersonVO) desta conta corrente, através do PersonBankDataVO. Se encontramos, definimos o Favorecido automaticamente e o deixamos desabilitado. Afinal os dados bancários pertencem àquela empresa. Mudar o Favorecido fará com que o core não permita a inserção.
• Deixar o Tipo de Pagamento como "Unico"
• Definir o valor código de barras do boleto no campo adequado, e executar todas as definições da tela de entrada manual para este campo. Provavelmente já no evento de onChange, ou chamar o método específico.

Arrecadação

Caso seja uma guia de arrecadação, devemos tentar extrair as informações do boleto utilizando o método da classe Utils que extrai o máximo de informações possíveis do código de barras. (Clique aqui para ver a especificação).

• Caso o nome do Órgão/Empresa seja conhecido pelo sistema, defini-lo como sugestão no campo Descrição. Veja em: Lista de Identificações Conhecidas.
• Deixar o Tipo de Pagamento como Único;
• Definir o valor código de barras do boleto no campo adequado, e executar todas as definições da tela de entrada manual para este campo. Provavelmente já no evento de onChange, ou chamar o método específico.

Lançamento de DARF

Ao clicar em DARF a tela de lançamento deve se assemelhar à um DARF, facilitando que o usuário identifique os campos da guia na hora de lança-los na tela. Obviamente evitando erros de interpretação e facilitando o treinamento de novos funcionários. Internamente faremos a associação dos campos da guia com os do VO da seguinte forma:

• companyvo - O relacionamento de empresa deve ser completado com a empresa selecionada no campo "01 Identificação (Empresa)". (Campo 01)

Campos do InstallmentVO

• accrualdate - Período de Apuração (Campo 02)
• cpfcnpj - CPF ou CNPJ (Campo 03)
• slipcode - Código da Receita (Campo 04)
• idnumber - Número de Referência (Campo 05)
• limitdate - Data de Vencimento (Campo 06)
• originalvalue - Valor do Principal (Campo 07)
• valuepenalty - Valor da Multa (Campo 08)
• valuediscount - Valor do Juros Encargos (Campo 09) - Embora o campo do VO seja destinado a aplicação de desconto, para o DARF vamos utilizar este campo para os Juros. Evitamos assim de criar um novo campo específico para guardar este valor já que o DARF não prevê descontos em sua guia.
• valuefinal - Valor Total (Campo 10)

Tela de Lançamento de Débito tipo DARF

A tela terá as seguintes regras:

• O lançamento de DARF será sempre do tipo "Único", sem múltiplas parcelas.
• No Campo 01: Identificação (Empresa): a tela deve exibir a lista de empresas do sistema. No caso do sistema ter apenas uma única empresa, a tela já deve deixa-la selecionada e desabilitar o campo.
• No Campo 03: O Campo CPF ou CNPJ deve ser completado automaticamente com o CNPJ da empresa selecionada no campo 01. Deve ficar constantemente desabilitado. Nunca sendo preenchido pelo usuário.

  Embora uma guia DARF possa ter um CPF lançado no Campo 03, até o momento desconheço uma guia com CPF que seja de obrigação de pagamento da empresa.

• O campo código da Receita é um valor de apenas 4 dígitos inteiros e positivos. Zeros não significativos (zeros a esquerda) devem ser salvos.

  Criar um DataHandler que valide se o código informado é válido para recolhimento com CNPJ. Há uma lista [aqui] com os códigos de receita passíveis de recolhimento por PJ.

• O número de Referência não é obrigatório, há guias sem o mesmo.

  Não encontrei nenhuma especificação sobre o mesmo, mas tenho uma guia cujo número apresenta o formato "xxxxx-­xxxxxx/xxxx-­xx". Criar um DataHandler que formate e valide os números no formato passado caso o tamanho seja igual a 17. Caso alguma guia tenha uma quantidade de números diferentes deixar o cliente reclamara para tomarmos conhecimento de outro tipo de numeração que este campo pode ter.

• O Campo Valor Total deve permanecer desabilitado, e ser sempre o resultado da soma dos campos Valor Principal, Valor da Multa e Valor dos Juros/Encargos.

Aba de Anexos: Sem Anexos

Aba de Anexos: Com Anexos

• A segunda aba "Anexos" terá os componentes para permitir os anexos. Tanto a guia de pagamento (documento), como o Comprovante.
• Embora os VO de Statement esteja preparado para receber múltiplos documentos anexos, o Lançamento do tipo DARF será restrito à apenas um documento anexado (a Guia). Também não será permitido anexar nenhuma NFe.
• Ambos os anexos se comportarão da mesma maneira:
  • Enquanto não houver um documento anexado, o componente deverá exibir a mensagem "Nenhuma guia anexada!"/"Nenhum comprovante anexado!".
  • O usuário poderá anexar o documento/comprovante clicando no botão "Enviar Arquivo" correspondente, ou arrastando o arquivo para o componente correto.

    Aplicar a mesma regra de upload descrita na sessão de Lançamento Manual.

  • Quando o documento estiver anexado o componente deve exibir a mensagem "Guia anexada!"/"Comprovante anexado!" e exibir três botões:
    • Visualizar: Abrirá um popoup tento exibir o documento no browser do usuário;
    • Baixar Arquivo: Iniciará o download do documento automaticamente, evitando que o browser tente abri-lo.
    • Excluir: Excluirá o documento. Não só a associação como excluirá do banco também.
      • O botão excluir deve exibir uma mensagem de confirmação.
  • Uma vez que já tenhamos o documento anexado, o Drag'n'Drop deve exibir uma mensagem solicitando confirmação de que o arquivo será substituído pelo novo.

Lançamento de GPS (INSS)

A GPS (INSS) tem um funcionamento bem similar ao DARF. A tela terá uma aparência similar a GPS para facilitar o preenchimento e a vida dos novos usuários. Informações sobre o preenchimento da GPS podem ser encontradas [aqui].

Lançamento de GPS

A associação dos campos entre o VO e os campos da GPS serão:

• companyvo - "Identificação (Empresa)" O relacionamento de empresa deve ser completado com a empresa selecionada. (Campo 01)
• limitdate - Data de Vencimento (Campo 02)
• dispalyline - Campo de Descrição
• slipcode - Código de Pagamento (Campo 03)
• accrualdate - Competência (Campo 04)
• idnumber - Identificador (Campo 05) - Pode ser: CNPJ / CEI / NIT / PIS / PASEP
  • CNPJ (Cadastro Nacional da Pessoa Jurídica): XX.XXX.XXX/XXXX-XX (14)
  • CEI (Cadastro Específico do INSS): XX.XXX.XXXXX/XX (12)
  • NIT (Número de Identificação do Trabalhador): XXX.XXXXX.XX-X (11)
  • PIS (Programa de Integração Social): É o mesmo número do NIT
  • PASEP (Programa de Formação do Patrimônio do Servidor Público): É o mesmo Número do NIT
• originalvalue - Valor do INSS (Campo 06)
• valuepenalty - Valor de Outras Entidades (Campo 09)
• valuediscount - ATM/Multas e Juros (Campo 10)
• valuefinal - Valor Total (Campo 11)

Regras de funcionamento da Tela:

• Caso o sistema tenha apenas 1 única empresa cadastrada, o Campo 01 - Identificação (Empresa) deve seleciona-la automaticamente e ser desabilitado.
• Sempre que uma empresa for selecionada, o Campo 05 - Identificador deve ser completado com o CNPJ.

  Suspeito que algumas empresas usem o CEI, mas ainda não confirmei nenhuma. Caso encontre alguma no futuro, podemos ter uma configuração do sistema que defina que o identificador sugerido deverá ser o CEI ao invés do CNPJ. E obviamente temos de criar um campo para definição do CEI no cadastro da empresa.

• O código de pagamento é um numero inteiro de 4 dígitos. Zeros não significativos devem ser guardados. O código digitado deve ser validado de acordo com esta [lista]. A princípio os códigos válidos podem ser definidos diretamente no código, para evitar uma complexidade maior (e só com essa finalidade) de cadastra-los no banco.
• O campo competência aceita apenas o formato MM/AAAA. Diferentemente do campo da DARF que incluí o dia. No entanto, há ainda a questão de que a GPS aceita a competência "13/AAAA" usada para recolhimentos provenientes de 13° salário. Como não há como definir o mês 13 no DatePopupComponent, será usado um BISTextField com um DataHandler específico.

  Como o campo no VO, o accrualdate, é um date e o campo competência da GPS não inclui o dia. A sugestão de armazenamento seria manipular o campo "dia" no DataHandler do campo. Todos os meses de competência terão o dia definidos como 01. No entanto, quanto a competência for 13, usaríamos a data fixa de 31/12/AAAA.

• O campo Valor Total deverá ser a soma dos campos Valor do INSS, Valor de Outras Entidades e ATM/Multa e Juros. E deverá sempre estar desabilitado.
• A aba de anexos segue a mesma lógica e funcionalidade da aba Anexos da Guia DARF.

Lançamento de GPS - Aba Anexos