Inclusão de Desconto no Pagamento
PagamentoInclusaoDeDesconto
Esta rotina pertence ao módulo Financeiro, dentro da área de Pagamento, e é responsável por processar o desconto concedido sobre um ou mais títulos a pagar no momento da liquidação (pagamento) desses títulos.
Visão Geral
Esta rotina pertence ao módulo Financeiro, dentro da área de Pagamento, e é responsável por processar o desconto concedido sobre um ou mais títulos a pagar no momento da liquidação (pagamento) desses títulos. Ela grava a movimentação financeira e os lançamentos contábeis correspondentes ao valor do desconto, e também disponibiliza a impressão do comprovante da operação.
Endpoints
POST /PagamentoInclusaoDeDesconto/Salvar
Processa o desconto sobre um ou mais títulos a pagar informados. Para cada título, o sistema primeiro confirma que ele não está bloqueado; em seguida, calcula e grava o valor do desconto (em moeda nacional e, quando aplicável, em moeda estrangeira), gera a movimentação financeira e os lançamentos contábeis decorrentes, e retorna essas movimentações para exibição.
Permissão: “EditViewDeTitulosParaAlteracaoTPAGDESC” (ID 1582) — tela “Desconto”, uma das telas de alteração de títulos a pagar agrupadas sob “Pagamento” (ID 1575, item de menu sem permissão própria — apenas agrupa as telas filhas).
Parâmetros (corpo da requisição, objeto DTOCabecalhoDeOperacoes):
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| TitulosAProcessar | Lista de títulos | Sim | Lista dos títulos a pagar que vão receber o desconto. Cada item traz o identificador do título e os valores de desconto. Se vier vazia ou não informada, a operação não é executada. |
| GeraLanctosIndependentes | Texto (“S” ou outro valor) | Não | Indica se cada título deve gerar um lançamento contábil independente (uma “chave de fato” própria) ou se todos os títulos da lista compartilham o mesmo lançamento. |
| ValorCotacao | Numérico | Condicional | Cotação da moeda estrangeira usada para converter o desconto informado em moeda estrangeira para o valor equivalente em moeda nacional. Necessário quando o título tem desconto em moeda estrangeira. |
| EhLiquidacaoMoedaExtrangeira | Verdadeiro/Falso | Não | Indica se a liquidação envolve moeda estrangeira; quando verdadeiro, o sistema também registra a movimentação de variação cambial do título. |
Campos de cada item da lista TitulosAProcessar (objeto DTODeTituloAProcessar):
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| ID | Texto | Sim | Identificador do título a pagar que vai receber o desconto. |
| Desconto | Numérico | Condicional | Valor do desconto em moeda nacional. Usado quando o título não tem desconto em moeda estrangeira. |
| DescontoMoeda | Numérico | Condicional | Valor do desconto em moeda estrangeira. Quando maior que zero, tem prioridade sobre o campo “Desconto”: o sistema converte esse valor para moeda nacional usando a cotação informada (ValorCotacao). |
“` POST /PagamentoInclusaoDeDesconto/Salvar { “TitulosAProcessar”: [ { “ID”: “12345”, “Desconto”: 50.00, “DescontoMoeda”: 0 } ], “GeraLanctosIndependentes”: “N”, “EhLiquidacaoMoedaExtrangeira”: false } “`
“`json { “success”: true, “listaDeOperacoesFinanceiras”: [], “listaDeOperacoesContabeis”: [] } “`
POST /PagamentoInclusaoDeDesconto/Imprimir
Ação de apoio, sem regra de negócio: prepara o arquivo de modelo do comprovante de pagamento (relatório “Comprovante.rpt”) na pasta de documentos do cliente, copiando o modelo padrão do sistema caso o arquivo ainda não exista nessa pasta. Não recebe parâmetros e apenas garante que o modelo esteja disponível para a geração do comprovante da operação.
Permissão: coberta pela mesma permissão da tela, “EditViewDeTitulosParaAlteracaoTPAGDESC” (ID 1582) — não há permissão granular própria para esta ação.
“` POST /PagamentoInclusaoDeDesconto/Imprimir “`
“`json { “success”: true } “`
Modelos de Dados
Os objetos DTOCabecalhoDeOperacoes e DTODeTituloAProcessar são estruturas de dados compartilhadas por várias rotinas da área de Pagamento (forma de pagamento, vencimento, decréscimo, desconto, juros, multa, remessa de arquivo). Por isso, cada um desses objetos possui muitos campos que não são utilizados pela ação Salvar desta rotina. A tabela abaixo lista apenas os campos efetivamente utilizados no processamento do desconto; os demais campos desses objetos pertencem a outras rotinas de pagamento e não têm efeito aqui.
| Campo | Objeto | Descrição |
|---|---|---|
| TitulosAProcessar | DTOCabecalhoDeOperacoes | Lista dos títulos a receber desconto nesta execução. |
| GeraLanctosIndependentes | DTOCabecalhoDeOperacoes | Define se os lançamentos contábeis dos títulos da lista são independentes entre si ou compartilham a mesma chave de fato. |
| ValorCotacao | DTOCabecalhoDeOperacoes | Cotação usada para converter o desconto em moeda estrangeira para moeda nacional. |
| EhLiquidacaoMoedaExtrangeira | DTOCabecalhoDeOperacoes | Indica se a operação envolve moeda estrangeira. |
| ID | DTODeTituloAProcessar | Identificador do título a pagar. |
| Desconto | DTODeTituloAProcessar | Valor do desconto em moeda nacional. |
| DescontoMoeda | DTODeTituloAProcessar | Valor do desconto em moeda estrangeira. |
Regras de Negócio
- Título bloqueado impede o desconto: antes de processar cada título da lista, o sistema verifica se ele está bloqueado. Se estiver, a operação é interrompida para aquele título e a seguinte mensagem é exibida:Mensagem exibida: “O desconto não pode ser concluído pois os títulos não podem estar bloqueados. O título [identificador do título] está bloqueado.”
- Lista de títulos vazia não é processada: se nenhum título for informado na requisição (lista vazia ou não enviada), a operação não executa nenhum processamento e a seguinte mensagem é exibida:Mensagem exibida: “Não foi possível Salvar. Nenhum título foi informado. Verifique e informe título válido para operação”
- Lançamentos independentes não são permitidos com moeda estrangeira: se a opção de gerar lançamentos independentes por título estiver ativada ao mesmo tempo em que a operação envolve moeda estrangeira, a operação é bloqueada e a seguinte mensagem é exibida:Mensagem exibida: “Não foi possível Processar Títulos. Geração de lançamentos independentes não permitido quando há moeda estrangeira. Mude o parâmetro ‘Gerar lançamentos independentes’ para ‘N – Não’ e tente novamente.”
- Cálculo do valor do desconto: para cada título, se houver valor de desconto em moeda estrangeira (DescontoMoeda maior que zero), o valor lançado em moeda nacional é o resultado da conversão desse valor pela cotação informada (arredondado em duas casas decimais); caso contrário, é usado diretamente o valor informado no campo Desconto.
- Variação cambial: quando a operação é identificada como liquidação em moeda estrangeira, o sistema também registra, antes do lançamento do desconto, uma movimentação de variação cambial referente ao título.
- Efeito de persistência: para cada título processado com sucesso, o sistema grava a movimentação financeira do desconto e, ao final do processamento de toda a lista, executa a integração contábil dos lançamentos gerados. Toda a operação (todos os títulos da lista) ocorre dentro de uma única transação: se algo falhar durante o processamento, nenhuma parte da operação é persistida.
Permissões
Acesso à rotina: “EditViewDeTitulosParaAlteracaoTPAGDESC” (ID 1582) — tela “Desconto”, uma das telas de alteração de títulos a pagar agrupadas sob o item de menu “Pagamento” (ID 1575, sem permissão própria).
| Ação | Permissão | ID |
|---|---|---|
| Salvar | “EditViewDeTitulosParaAlteracaoTPAGDESC” | 1582 |
| Imprimir | coberta por “EditViewDeTitulosParaAlteracaoTPAGDESC” | — |