DS_COMPLEMENTO - Complemento por Tipo de Conta

Tela de configuração: TFC007 — Parâmetros de Complemento do Caixa Tabela: PARMCOMPLCAIXA.DS_COMPLEMENTO Tipo: DOM_VARCHAR240 NOT NULL Componente: edtDS_COMPLEMENTO (edit, texto livre) Valor padrão: Nenhum (preenchimento obrigatório ao cadastrar um registro)

Descrição

Define o modelo de texto (complemento) que será automaticamente preenchido no campo "Complemento" dos movimentos de caixa. O texto pode conter macros (placeholders) que são substituídas em tempo de execução por dados reais do processo financeiro (nome da pessoa, número do documento, datas, etc.).

Cada registro em PARMCOMPLCAIXA combina até 4 filtros — Tipo de Conta, Tipo de Documento, Tipo de Baixa e Tipo de Processo — para determinar qual complemento aplicar. A procedure RETORNA_PARMCOMPLEMENTOCAIXA busca a combinação mais específica primeiro e, se não encontrar, vai relaxando filtros progressivamente até a combinação mais genérica (todos os filtros nulos).

Campos Envolvidos

Campo	Tabela	Tipo	Descrição
DS_COMPLEMENTO	PARMCOMPLCAIXA	DOM_VARCHAR240	Texto-modelo com macros de substituição
ST_BLOQUEIO	PARMCOMPLCAIXA	DOM_CHAR1	Controla se o complemento pode ser editado pelo usuário no caixa (S = bloqueado, N = editável)
CD_TIPOCONTA	PARMCOMPLCAIXA	DOM_INTEGER	Filtro: tipo de conta (FK para TIPOCONTA)
TP_DOCUMENTO	PARMCOMPLCAIXA	DOM_VARCHAR2	Filtro: tipo de documento (ex: AV, NF, FT)
TP_BAIXA	PARMCOMPLCAIXA	DOM_CHAR1	Filtro: tipo de baixa (B=banco, X=caixa, T=cartão, I=incobrável)
TP_PROCESSO	PARMCOMPLCAIXA	DOM_CHAR1	Filtro: tipo de processo (P=pagamento, R=recebimento)

Macros Disponíveis

O texto informado em DS_COMPLEMENTO aceita as seguintes macros, substituídas automaticamente pelas procedures RETORNA_COMPLEMENTO e RETORNA_PARMCOMPLEMENTOCAIXA:

Macro	Substituída por	Exemplo
%N	Nome da pessoa (cliente/fornecedor)	"João da Silva"
%H	Descrição do histórico contábil	"Venda de mercadoria"
%D	Número do documento / parcela	"1234/1"
%NF	Número da nota fiscal	"5532"
%NC	Número do documento (contas)	"1234"
%SN	Série da nota fiscal	"1"
%NP	Número da parcela	"1"
%NT	Total de parcelas	"3"
%DL	Dia do lançamento	"15"
%ML	Mês do lançamento	"06"
%AL	Ano do lançamento	"2025"
%DV	Dia do vencimento	"20"
%MV	Mês do vencimento	"07"
%AV	Ano do vencimento	"2025"
%OC	Observação da conta	"Referente ao contrato 99"
%VC	Valor da conta (com contexto)	—
%TC	Tipo de conta (com contexto)	—
%BC	Banco/conta corrente (com contexto)	—
%AG	Agência (com contexto)	—

Lógica de Resolução (Hierarquia de Filtros)

A procedure RETORNA_PARMCOMPLEMENTOCAIXA faz uma busca em cascata, do mais específico para o mais genérico:

1. 4 filtros preenchidos — CD_TIPOCONTA + TP_DOCUMENTO + TP_BAIXA + TP_PROCESSO
2. 3 filtros preenchidos — Relaxa CD_TIPOCONTA, depois TP_DOCUMENTO, depois TP_BAIXA, depois TP_PROCESSO
3. 2 filtros preenchidos — Todas as combinações possíveis de 2 filtros
4. 1 filtro preenchido — Apenas um dos 4 filtros, os demais nulos
5. 0 filtros preenchidos — Registro "genérico" com todos os filtros nulos (fallback global)

