Liquidação de Contrato
LiquidacaoContrato
Rotina do módulo Financeiro responsável pela liquidação de contratos de câmbio: permite consultar contratos de câmbio em aberto, selecionar um ou mais contratos e/ou títulos para vincular, calcular os juros proporcionais quando aplicável ao modelo do contrato, gravar a liquidação e gerar os lançamentos contábeis e financeiros correspondentes.
Visão Geral
Rotina do módulo Financeiro responsável pela liquidação de contratos de câmbio: permite consultar contratos de câmbio em aberto, selecionar um ou mais contratos e/ou títulos para vincular, calcular os juros proporcionais quando aplicável ao modelo do contrato, gravar a liquidação e gerar os lançamentos contábeis e financeiros correspondentes.
Endpoints
GET /LiquidacaoContrato/ListarContratos
Lista os contratos de câmbio em aberto (status “A”) disponíveis para liquidação, calculando o saldo pendente de cada um e, quando aplicável ao modelo do contrato, o valor de juros proporcional até a data de movimentação informada. Aceita um texto livre de consulta (valorDeConsulta) que é comparado tanto como data quanto como texto contra os campos do contrato.
Permissão: coberta pela permissão de acesso à rotina “EditViewDeLiquidacaoDeContratoBuscaContratos” (ID 3107)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| valorDeConsulta | string | Não | Texto livre de busca; comparado como data ou como texto contra os campos do contrato |
| dataMovimentacao | DateTime | Sim | Data de referência usada no cálculo dos dias de juros |
| (demais filtros de tela) | — | Não | Filtros adicionais de carteira/moeda conforme configuração da tela |
“` GET /LiquidacaoContrato/ListarContratos?valorDeConsulta=ACC001&dataMovimentacao=2026-09-01 “`
“`json { “Dados”: [ { “ID”: “123456789”, “Codigo”: “ACC001”, “Modelo”: “ACC”, “Saldo”: 15000.00, “ValorParaLancamentoDeJuros”: 45.20 } ] } “`
POST /LiquidacaoContrato/Salvar
Efetiva a liquidação dos contratos de câmbio (e, quando informados, dos títulos) selecionados pelo usuário: valida os dados enviados, calcula/confirma o valor de liquidação e os juros, gera os lançamentos contábeis específicos do modelo do contrato (ACC, ACE, TRV, NDF, NDFC, OPC, PPE, Pronto), atualiza o status do contrato para “Liquidado” e grava a movimentação financeira. Toda a operação ocorre dentro de uma transação (BeginTran/Commit/FinalizeTran); qualquer falha reverte todas as alterações.
Permissão: “LiquidacaoContrato/Salvar” (ID 3108)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| IDDaMoeda | short | Sim | Moeda da operação |
| IDDaCarteiraSelecionada | int | Sim | Carteira usada para a liquidação |
| ValorCotacao | decimal | Sim | Cotação usada no cálculo |
| DataDeLancamento | DateTime | Sim | Data do lançamento contábil/financeiro |
| TitulosAProcessar | List[DTODeTituloAProcessar] | Não | Títulos vinculados à liquidação |
| ContratosCambioAProcessar | List[DTODeContratoCambio] | Sim | Contratos de câmbio selecionados para liquidação |
| LiquidacaoSemContrato | bool | Não | Indica liquidação sem vínculo a contrato |
“` POST /LiquidacaoContrato/Salvar { “IDDaMoeda”: 2, “IDDaCarteiraSelecionada”: 10, “ValorCotacao”: 5.32, “DataDeLancamento”: “2026-09-09”, “ContratosCambioAProcessar”: [{ “ID”: “123456789”, “IDDoModelo”: “ACC” }], “LiquidacaoSemContrato”: false } “`
“`json { “Sucesso”: true } “`
GET /LiquidacaoContrato/ObterFiltrosDoXmlDeConfiguracaoDeContrato
Retorna os filtros de configuração (definidos em XML) usados para montar as opções de busca/consulta de contratos na tela de liquidação.
Permissão: coberta pela permissão de acesso à rotina “EditViewDeLiquidacaoDeContratoBuscaContratos” (ID 3107)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| (sem parâmetros de entrada específicos) | — | — | — |
“` GET /LiquidacaoContrato/ObterFiltrosDoXmlDeConfiguracaoDeContrato “`
“`json { “Filtros”: [] } “`
GET /LiquidacaoContrato/Imprimir
Gera a impressão/relatório da liquidação de contrato realizada.
Permissão: coberta pela permissão de acesso à rotina “EditViewDeLiquidacaoDeContratoBuscaContratos” (ID 3107) — [informação não disponível na análise de código — validar com analista/vídeo do sistema se existe permissão granular própria para esta ação]
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| (parâmetros de identificação da liquidação a imprimir) | — | Sim | [informação não disponível na análise de código — validar com analista] |
“` GET /LiquidacaoContrato/Imprimir?id=123456789 “`
“` [arquivo/relatório binário ou HTML de impressão] “`
Modelos de Dados
DTODeCabecalhoLiquidacaoFatura (corpo enviado por Salvar)
| Campo | Tipo | Descrição |
|---|---|---|
| IDDaMoeda | short | Moeda da operação |
| IDDaCarteiraSelecionada | int | Carteira selecionada |
| ValorCotacao | decimal | Cotação usada no cálculo |
| DataDeLancamento | DateTime | Data do lançamento |
| TitulosAProcessar | List[DTODeTituloAProcessar] | Títulos vinculados |
| ContratosCambioAProcessar | List[DTODeContratoCambio] | Contratos selecionados |
| LiquidacaoSemContrato | bool | Indica liquidação sem contrato vinculado |
DTODeContratoCambio (principais campos usados na liquidação)
| Campo | Tipo | Descrição |
|---|---|---|
| ID | string | Chave de fato do contrato |
| IDDoTipo | string | Tipo do contrato |
| IDDoModelo | string | Modelo do contrato (ACC, ACE, TRV, NDF, NDFC, OPC, PPE, Pronto) |
| Codigo | string | Código do contrato de câmbio |
| DataAbertura | DateTime? | Data de abertura |
| DataVencimento | DateTime? | Data de vencimento |
| DataEntregaDocs | DateTime? | Data de entrega de documentos |
| Valor | decimal? | Valor do contrato |
| ValorMoeda | decimal? | Valor do contrato em moeda estrangeira |
| Juros | decimal? | Percentual de juros do contrato |
| ValorCotacao | decimal? | Valor da cotação |
| IDDoStatus | string | Status do contrato (ex: “A” = Aberto) |
| Observacao | string | Observação |
| IDDaMoeda | short? | Moeda |
| ValorVinculadoMoeda | decimal? | Valor já vinculado em moeda |
| PrazoVencimento | int? | Prazo de vencimento em dias |
| DataCredito | DateTime? | Data de crédito |
| ValorLiquidadoMoeda | decimal? | Valor já liquidado em moeda |
| ValorParaLancamentoDeJuros | decimal | Valor de juros calculado para o lançamento |
| SaldoAVincular | decimal? | Saldo ainda a vincular |
| SaldoALiquidar | decimal? | Saldo ainda a liquidar |
Regras de Negócio
- Contratos elegíveis para liquidação: apenas contratos com Status = “A” (Aberto) e saldo pendente maior que zero são retornados pela consulta de listagem. O saldo é calculado como Valor em moeda menos o Valor liquidado em moeda (ou o Valor vinculado em moeda, dependendo do modo de consulta configurado).
- Busca livre por texto ou data: o parâmetro valorDeConsulta é comparado tanto como data quanto como texto contra os campos do contrato, permitindo que o usuário digite tanto um código/observação quanto uma data para localizar o contrato desejado.
- Cálculo de juros proporcional (aplica-se apenas a modelos com juros aplicável, ex: ACC/ACE/TRV): os dias de juros são obtidos a partir do dia da data de movimentação (qtdeDias = dataMovimentacao.Day), ajustado quando a Data de Crédito do contrato cai no mesmo mês/ano da data de movimentação. A fórmula aplicada é: taxaDivisao = arredondar(TaxaDeJuros / 360, 9); taxaMultiplicada = arredondar(arredondar(taxaDivisao * qtdeDias, 9) / 100, 9); ValorParaLancamentoDeJuros = arredondar(taxaMultiplicada * Saldo, 2) quando TaxaDeJuros for diferente de zero; caso contrário, o valor de juros é zero.
- Transação atômica na gravação: toda a operação de liquidação (Salvar) ocorre dentro de uma transação (BeginTran/Commit/FinalizeTran). Se qualquer validação ou gravação falhar, todas as alterações da operação são revertidas — nenhum contrato fica parcialmente liquidado.
- Valor de liquidação inválido: se o valor informado para liquidação for inválido (ex: zero, negativo ou incompatível com o saldo do contrato), a operação é bloqueada.Mensagem exibida: “Valor de liquidação inválido” (mensagem associada ao método VALOR_DE_LIQUIDACAO_INVALIDO_SVOWR em Portugues.cs — [informação não disponível na análise de código — o texto completo de Erro/Motivo/Solução deste método específico deve ser validado com o analista, pois não foi possível confirmar a íntegra dos três campos durante a análise]).
- Cálculo do saldo do contrato: o saldo utilizado tanto na listagem quanto no cálculo de juros é ValorMoeda menos ValorLiquidadoMoeda (ou ValorVinculadoMoeda, conforme o modo de consulta), refletindo o quanto ainda resta a liquidar/vincular naquele contrato.
- Valor inválido para liquidar o contrato: se o valor informado para liquidar um contrato específico não for compatível com as regras de validação da tela, a gravação é bloqueada.Mensagem exibida: mensagem associada ao método VALOR_INVALIDO_PARA_LIQUIDAR_O_CONTRATO__VKGXC em Portugues.cs — [informação não disponível na análise de código — texto literal completo deve ser validado com o analista].
- Falha genérica ao salvar: se os dados enviados estiverem incorretos ou incompletos e não se enquadrarem em nenhuma validação específica anterior, a gravação é bloqueada com uma mensagem genérica.Mensagem exibida: Erro: “Não foi possível Salvar” / Motivo: “Os dados informados podem estar incorretos” / Solução: “Verifique se os dados informados estão corretos.” (mensagem associada ao método NAO_POSSIVEL_SALVAR_DADOS_INFORMADOS_PODEM_ESTAR_INCORRETOS em Portugues.cs).
- Lançamento contábil específico por modelo de contrato: o fato contábil gerado na liquidação depende do modelo do contrato: NDF e NDFC utilizam a rotina de gravação de NDF (com filtro específico para operações “BCOVC”); OPC, PPE e Pronto possuem suas próprias rotinas de geração de fato contábil; ACC/ACE/TRV seguem a rotina padrão de contrato de câmbio.
- Filtro “BCOVC” para NDF/NDFC: ao gerar o fato contábil de contratos do modelo NDF ou NDFC, a rotina aplica um filtro específico para identificar operações do tipo “BCOVC” antes de compor o lançamento contábil.
- Atualização de status após liquidação: ao concluir a liquidação com sucesso, o status do contrato de câmbio é atualizado para “Liquidado”.
- Movimentação financeira vinculada: além do lançamento contábil, a liquidação gera o registro de movimentação financeira correspondente, refletindo a baixa do valor liquidado.
- Integração contábil obrigatória: a liquidação não é considerada concluída sem a geração do fato contábil correspondente ao modelo do contrato — a ausência dessa integração indica falha na operação e a transação é revertida.
- Liquidação sem contrato vinculado: quando a flag LiquidacaoSemContrato é usada, a liquidação é processada a partir dos títulos informados (TitulosAProcessar) sem exigir um contrato de câmbio vinculado; as mesmas validações de valor e persistência se aplicam, podendo resultar na mensagem genérica de falha ao salvar descrita na Regra 8.
- Vínculo entre contratos e títulos: quando a liquidação envolve tanto contratos de câmbio quanto títulos (TitulosAProcessar preenchido), o sistema associa os valores liquidados entre as duas listas conforme a moeda e a carteira selecionadas no cabeçalho da operação.
- Cotação usada no cálculo: o ValorCotacao informado no cabeçalho da liquidação é o valor efetivamente utilizado para conversão e cálculo dos valores em moeda nacional/estrangeira durante a gravação.
- Reversão total em caso de erro em qualquer contrato do lote: ao processar múltiplos contratos em uma única chamada de Salvar, se a validação ou gravação de qualquer um dos contratos falhar, a transação inteira é revertida — nenhum dos contratos do lote é liquidado parcialmente.
Permissões
Acesso à rotina: “EditViewDeLiquidacaoDeContratoBuscaContratos” (ID 3107, menu pai ID 1585)
| Ação | Permissão | ID |
|---|---|---|
| Salvar | “LiquidacaoContrato/Salvar” | 3108 |
| ListarContratos | coberta por “EditViewDeLiquidacaoDeContratoBuscaContratos” | 3107 |
| ObterFiltrosDoXmlDeConfiguracaoDeContrato | coberta por “EditViewDeLiquidacaoDeContratoBuscaContratos” | 3107 |
| Imprimir | coberta por “EditViewDeLiquidacaoDeContratoBuscaContratos” (permissão granular própria não localizada em RecursosGeraisFinanceiro.cs) | 3107 |
Rotinas relacionadas
| Rotina | Relação |
|---|---|
| Contrato de Câmbio (cadastro) | Origem dos contratos elegíveis para liquidação |
| Movimentação Financeira | Recebe o lançamento de baixa gerado na liquidação |
| Integração Contábil (Fato Contábil) | Recebe o lançamento contábil específico do modelo do contrato liquidado |