AdiantamentoCliente

Rotina do módulo Financeiro responsável por registrar o “Adiantamento de cliente” — um lançamento de contas a receber que antecipa valores recebidos de um participante (cliente) antes da geração/vinculação de um título formal, gerando automaticamente os lançamentos financeiros e contábeis correspondentes.

Rotina do módulo Financeiro responsável por registrar o “Adiantamento de cliente” — um lançamento de contas a receber que antecipa valores recebidos de um participante (cliente) antes da geração/vinculação de um título formal, gerando automaticamente os lançamentos financeiros e contábeis correspondentes. É uma tela filha do grupo de menu “Transferências” (recurso pai 1554).

Regra 1 — Filial e carteira são obrigatórias. Se a filial ou a carteira não forem informadas, a operação é bloqueada.

Regra 2 — Carteira deve pertencer à mesma filial do título. A carteira informada precisa pertencer à mesma filial informada para o título, a menos que a carteira seja do tipo Caixa (nesse caso a validação é dispensada).

Regra 3 — A filial informada na tela é substituída pela filial logada do usuário. Independentemente do que for digitado no campo de filial, o sistema sempre grava a filial do usuário logado no momento da operação.

Regra 4 — Forma de cobrança é obrigatória. Como este fluxo sempre opera em Contas a Receber, é obrigatório informar uma forma de cobrança; caso contrário a operação é bloqueada.

Regra 5 — Toda a operação ocorre dentro de uma transação única. O sistema abre uma transação (BeginTran) antes de processar o adiantamento e só confirma (Commit/FinalizeTran) ao final — se qualquer etapa falhar, nada é persistido.

Regra 6 — Existem dois sub-fluxos de persistência, conforme o adiantamento é pago com cheque de terceiro ou não.

• Com cheque(s) de terceiro(s) informado(s): para cada cheque, o sistema gera a numeração do documento e, por este ser um adiantamento de cliente, usa a série e o número informados pelo próprio usuário na tela para o cheque (diferente do fluxo de fornecedor, em que série/número seriam gerados automaticamente). São criados dois títulos a receber (um para o adiantamento, outro para o cheque), o registro do cheque em si, e duas movimentações financeiras (um crédito referente ao adiantamento e um débito referente à inclusão do cheque) — ambas ficam disponíveis para a integração contábil.
• Sem cheque de terceiro (em carteira): o sistema gera a numeração do documento; se não for encontrada uma sequência de numeração ativa para a filial e o tipo de documento, a mensagem de erro abaixo é apresentada, mas o processamento continua normalmente mesmo assim (o erro não interrompe a operação).
  Mensagem exibida: “Não foi encontrada uma sequencia de numeração ativa para a filial [ID da filial] e documento [ID do tipo de documento])”

Em seguida é criado um único título a receber (usando o valor do próprio título, e não o valor de algum cheque) e duas movimentações — uma de crédito ligada ao adiantamento e uma de débito ligada ao banco — mas apenas a movimentação de crédito do adiantamento é enviada para a integração contábil (a movimentação bancária não entra na lista de integração contábil neste sub-fluxo).

Regra 7 — Falha inesperada durante a inclusão. Se ocorrer qualquer erro não tratado durante o processamento, a operação é interrompida e a mensagem abaixo é exibida, contendo o detalhe técnico do erro ocorrido:

Regra 8 — Ausência de títulos a processar impede o salvamento. Se a tela enviar a requisição sem nenhum título na lista de títulos a processar, o sistema não chama a regra de negócio e apresenta a mensagem abaixo:

Observação de escopo: este fluxo é exclusivo de Contas a Receber (o controller sempre invoca o serviço com o módulo “tcReceber” e com o indicador de adiantamento de cliente sempre verdadeiro). O fluxo equivalente de adiantamento de fornecedor (Contas a Pagar) existe no mesmo serviço de negócio, mas pertence a outra rotina e não faz parte desta documentação.

Esta seção detalha, em nível técnico, onde e como o adiantamento de cliente é efetivamente gravado no banco de dados, e como ele é posteriormente compensado (baixado) contra um título real. O objetivo de negócio da rotina é sempre o mesmo: gerar um lançamento no caixa/banco e, ao mesmo tempo, um título a receber em aberto que representa o valor antecipado — título esse que fica “pendurado” até ser compensado, no futuro, com um título a receber de verdade (por exemplo, oriundo de uma venda ou fatura).

Tabelas envolvidas

