DS_MSGCONTRATO — Mensagem em Contratos

Tela de configuração: MFA001 — Parâmetros de Faturamento Localização: Parâmetros → aba Mensagens → grupo Mensagem Contrato Tabela: PARMFATUR.DS_MSGCONTRATO Tipo: Texto livre (VARCHAR(240)) — TDBMemo com MaxLength = 240 Valor padrão: vazio/NULL (não é preenchido no AfterInsert do dataset — ver UdmMFA001.pas linhas 434-509; o bloco de inicialização não referencia DS_MSGCONTRATO)

Telas impactadas

Módulo	Código	Papel
Parâmetros de Faturamento	MFA001	Tela de cadastro/edição do texto (produtora). Campo memoDS_MSGCONTRATO: TDBMemo em pagMENSAGEM/GroupBox2
Emissão de Mensalidades de Contrato	MNF010	Consumidor principal. Exibe o texto parametrizado no memCOMPLEMENTO da tela de processamento (UMSGMNF010.pas linhas 867-883) e o injeta na observação de cada NF gerada via procedure RETORNA_COMPLEMENTOCONTRATO (chamada em 5 variantes de SQL: UMNF010.pas linhas 1132, 1187, 1250, 1308, 1365, 1429)
Auditoria de Parâmetros	FER002	Exclui explicitamente DS_MSGCONTRATO das auditorias automáticas da PARMFATUR (6 blocos: UFER002.pas linhas 183, 247, 356, 421, 510, 654, 786, 837) — assim como demais campos Blob/Memo da tabela

Observação: o parâmetro não é lido pelos módulos de NF-e padrão (MNF001/MNF002), Pedido (MPD*) ou Orçamento. Ele é exclusivo do fluxo de contratos de mensalidade processados em MNF010.

Procedures impactadas

Procedure	Arquivo	Papel
RETORNA_COMPLEMENTOCONTRATO	Scripts/RETORNA_COMPLEMENTOCONTRATO.sql	USO PRINCIPAL. Recebe PF.DS_MSGCONTRATO no parâmetro I_DS_MSG e substitui macros (%N, %DL, %ML, %AL, %DV, %MV, %AV, %MV1, %AV1, %D, %CP) pelos dados do contrato/parcela; retorna o texto final truncado em 240 caracteres em O_DS_MSG

Campos envolvidos

Campo	Descrição
PARMFATUR.DS_MSGCONTRATO	Este parâmetro. Texto com até 240 caracteres, exibido como observação nas NFs geradas a partir de mensalidades de contrato
PARMFATUR.ST_VARIOSITENSCONTRATO	Parâmetro irmão lido no mesmo SELECT da tela MNF010 (UMSGMNF010.pas linha 873). Define se a NF gerada deve agrupar vários itens do contrato
PARMFATUR.DS_MENSAGEM	Mensagem padrão da Nota Fiscal (campo irmão em pagMENSAGEM) — ver DS_MENSAGEM
PARMFATUR.DS_MSGPEDIDO	Mensagem padrão do Pedido — ver DS_MSGPEDIDO
PARMFATUR.DS_MSGORCAMENTO	Mensagem padrão do Orçamento — ver DS_MSGORCAMENTO
CONTRATO.NR_CONTRATO	Usado na macro %D para compor "<parcela>/<total> - Contrato Nº <n>"
CONTRATO.DT_VENCTOPARCELA / DT_EMISSAO	Base das macros %DV/%MV/%AV (vencimento) e %DL/%ML/%AL (lançamento)
PESSOA.NM_PESSOA / CD_PESSOA	Resolvem as macros %N e %CP

---

Onde a mensagem aparece

O parâmetro tem um único fluxo de uso: gerar a observação das Notas Fiscais de mensalidade emitidas a partir de contratos (tela MNF010 — Emissão de Mensalidades de Contrato).

O texto digitado em MFA001 funciona como template — ele contém macros que são substituídas pelos dados reais de cada contrato/parcela no momento da geração da NF, pela procedure RETORNA_COMPLEMENTOCONTRATO.

1. Tela MNF010 — Processamento de Mensalidades

Ao abrir a janela Processando Mensalidades (frmMSGMNF010), o evento FormShow (UMSGMNF010.pas linhas 867-883) executa:

SELECT P.DS_MSGCONTRATO, P.ST_VARIOSITENSCONTRATO
FROM PARMFATUR P
WHERE P.CD_EMPRESA = <empresa da sessão>

O texto retornado é exibido no TMemo memCOMPLEMENTO, rotulado como "Complemento para Observação (MFA001)" (ver UMSGMNF010.dfm linha 39). O usuário pode editar o texto neste momento para aquela execução específica, mas o conteúdo persistido continua sendo o de PARMFATUR.

Simulação passo a passo

1. Em MFA001 → aba Mensagens → grupo Mensagem Contrato, digite em memoDS_MSGCONTRATO: Ref. mensalidade %D - %ML/%AL - Cliente %N
2. Salve (F6) e feche.
3. Abra MNF010 e acione Processar Mensalidades.
4. Na janela Processando Mensalidades, o campo Complemento para Observação (MFA001) abre pré-preenchido com Ref. mensalidade %D - %ML/%AL - Cliente %N.
5. Confirme (F6 — botão Gerar Mensalidades).