Em cada passo, retorna o FIRST 1 registro encontrado.

Telas Impactadas

Tela	Impacto
Tela de Caixa (jCaixa)	Ao registrar um movimento, o sistema chama RETORNA_COMPLEMENTO que consulta PARMCOMPLCAIXA para preencher automaticamente o campo DS_COMPLEMENTO do movimento
Extrato de Caixa (LCX001)	O complemento resolvido aparece na coluna DS_COMPLEMENTO do extrato
Consulta Financeira (CFC002)	O complemento é exibido nos resultados de consulta de movimentos de caixa
Relatórios Contábeis (CCB001)	O complemento é utilizado como filtro e exibição em relatórios contábeis

Opções Disponíveis

DS_COMPLEMENTO é um campo de texto livre — não possui opções pré-definidas. A configuração é feita por registro, combinando os filtros da tabela PARMCOMPLCAIXA.

Exemplo 1 — Complemento genérico para recebimento

O que faz	Detalhe
Define um texto-modelo global para recebimentos	Todos os filtros nulos exceto TP_PROCESSO = R

Simulação passo a passo

1. Acesse a tela TFC007 — Parâmetros de Complemento do Caixa.
2. Clique em Incluir para criar um novo registro.
3. No campo Tipo de Processo, selecione R (Recebimento).
4. Deixe os campos Tipo de Conta, Tipo de Documento e Tipo de Baixa vazios (nulos).
5. No campo Complemento, digite: Recto %N - Doc %D.
6. No campo Bloqueio, selecione S para impedir edição pelo usuário no caixa.
7. Clique em Salvar.

Resultado esperado: Ao receber um pagamento no caixa para a pessoa "Maria Oliveira" com documento 500/parcela 1, o complemento será preenchido automaticamente como "Recto Maria Oliveira - Doc 500/1", e o campo ficará bloqueado para edição.

---

Exemplo 2 — Complemento específico para recebimento em banco de um tipo de conta

O que faz	Detalhe
Define complemento específico para um tipo de conta + baixa bancária + recebimento	CD_TIPOCONTA + TP_BAIXA = B + TP_PROCESSO = R

Simulação passo a passo

1. Acesse a tela TFC007 — Parâmetros de Complemento do Caixa.
2. Clique em Incluir para criar um novo registro.
3. No campo Tipo de Conta, selecione o tipo de conta desejado (ex: "Duplicata").
4. No campo Tipo de Baixa, selecione B (Banco).
5. No campo Tipo de Processo, selecione R (Recebimento).
6. Deixe o campo Tipo de Documento vazio.
7. No campo Complemento, digite: Recto Banco %N - NF %NF - Venc %DV/%MV/%AV.
8. Clique em Salvar.

Resultado esperado: Ao receber uma duplicata via banco para "João Santos" com NF 1200 e vencimento 15/08/2025, o complemento será "Recto Banco João Santos - NF 1200 - Venc 15/08/2025". Este registro tem prioridade sobre configurações mais genéricas.

---

Exemplo 3 — Complemento com bloqueio desligado (editável)

O que faz	Detalhe
Sugere um complemento mas permite edição manual	ST_BLOQUEIO = N

Simulação passo a passo

1. Acesse a tela TFC007 — Parâmetros de Complemento do Caixa.
2. Clique em Incluir para criar um novo registro.
3. Deixe todos os filtros vazios para criar um registro genérico (fallback).
4. No campo Complemento, digite: %H - %N.
5. No campo Bloqueio, selecione N.
6. Clique em Salvar.

Resultado esperado: Ao registrar qualquer movimento de caixa sem configuração mais específica, o complemento será preenchido com "Venda de mercadoria - Maria Oliveira", mas o operador poderá editar livremente o texto antes de confirmar.

Exceção / Importante: Quando ST_BLOQUEIO = S (bloqueado), o campo edtDS_COMPLEMENTO na tela do Caixa é definido como ReadOnly = True, impedindo alteração. Quando ST_BLOQUEIO = N, o campo permanece editável. Esse controle é feito em UdmCaixa.pas conforme retorno da procedure RETORNA_COMPLEMENTO.