Ou seja: a tabela “tbMovtoFin” mencionada na solicitação corresponde exatamente à tabela TBMOVTOFIN (movimentação financeira), e “tbMovtoCtb” corresponde à tabela TBMOVTOCTB (movimentação contábil) — ambas confirmadas no mapeamento de dados do sistema (arquivos “MapeamentoDeMovimentacaoFinanceira.cs” e “MapeamentoDeMovimentacaoContabil.cs”).

Fato contábil utilizado

Cada movimentação financeira gravada carrega um “fato contábil” (o código que a contabilidade usa para saber qual regra de lançamento contábil aplicar). Os fatos contábeis utilizados por esta rotina são:

• ADIANTAMENTO (código “TRECAD”, variação “Sem Variação”) — usado na movimentação de crédito ligada ao título de adiantamento, no sub-fluxo sem cheque de terceiros (o caso mais comum: “gerar lançamento no caixa e um título”).
• TRANSFERENCIA (código “BCOTRNF”, variação “Adiantamento”) — usado na movimentação de débito ligada ao banco/caixa, no mesmo sub-fluxo sem cheque de terceiros — é o lançamento que representa a entrada do dinheiro no caixa/banco.
• ADIANTAMENTO (código “TRECAD”, variação “Cheque de Terceiros”) e INCLUSÃO (código “TRECINC”, variação “Cheque de Terceiros”) — usados, respectivamente, na movimentação de crédito do adiantamento e na movimentação de débito da inclusão do cheque, no sub-fluxo com cheque de terceiros.

Lógica de gravação em TBMOVTOFIN e TBMOVTOCTB

1. É gerada uma chave de fato (idIntegracao) única para a operação — essa chave amarra o título, todas as movimentações financeiras e o lançamento contábil entre si.
2. O título de adiantamento é criado e gravado em TBTITULOREC com status “Aberto”.
3. São criadas as movimentações financeiras (uma de crédito e uma de débito, conforme o fato contábil de cada uma — ver seção anterior) e gravadas em TBMOVTOFIN, cada uma gravada com a chave de fato, o número do lançamento (numLancto) e seu respectivo fato contábil.
4. No sub-fluxo sem cheque de terceiros, apenas a movimentação de crédito (ligada ao adiantamento) é enviada para a integração contábil — a movimentação de débito do banco/caixa não gera lançamento em TBMOVTOCTB neste sub-fluxo. Já no sub-fluxo com cheque de terceiros, as duas movimentações (crédito do adiantamento e débito da inclusão do cheque) são enviadas para a integração contábil.
5. A integração contábil (responsável por gravar em TBMOVTOCTB) recebe a lista de movimentações financeiras marcadas para integração e gera, para cada uma, o lançamento contábil correspondente em TBMOVTOCTB, refletindo o fato contábil de cada movimentação.
6. Toda a sequência (título, cheque quando houver, movimentações financeiras e integração contábil) ocorre dentro de uma única transação — se qualquer etapa falhar, nada é persistido (ver Regra 5).

Compensação do adiantamento (baixa futura)

O título de adiantamento é gravado propositalmente com status “Aberto”: ele representa um valor recebido antecipadamente, mas ainda não vinculado a nenhuma venda/fatura real. A baixa (compensação) desse título não é feita por esta rotina, e sim por uma rotina irmã, específica para isso: “Compensação de Recebimento x Adiantamento de Cliente” (tela de Extra-Caixa > Compensações).

Nessa rotina de compensação, o sistema:

• Localiza o título de adiantamento em aberto e um título a receber real (de venda/fatura) do mesmo cliente.
• Usa o fato contábil LIQUIDAÇÃO (código “TRECLIQ”, variação “Compensação de Adiantamento”) para gerar o lançamento financeiro e contábil da baixa — ou seja, um novo registro em TBMOVTOFIN (e o respectivo reflexo em TBMOVTOCTB) que baixa o valor do adiantamento contra o título real.
• Ao final, o título de adiantamento deixa de estar em aberto (é compensado/baixado) e o título real recebido é quitado (total ou parcialmente) pelo valor do adiantamento.

Em resumo: esta rotina (Adiantamento de Cliente) cria a “ponta de entrada” da antecipação — o dinheiro no caixa/banco e o título em aberto —, e a rotina de Compensação cria a “ponta de saída” — a liquidação desse título em aberto contra um título a receber real, fechando o ciclo da antecipação.

Acesso à rotina: “EditViewDeAdiantamentoCliente” (ID 1555, recurso pai: 1554 – Transferências)