Resultado esperado: para cada parcela/NF gerada, a observação gravada passa pela procedure RETORNA_COMPLEMENTOCONTRATO, que resolve:

• %D → "1/12 - Contrato Nº 15" (parcela/total + número do contrato)
• %ML → nome do mês de lançamento por extenso (via MES_EXTENSO)
• %AL → ano de lançamento
• %N → nome do cliente (PESSOA.NM_PESSOA)

Texto final (exemplo para parcela 1/12 de um contrato do cliente "ACME LTDA", lançado em abril/2026): Ref. mensalidade 1/12 - Contrato Nº 15 - abril/2026 - Cliente ACME LTDA

---

2. Procedure RETORNA_COMPLEMENTOCONTRATO

Chamada em 5 variantes do SQL de MNF010 (com 6 ocorrências em UMNF010.pas: linhas 1132, 1187, 1250, 1308, 1365, 1429 — além de uma réplica no UdmMNF010.dfm linha 831), todas com o padrão:

LEFT JOIN RETORNA_COMPLEMENTOCONTRATO(PF.DS_MSGCONTRATO, PC.NM_PESSOA, <data_lancto>,
   CASE X.O_NR_LINHA
      WHEN 1 THEN C.DT_VENCTOPARCELA
      ELSE <data_vencto_calculada>
   END,
   C.NR_CONTRATO,
   x.O_NR_LINHA||'/'||(select max(o_nr_linha) from retorna_linhas(:nr_parcelas)),
   C.CD_PESSOA) OPS ON (1=1)

As variantes diferem apenas na data de lançamento passada:

• C.DT_EMISSAO (emissão do contrato — linhas 1132, 1308)
• Último dia do mês anterior ao vencimento (linhas 1187, 1365)
• Data de lançamento informada no filtro (tabFILTRODT_LANCAMENTO — linhas 1250, 1429)

Macros suportadas (ver RETORNA_COMPLEMENTOCONTRATO.sql linhas 20-84)