Regra de Fallback

Se nenhum registro em PARMCOMPLCAIXA atender aos filtros, o sistema utiliza como fallback:

1. O campo DS_COMPLEMENTO da tabela TIPOCONTA (complemento configurado no próprio tipo de conta).
2. O campo DS_COMPLEMENTO da tabela PARMFINANC (complemento padrão dos parâmetros financeiros), configurado em DS_COMPLEMENTO (configurado em PARMFINANC, tabela de parâmetros financeiros).
3. Um texto montado automaticamente com o prefixo do tipo de operação (ex: "Pagto Banco", "Recto Caixa", "Baixa Duplicata Incobrável").

Nota: O parâmetro TP_COMPLEMENTO (configurado em PARMFINANC, tabela de parâmetros financeiros) influencia qual dessas fontes é utilizada: quando TP_COMPLEMENTO = 'T', o sistema busca o complemento de cada tipo de conta individualmente; quando TP_COMPLEMENTO = 'A', utiliza o complemento de PARMFINANC como fallback.

Procedures Impactadas

Rotinas Delphi com referência direta ao campo

Rotina	Arquivo	Descrição
TdmCaixa (movimento)	source/jCaixa/UdmCaixa.pas	Chama RETORNA_COMPLEMENTO ao registrar movimentos de caixa; controla bloqueio do campo
TdmFNC001.tabPARMFINANCAfterInsert	source/FNC001/UdmFNC001.pas	Inicializa DS_COMPLEMENTO de PARMFINANC com valor padrão '%N'

Procedures SQL com referência direta à tabela PARMCOMPLCAIXA

Procedure	Arquivo	Descrição
RETORNA_PARMCOMPLEMENTOCAIXA	Scripts/RETORNA_PARMCOMPLEMENTOCAIXA.sql	Busca o complemento em PARMCOMPLCAIXA com resolução em cascata (mais específico → mais genérico)
RETORNA_COMPLEMENTO	Scripts/RETORNA_COMPLEMENTO.sql	Procedure principal que chama RETORNA_PARMCOMPLEMENTOCAIXA, aplica macros e monta o texto final
RETORNA_COMPLEMENTOPROCESSO_MX	Scripts/RETORNA_COMPLEMENTOPROCESSO_MX.sql	Resolve tipo de conta, baixa e chama RETORNA_PARMCOMPLEMENTOCAIXA para cada movimento do processo
EXTRATO_CAIXA	Scripts/EXTRATO_CAIXA.sql	Utiliza DS_COMPLEMENTO de MOVTOCAIXA (resultado da resolução) na exibição do extrato

Candidatas por uso da tabela (referência indireta)

Procedure	Arquivo	Observação
GERA_INTEGRACAO	Scripts/GERA_INTEGRACAO.sql	Declara I_DS_COMPLEMENTO VARCHAR(240) — pode receber o complemento resolvido
GERA_MOVTOCONTABIL	Scripts/GERA_MOVTOCONTABIL.sql	Declara I_DS_COMPLEMENTO VARCHAR(500) — usa complemento na geração contábil
GERA_SPEDCONTABIL	Scripts/GERA_SPEDFCONT.sql	Declara V_DS_COMPLEMENTO — usa complemento em exportações fiscais

Tabela Comparativa Resumida

Situação	Filtros Preenchidos	Prioridade
Complemento ultra-específico	4 filtros (Tipo de Conta + Documento + Baixa + Processo)	1ª (mais alta)
Complemento parcial (3 filtros)	Qualquer combinação de 3	2ª
Complemento parcial (2 filtros)	Qualquer combinação de 2	3ª
Complemento parcial (1 filtro)	Qualquer combinação de 1	4ª
Complemento genérico (fallback local)	Nenhum filtro	5ª
Complemento do Tipo de Conta (TIPOCONTA.DS_COMPLEMENTO)	—	6ª
Complemento do Financeiro (PARMFINANC.DS_COMPLEMENTO)	—	7ª
Texto automático (prefixo de operação)	—	8ª (último recurso)