Juros para Contrato de Câmbio
JurosParaContratoDeCambio
Rotina do módulo Financeiro (submenu Comex) que permite lançar juros sobre contratos de câmbio em aberto.
Visão Geral
Rotina do módulo Financeiro (submenu Comex) que permite lançar juros sobre contratos de câmbio em aberto. O usuário informa uma moeda e uma cotação de referência, o sistema lista os contratos de câmbio elegíveis para lançamento de juros com o valor calculado automaticamente, e o usuário confirma o processamento, que gera lançamentos financeiros e sua integração contábil.
Endpoints
[GET] /JurosParaContratoDeCambio/ListarContratosParaJuros
Lista os contratos de câmbio de uma determinada moeda que são elegíveis para lançamento de juros, já com o valor de juros pré-calculado com base na cotação informada pelo usuário na tela e na data de movimentação do usuário logado.
Permissão: coberta pela permissão de acesso à rotina “EditViewDeJurosParaContratoDeCambio” (ID 3942)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| idMoeda | string (convertido para short/Int16) | Sim | Código da moeda dos contratos de câmbio a listar |
| valorCotacaoTela | decimal | Sim | Cotação informada pelo usuário na tela, usada para calcular o valor de atualização monetária de cada contrato |
“` GET /JurosParaContratoDeCambio/ListarContratosParaJuros?idMoeda=2&valorCotacaoTela=5.35 “`
“`json { “total”: 1, “rows”: [ { “ID”: “ABC123”, “NumeroDoContrato”: “0001”, “DataAbertura”: “2026-08-01T00:00:00”, “DataCredito”: “2026-08-05T00:00:00”, “IDTipoDoContrato”: “…”, “ModeloContrato”: “ACC”, “ValorContrato”: 10000.00, “ValorContratoMoeda”: 2000.00, “ValorVinculadoMoeda”: 500.00, “ValorCotacao”: 5.20, “SaldoComLiquidado”: 1500.00, “IDFilial”: “1”, “ValorNovaCotacao”: 5.35, “IDDaMoeda”: “2”, “DataDeVencimento”: “2026-09-05T00:00:00”, “TaxaDeJuros”: 12.5, “ValorParaLancamentoDeJuros”: 65.10, “TipoDaAtualizacaoMonetaria”: “Passiva”, “ValorParaLancamentoDeAtualizacaoMonetaria”: 225.00 } ] } “`
[POST] /JurosParaContratoDeCambio/Salvar
Processa o lançamento de juros para um ou mais contratos de câmbio selecionados pelo usuário: gera as movimentações financeiras de juros (quando houver valor de juros informado para o contrato), executa a atualização monetária dos contratos com base na nova cotação e integra os lançamentos à contabilidade. Toda a operação roda dentro de uma única transação — se qualquer etapa falhar, nada é gravado.
Permissão: “JurosParaContratoDeCambio/Salvar” (ID 3943)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| dto | DTODeCabecalhoParaJurosDoContrato (corpo da requisição) | Sim | Cabeçalho com a cotação usada no lançamento e a lista de contratos selecionados com seus valores de juros |
“` POST /JurosParaContratoDeCambio/Salvar { “ValorDaCotacao”: 5.35, “Contratos”: [ { “ID”: “ABC123”, “ValorDaCotacao”: 5.35, “ValorDoJuros”: 65.10, “ValorDaTaxa”: 12.5 } ] } “`
“`json { “success”: true, “idOperacao”: “2026090900001”, “listaDeOperacoes”: [ “…” ], “listaDeContabeis”: [ “…” ], “listaDeContratos”: [ “…” ] } “`
Modelos de Dados
DTODeCabecalhoParaJurosDoContrato (corpo do POST Salvar)
| Campo | Tipo | Descrição |
|---|---|---|
| ValorDaCotacao | decimal | Cotação usada para calcular a atualização monetária de todos os contratos selecionados |
| Contratos | Lista de DTODeJurosDoContratoCambio | Contratos selecionados pelo usuário para lançamento de juros |
DTODeJurosDoContratoCambio (item da lista Contratos)
| Campo | Tipo | Descrição |
|---|---|---|
| ID | string | Chave de fato (identificador) do contrato de câmbio |
| ValorDaCotacao | decimal | Cotação aplicada a este contrato |
| ValorDoJuros | decimal | Valor de juros a lançar para este contrato — se for zero, nenhuma movimentação financeira de juros é gerada para ele (apenas a atualização monetária, quando aplicável) |
| ValorDaTaxa | decimal | Taxa de juros usada no cálculo |
Regras de Negócio
- Cálculo do valor de juros na listagem. Para cada contrato elegível, o sistema calcula os dias a considerar (dia do mês da data de movimentação do usuário, descontando os dias já decorridos desde a data de crédito do contrato, quando a data de crédito cai no mesmo mês/ano da data de movimentação). A taxa de juros do contrato é dividida por 360 e multiplicada pelos dias e pelo saldo do contrato, arredondando os valores intermediários e o resultado final para 2 casas decimais.
- Cálculo do tipo e valor de atualização monetária na listagem. Comparando a cotação informada na tela com a cotação atual do contrato: se a nova cotação for maior, a atualização é classificada como “Passiva”; caso contrário, como “Ativa”. O valor da atualização é a diferença entre o saldo do contrato valorizado pela nova cotação e o saldo valorizado pela cotação atual.
- Somente contratos com modelo elegível para juros aparecem na listagem. A consulta só retorna contratos cujo modelo esteja marcado como válido para lançamento de juros (atualmente: ACC — Adiantamento sobre Contrato de Câmbio, ACE — Adiantamento sobre Cambiais Entregues, Trava e Pronto com Fatura).
- Contrato deve existir para ser processado. Ao processar o lançamento (ação Salvar), se o contrato informado não for encontrado, a operação é interrompida.Mensagem exibida: “Não foi possível obter Contrato valido” — “O Contrato com código [chave de fato] {0} não encontrado para realizar o lançamento.” — “Informe Chave de fato valida para a operação” (onde {0} é a chave de fato do contrato informado).
- Contrato deve ter um modelo cadastrado válido. Se o modelo do contrato não puder ser identificado na lista de modelos do sistema, a operação é interrompida.Mensagem exibida: “Não foi possível obter Contrato valido” — “O Contrato com código [{0}] não possui um modelo válido. Modelo : {1}” — “Informe um Modelo valido para o lançamento de juros” (onde {0} é a chave de fato e {1} o código do modelo).
- Contrato deve ter modelo elegível para juros. Mesmo existindo, se o modelo do contrato não estiver entre os permitidos para lançamento de juros, a operação é interrompida.Mensagem exibida: “Não foi possível obter Contrato valido” — “O Contrato com código [{0}] não é válido para lançamento de juros. Modelo : {1} Modelos permitidos : ACC” — “ACE e Trava” (onde {0} é a chave de fato e {1} o código do modelo; a mensagem no sistema está com a lista de modelos permitidos truncada entre os campos Motivo e Solução).
- Contrato deve estar com status Aberto. Contratos que não estejam no status “Aberto” não podem receber lançamento de juros.Mensagem exibida: “Não foi possível obter Contrato valido” — “O Contrato com código {0}[{1}] não é válido para lançamento de juros pois não esta Aberto” — “Informe um contrato valido para o lançamento de juros” (onde {0} é o código do contrato e {1} a chave de fato).
- Nenhum contrato informado. Se a lista de contratos enviada estiver vazia ou nula, a operação inteira é interrompida antes de qualquer processamento.Mensagem exibida: “Não foi possível Processar operação” — “Nenhum contrato foi informado” — “Informe um contrato para operação”
- Falha inesperada durante o processamento. Qualquer erro não previsto durante a transação (atualização monetária, geração das movimentações ou integração contábil) cancela toda a operação (nada é persistido) e o erro original é repassado ao usuário.Mensagem exibida: “{0}.” — “Falha na operação.” — “Verifique os dados e tente novamente.” (onde {0} é a mensagem do erro técnico ocorrido).
- Lançamento de juros só ocorre quando há valor de juros informado. Para cada contrato selecionado, a movimentação financeira de juros só é gerada se o valor de juros do contrato for diferente de zero; contratos com valor de juros zerado participam apenas da atualização monetária.
- Integração contábil automática. Após gerar todas as movimentações financeiras da operação, o sistema executa a integração contábil de todos os lançamentos gerados, dentro da mesma transação — se a integração contábil falhar, toda a operação (incluindo os lançamentos financeiros) é desfeita.
Permissões
Acesso à rotina: “EditViewDeJurosParaContratoDeCambio” (ID 3942)
| Ação | Permissão | ID |
|---|---|---|
| Salvar (processar lançamento de juros) | “JurosParaContratoDeCambio/Salvar” | 3943 |
| Listar contratos para juros | coberta por “EditViewDeJurosParaContratoDeCambio” | — |