Macro	Substituição	Fonte
%N	Nome do cliente	PESSOA.NM_PESSOA (parâmetro I_NM_PESSOA)
%DL	Dia do lançamento	EXTRACT(DAY FROM I_DT_LANCTO)
%ML	Mês do lançamento por extenso	MES_EXTENSO(I_DT_LANCTO)
%AL	Ano do lançamento	EXTRACT(YEAR FROM I_DT_LANCTO)
%DV	Dia do vencimento	EXTRACT(DAY FROM I_DT_VENCTO)
%MV	Mês do vencimento por extenso	MES_EXTENSO(I_DT_VENCTO)
%AV	Ano do vencimento	EXTRACT(YEAR FROM I_DT_VENCTO)
%MV1	Mês do vencimento -1 por extenso	MES_EXTENSO(DATEADD(-1 MONTH, I_DT_VENCTO))
%AV1	Ano do vencimento -1	EXTRACT(YEAR FROM DATEADD(-1 MONTH, I_DT_VENCTO))
%D	Parcela + contrato	`I_DS_PARCELAS
%CP	Código da pessoa	I_CD_PESSOA

As macros dia/mês/ano literais (%DL/%ML/%AL/%DV/%MV/%AV) estão descritas nos próprios labels da aba Mensagens (UMFA001.dfm linhas 11897-11989) — lblMacroData, labelCompVencimento, labelCompDocto, lblMacroPessoa, Label49, lbl76, lbl77.

Resultado esperado: o retorno da procedure (O_DS_MSG) é truncado em 240 caracteres via SUBSTRING(V_DS_MSG FROM 1 FOR 240) (RETORNA_COMPLEMENTOCONTRATO.sql linha 87), mesmo limite físico do campo na PARMFATUR.

---

Regras de formatação

1. Tamanho máximo: 240 caracteres (MaxLength = 240 no TDBMemo / VARCHAR(240) em banco). Macros são expandidas antes do truncamento, então um texto com muitas macros pode ultrapassar 240 caracteres internamente — o excesso é cortado pelo SUBSTRING final.
2. Ordem de substituição importa: na procedure, %MV1/%AV1 são tratadas antes de %MV/%AV (linhas 49-73 de RETORNA_COMPLEMENTOCONTRATO.sql). Usar %MV em texto que contenha %MV1 funciona; o inverso também. Porém não existe tratamento equivalente para %ML1/%AL1/%DL1 — apenas vencimento tem variante -1.
3. Macros dia retornam inteiros sem zero à esquerda: %DL/%DV produzem "1", "2", ..., "31" (vêm de EXTRACT(DAY FROM ...)). Não há padding para dois dígitos.
4. Meses por extenso vêm em minúsculas: a procedure MES_EXTENSO retorna o nome em minúsculas (ex.: "abril"). Para capitalizar, digite a mensagem iniciando com letra maiúscula e evite começar a frase com %ML/%MV.
5. Macro %D já formata "Contrato Nº": digitar Ref. %D resulta em Ref. 1/12 - Contrato Nº 15. Não é preciso (nem recomendado) duplicar o prefixo "Contrato".
6. Macros não usadas permanecem literais: se a mensagem contiver %XY (macro inexistente), o texto %XY aparece como-está na observação final — a procedure só substitui as macros listadas.
7. O texto é editável na hora: o operador pode sobrescrever o conteúdo em memCOMPLEMENTO (MNF010) antes de gerar as NFs, mas as macros só são resolvidas pela procedure — logo, editar o texto manualmente não reexecuta a substituição; ele é usado conforme digitado.

---

Interação com DS_MENSAGEM / DS_MSGPEDIDO / DS_MSGORCAMENTO

Os quatro campos de mensagem da PARMFATUR coexistem na mesma aba Mensagens do MFA001 (ver UMFA001.dfm linhas 11785-12009):

Campo	Grupo na tela	Contexto de uso	Macros?
DS_MENSAGEM	Mensagem Nota Fiscal	Observação de toda NF emitida (RETORNA_OBSNOTA)	Não
DS_MSGPEDIDO	Mensagem Pedido	Observação de Pedidos	Não
DS_MSGORCAMENTO	Mensagem Orçamento	Observação de Orçamentos	Não
DS_MSGCONTRATO	Mensagem Contrato	Observação de NFs de mensalidade geradas em MNF010	Sim (11 macros)

Não há concatenação entre eles — cada campo é lido/aplicado em fluxos independentes. Uma NF gerada a partir de mensalidade de contrato (MNF010) terá a observação composta pela mensagem resolvida de DS_MSGCONTRATO e pela DS_MENSAGEM (via RETORNA_OBSNOTA), pois o fluxo de gravação passa pelas duas procedures.

Também diferentemente dos demais campos, DS_MSGCONTRATO tem contraparte comportamental: ST_VARIOSITENSCONTRATO, lido no mesmo SELECT do FormShow de MNF010 (UMSGMNF010.pas linha 873), que decide se a geração vai agrupar itens do contrato.

---

Referências no Código Fonte

Delphi

Arquivo	Linhas	Conteúdo
source/MFA001/UdmMFA001.pas	155	Declaração do field: tabPARMFATURDS_MSGCONTRATO: TStringField;
source/MFA001/UdmMFA001.pas	1236-1239	Definição do field em design-time (FieldName = 'DS_MSGCONTRATO', Size = 240)
source/MFA001/UdmMFA001.pas	161, 2389, 2552, 2768, 3041	Colunas em SELECT, INSERT e UPDATE da PARMFATUR no dataset tabPARMFATUR
source/MFA001/UdmMFA001.pas	434-509	TdmMFA001.tabPARMFATURAfterInsert — não inicializa DS_MSGCONTRATO (fica NULL ao criar novo registro)
source/MFA001/UMFA001.dfm	11884-11896	GroupBox2 com Caption = ' Mensagem Contrato '
source/MFA001/UMFA001.dfm	11897-11990	Labels das macros disponíveis (%DL, %ML, %AL, %DV, %MV, %AV, %MV1, %AV1, %D, %N, %CP)
source/MFA001/UMFA001.dfm	11991-12008	Componente memoDS_MSGCONTRATO: TDBMemo (DataField = 'DS_MSGCONTRATO', MaxLength = 240)
source/MFA001/UMFA001.pas	72	Declaração do componente memoDS_MSGCONTRATO: TDBMemo no form
source/MFA001/UMFA001.pas	1173-1179	Lógica de navegação por teclado: após memoDS_MSGCONTRATO, foco vai para pagLogo / btnAbrir
source/MNF010/UMSGMNF010.pas	867-883	FormShow lê P.DS_MSGCONTRATO e P.ST_VARIOSITENSCONTRATO da PARMFATUR, popula memCOMPLEMENTO.Lines.Text
source/MNF010/UMNF010.pas	1132, 1187, 1250, 1308, 1365, 1429	Chamadas LEFT JOIN RETORNA_COMPLEMENTOCONTRATO(PF.DS_MSGCONTRATO, PC.NM_PESSOA, ..., C.NR_CONTRATO, ..., C.CD_PESSOA) em 5 variantes do SQL de mensalidades
source/MNF010/UdmMNF010.dfm	831	Mesma chamada RETORNA_COMPLEMENTOCONTRATO(PF.DS_MSGCONTRATO, ...) em SQL embutido no dataset
source/FER002/UFER002.pas	183, 247, 356, 421, 510, 654, 786, 837	Exclusão de DS_MSGCONTRATO da auditoria automática da PARMFATUR (mesmo tratamento dado aos demais campos Memo/Blob)

SQL

Arquivo	Conteúdo
Scripts/RETORNA_COMPLEMENTOCONTRATO.sql	Procedure que recebe I_DS_MSG (valor de DS_MSGCONTRATO) e substitui as 11 macros (%N, %DL/ML/AL, %DV/MV/AV, %MV1/AV1, %D, %CP) pelos dados da parcela/contrato, retornando texto truncado em 240 caracteres