📌 Base para outras rotinas

O contrato cadastrado aqui é a base de outras rotinas do sistema (como vinculação de fatura, desvinculação de fatura, liquidação de contrato e lançamento de juros para contrato): todas elas pesquisam contratos por meio desta rotina e consomem o saldo controlado por ela. Por isso, qualquer novo contrato criado por outros meios (como uma futura importação via planilha) precisa reproduzir exatamente o mesmo comportamento descrito neste documento para o cadastro de um novo contrato.

▶ Tutorial em vídeo: ainda não disponível para esta rotina.

Chave Fato

Tipo: texto (somente leitura)

Obrigatoriedade: não se aplica, é gerado pelo sistema

Descrição: identificador interno único do contrato de câmbio.

Comportamento: fica escondido na tela de “Novo” e aparece na tela de “Edição”, sempre bloqueado para digitação. O sistema gera esse valor automaticamente ao salvar um contrato novo.

Impacto: é a chave usada em todas as integrações posteriores (vínculo de fatura, liquidação, movimentação financeira e integração contábil). Também é um dos filtros da tela de consulta (“Chave Fato”).

Filial

Tipo: campo de busca (lupa)

Obrigatoriedade: obrigatório

Descrição: filial à qual o contrato de câmbio pertence.

Comportamento: já vem preenchido com a filial do usuário logado; pode ser trocado pela lupa de pesquisa.

Impacto: usada para segregar o contrato por filial, para localizar o Fato Contábil correto durante a geração das movimentações financeiras e para obter a série/número do documento “ADX” no modelo Antecipado (ADX).

Número do Contrato

Tipo: texto

Obrigatoriedade: obrigatório

Descrição: número do contrato de câmbio definido pelo usuário ou pelo banco.

Comportamento: aceita até 10 caracteres. É o campo que recebe o foco ao abrir a tela de “Novo”.

Impacto: usado para localizar o contrato nas telas de consulta, vinculação de fatura e liquidação, e gravado como código do documento nas movimentações financeiras geradas.

Código do Contrato

Tipo: texto

Obrigatoriedade: opcional

Descrição: código completo do contrato de câmbio conforme o documento emitido pelo banco.

Comportamento: texto livre de até 100 caracteres. Não é preenchido nem validado pelo sistema; é uma informação digitada pelo próprio usuário.

Impacto: gravado junto ao contrato como informação complementar de identificação.

Situação do Contrato

Tipo: seleção

Obrigatoriedade: obrigatório

Descrição: situação atual do contrato: “A – Aberto”, “L – Liquidado” ou “C – Cancelado”.

Comportamento: em um cadastro novo, já vem selecionado como “A – Aberto”. Na tela de edição, fica bloqueado.

Impacto: contratos que não estejam com situação “Aberto” não podem ser editados nem excluídos. As janelas de pesquisa usadas por outras rotinas (vinculação, liquidação) trazem, por padrão, apenas contratos “Abertos”.

Tipo do Contrato

Tipo: seleção

Obrigatoriedade: obrigatório

Descrição: tipo de operação do contrato: “E – Exportação” ou “I – Importação”.

Comportamento: já vem selecionado como “E – Exportação” em um cadastro novo.

Impacto: usado na classificação e como filtro na tela de consulta; aparece na coluna “Tipo do contrato” das listagens.

Modelo do Contrato

Tipo: seleção

Obrigatoriedade: obrigatório

Descrição: modelo/natureza do contrato de câmbio. Opções: ACC (Adiantamento sobre Contrato de Câmbio), ACE (Adiantamento sobre Cambiais Entregues), Pronto (Contrato Pronto), NDF (Non Deliverable Forward, Contrato a Termo de Moeda sem Entrega Física), NDFC (NDF – Corrente), TRV (Trava), PPE (Pré-Pagamento de Exportação), OPC (Opção), Antecipado (Banco) e Antecipado (ADX) (Antecipado cliente).

Comportamento: ao selecionar “Antecipado (ADX)”, o sistema esconde o campo “Carteira Origem” e exibe o campo “Participante” como obrigatório, além de tornar “Data de Abertura” e “Data de Vencimento” obrigatórias. Para os demais modelos, o comportamento é o inverso. Se não for selecionado um modelo válido, o sistema bloqueia o salvamento com a mensagem “Não foi possível obter modelo — Não foi informado um modelo valido para o contrato — Informar um modelo valido para o contrato.”

Impacto: é o campo que decide todo o comportamento financeiro automático do contrato: quais movimentações são geradas, se um título de adiantamento é criado e se a liquidação é lançada automaticamente (ver seção 9, Regra 3). Também define se o contrato aceita lançamento de juros (apenas ACC, ACE e TRV).

Carteira Origem

Tipo: campo de busca (lupa)

Obrigatoriedade: obrigatório, exceto quando o Modelo é “Antecipado (ADX)”, situação em que o campo some da tela e é substituído pelo campo “Participante”

Descrição: carteira (banco/caixa) de onde o valor do contrato sai.

Comportamento: se não for informada, for informada como zero, ou não existir ou estiver sem cadastro vinculado, o sistema bloqueia o salvamento com uma das mensagens de “Não foi possível obter carteira” descritas na seção 9, Regra 4.

Impacto: usada como uma das pontas das movimentações financeiras de débito/crédito geradas automaticamente; aparece na coluna “Carteira/Participante Origem” da listagem e é um dos filtros da tela de consulta.

Participante

Tipo: campo de busca (lupa)

Obrigatoriedade: condicional, obrigatório apenas quando o Modelo do Contrato é “Antecipado (ADX)”; nos demais modelos o campo fica escondido

Descrição: cliente do contrato de adiantamento, usado quando o adiantamento é feito pelo cliente e não pelo banco.

Comportamento: a lupa pesquisa apenas Clientes. Ao trocar o Modelo do Contrato para um valor diferente de “Antecipado (ADX)”, o sistema limpa e esconde este campo.

Impacto: identifica o cliente do contrato e é a origem da “Forma de Cobrança” usada para gerar o título a receber de adiantamento (ver seção 9, Regra 3).

Carteira Destino

Tipo: campo de busca (lupa)

Obrigatoriedade: obrigatório

Descrição: carteira (banco/caixa) que recebe o valor do contrato.

Comportamento: mesma validação de existência e vínculo de cadastro da Carteira Origem (seção 9, Regra 4), aplicada em todos os modelos, inclusive “Antecipado (ADX)”.

Impacto: usada como a outra ponta das movimentações financeiras de débito/crédito geradas automaticamente; aparece na coluna “Carteira/Participante Destino” da listagem e é um dos filtros da tela de consulta.

Data de Abertura

Tipo: data

Obrigatoriedade: obrigatório

Descrição: data em que o contrato de câmbio foi aberto/negociado.

Comportamento: já vem preenchida com a data atual, mas pode ser alterada.

Impacto: usada como referência de data para as movimentações financeiras quando a Data de Crédito não é informada; aparece na coluna “Data de abertura” da listagem e é filtrável por período na tela de consulta (“Data de Abertura” e “Data de Abertura Final”).

Data de Crédito

Tipo: data

Obrigatoriedade: obrigatório

Descrição: data em que o valor do contrato é creditado.

Comportamento: quando informada, tem prioridade sobre a Data de Abertura para efeito da data das movimentações financeiras geradas.

Impacto: usada como data das movimentações financeiras e, em contratos do modelo “Pronto”, como data da liquidação automática. Filtrável por período na tela de consulta (“Data de Crédito” e “Data de Crédito Final”).

Prazo Vencimento

Tipo: número inteiro (dias)

Obrigatoriedade: opcional

Descrição: prazo, em dias, acordado para o vencimento do contrato.

Comportamento: campo numérico de até 4 dígitos, sem casas decimais. O sistema não converte automaticamente esse prazo em Data de Vencimento; os dois campos são independentes e ambos precisam ser preenchidos pelo usuário quando aplicável.

Impacto: é um dos três únicos campos que continuam editáveis depois que o contrato é salvo (ver seção 7). Recebe o foco automaticamente ao abrir a tela de edição.

Data de Vencimento

Tipo: data

Obrigatoriedade: obrigatório

Descrição: data de vencimento do contrato de câmbio.

Comportamento: campo de data simples, sem cálculo automático a partir do Prazo Vencimento.

Impacto: usada nos filtros de consulta (“Data de Vencimento” e “Data de Vencimento Final”) e nas telas de liquidação de contratos. No modelo “Antecipado (ADX)”, é gravada como data de vencimento do título a receber gerado.

Prazo Entrega Documento

Tipo: número inteiro (dias)

Obrigatoriedade: opcional

Descrição: prazo, em dias, acordado para entrega dos documentos do contrato.

Comportamento: campo numérico de até 4 dígitos, sem casas decimais. Assim como o “Prazo Vencimento”, não é convertido automaticamente na data correspondente.

Impacto: é um dos três únicos campos que continuam editáveis depois que o contrato é salvo (ver seção 7).

Data de Entrega Documento

Tipo: data

Obrigatoriedade: opcional

Descrição: data limite para entrega dos documentos referentes ao contrato.

Comportamento: campo de data simples.

Impacto: usada apenas como informação de controle do contrato.

Moeda

Tipo: campo de busca (lupa)

Obrigatoriedade: obrigatório

Descrição: moeda estrangeira do contrato de câmbio.

Comportamento: a lupa é a de “Moeda com Cotação”; ao selecionar a moeda, o sistema preenche automaticamente o campo “Cotação moeda” com a cotação cadastrada e recalcula o “Valor Contrato”. Se a moeda não for informada ou não existir no cadastro, o sistema bloqueia o salvamento com as mensagens de “Não foi possível obter moeda” descritas na seção 9, Regra 5.

Impacto: usada para todos os valores do contrato expressos “em moeda” (Valor Contrato Moeda, Valor Vinculado Moeda, Valor Liquidado Moeda) e para a integração contábil. Aparece na coluna “Moeda” da listagem no formato “código-nome” e é um dos filtros das janelas de pesquisa de contrato usadas por outras rotinas.

Valor Contrato Moeda

Tipo: número decimal (2 casas)

Obrigatoriedade: obrigatório

Descrição: valor do contrato expresso na moeda estrangeira selecionada.

Comportamento: aceita até 15 caracteres e não aceita valor negativo. Ao sair do campo, o sistema recalcula automaticamente o “Valor Contrato” (Valor Contrato Moeda multiplicado pela Cotação moeda).

Impacto: é o valor de referência de todo o controle de saldo do contrato, limitando quanto pode ser vinculado a faturas e quanto pode ser liquidado. Aparece na coluna “Valor contrato” da listagem.

Cotação moeda

Tipo: número decimal (4 casas)

Obrigatoriedade: opcional

Descrição: cotação da moeda estrangeira usada no contrato.

Comportamento: preenchida automaticamente ao selecionar a Moeda, mas pode ser alterada. Ao sair do campo, o sistema recalcula o “Valor Contrato”. Se o usuário digitar manualmente um “Valor Contrato” que não bata com o cálculo, o sistema oferece recalcular esta cotação (ver seção 9, Regra 11).

Impacto: usada no cálculo do valor em moeda nacional das movimentações financeiras e gravada nas movimentações geradas.

Valor Contrato

Tipo: número decimal (2 casas)

Obrigatoriedade: obrigatório

Descrição: valor do contrato em moeda nacional.

Comportamento: calculado automaticamente como Valor Contrato Moeda multiplicado pela Cotação moeda, mas pode ser digitado diretamente. Se o valor digitado não corresponder ao cálculo, o sistema pergunta “O valor informado no campo não corresponde ao cálculo automático, deseja prosseguir?”; confirmando, o sistema recalcula e regrava a Cotação moeda; recusando, devolve o campo ao valor calculado.

Impacto: valor lançado como débito/crédito em moeda nacional nas movimentações financeiras geradas pelo contrato. O sistema não permite salvar o contrato com este valor vazio ou zerado (ver seção 9, Regra 5.1).

Taxa Juros

Tipo: número decimal (4 casas)

Obrigatoriedade: opcional

Descrição: percentual de juros associado ao contrato.

Comportamento: aceita até 6 caracteres e não aceita valor negativo.

Impacto: usado na rotina de liquidação de juros do contrato, disponível apenas para os modelos ACC, ACE e TRV.

Valor Vinculado Moeda

Tipo: número decimal (somente leitura)

Obrigatoriedade: não se aplica, é mantido pelo sistema

Descrição: soma dos valores, em moeda estrangeira, já vinculados a faturas para este contrato.

Comportamento: começa zerado em um contrato novo; é atualizado pelas rotinas de vinculação e desvinculação de faturas, nunca pela tela de cadastro do contrato.

Impacto: usado para calcular o “Saldo a Vincular”, para impedir vincular mais faturas do que o valor do contrato permite, e para bloquear a exclusão do contrato (ver seção 9, Regra 7). Aparece na coluna “Valor vinculado” da listagem.

Valor Liquidado Moeda

Tipo: número decimal (somente leitura)

Obrigatoriedade: não se aplica, é mantido pelo sistema

Descrição: soma dos valores, em moeda estrangeira, já liquidados deste contrato.

Comportamento: começa zerado em um contrato novo; é atualizado pela rotina de liquidação de contratos. No modelo “Pronto”, já vem preenchido no próprio cadastro, porque a liquidação é lançada automaticamente.

Impacto: usado para calcular o “Saldo a Liquidar”. Quando o Valor Liquidado Moeda se iguala ao Valor Contrato Moeda, o sistema muda a Situação do Contrato para “Liquidado”.

Saldo a Vincular

Tipo: número decimal (somente leitura)

Obrigatoriedade: não se aplica, é calculado pelo sistema

Descrição: quanto do contrato ainda pode ser vinculado a faturas.

Comportamento: o valor não é gravado no banco de dados; o sistema o calcula em toda consulta como Valor Contrato Moeda menos Valor Vinculado Moeda. Quando o Valor Contrato Moeda está vazio, o saldo é exibido como zero.

Impacto: exibido na coluna “Saldo a vincular” da listagem e usado como referência nas telas de vinculação de fatura.

Saldo a Liquidar

Tipo: número decimal (somente leitura)

Obrigatoriedade: não se aplica, é calculado pelo sistema

Descrição: quanto do contrato ainda pode ser liquidado.

Comportamento: o valor não é gravado no banco de dados; o sistema o calcula em toda consulta como Valor Contrato Moeda menos Valor Liquidado Moeda. Quando o Valor Contrato Moeda está vazio, o saldo é exibido como zero.

Impacto: exibido na coluna “Saldo a liquidar” da listagem e usado nas telas de liquidação de contratos para impedir liquidar mais do que o saldo disponível.

Observação

Tipo: texto longo (área de texto)

Obrigatoriedade: opcional

Descrição: campo de anotação livre sobre o contrato.

Comportamento: aceita até 255 caracteres.

Impacto: exibido nas telas de consulta e detalhe do contrato; copiado para a observação do título a receber gerado no modelo “Antecipado (ADX)”. É um dos três únicos campos que continuam editáveis depois que o contrato é salvo (ver seção 7).

📌 Integração com outras rotinas

Outras rotinas do sistema (como vinculação de fatura, desvinculação de fatura, liquidação de contrato e lançamento de juros para contrato) abrem janelas de pesquisa que consultam esta mesma base de contratos, mas com filtros próprios, conforme detalhado na seção 9, Regra 10.

📌 Histórico de alterações

[informação não disponível na documentação de origem, validar com analista responsável — não foi localizada uma tela de histórico/log de alterações do contrato acessível ao usuário final].

Regra 1: Geração automática da Chave Fato

Se o campo interno “Chave Fato” não vier preenchido, o sistema gera um valor automaticamente ao salvar. Se vier preenchido, o sistema usa o valor informado. Em um cadastro feito pela tela, esse campo está sempre vazio, então a chave é sempre gerada pelo sistema.

Regra 2: Participante do contrato conforme o Modelo

Quando o Modelo do Contrato é “Antecipado (ADX)”, o sistema usa o Participante informado para identificar o cliente do contrato; se o Participante não for informado, o sistema usa o valor do campo Carteira Origem diretamente, sem validá-lo como carteira. Para todos os demais modelos, a Carteira Origem é sempre validada como carteira, e o cadastro vinculado a ela é usado como participante do contrato.

Regra 3: Modelo do contrato define o comportamento financeiro

Modelos “ACC”, “ACE” e “Antecipado (Banco)”: o sistema gera duas movimentações financeiras (débito na Carteira Origem, crédito na Carteira Destino) no valor do contrato.

Modelo “Antecipado (ADX)”: além da movimentação de débito, o sistema exige que o cliente tenha uma Forma de Cobrança cadastrada; sem isso, exibe a mensagem “Não foi possível inserir novo Contrato de Câmbio — Não foi informado uma forma de cobrança no cliente — Informar uma forma de cobrança no Cliente [código do cliente] para a inclusão do título de adiantamento” e não permite salvar. Quando a forma de cobrança existe, o sistema cria automaticamente um título a receber de adiantamento (documento “ADX”) vinculado ao contrato, mais uma movimentação financeira de crédito ligada a esse título.

Modelos “Pronto”, “NDF”, “NDFC”, “TRV”, “PPE” e “OPC”: o sistema não gera movimentação financeira de débito/crédito entre carteiras na inclusão. As exceções são: “NDF” e “NDFC”, que geram um único lançamento contábil sem título; e “Pronto”, que lança a liquidação do contrato automaticamente no mesmo momento do cadastro (crédito na Carteira Destino, débito na Carteira Origem) e, se o valor em moeda do contrato ficar igual ao valor liquidado, muda a Situação do Contrato para “Liquidado”.

Regra 4: Carteiras precisam existir e ter um cadastro vinculado

As Carteiras Origem e Destino informadas precisam existir no cadastro e possuir um Cadastro Geral (participante) vinculado. Se qualquer uma dessas condições não for atendida, o sistema impede o salvamento, exibindo a mensagem correspondente (“A carteira informada está inválida”, “Carteira [código] não encontrada.” ou “Carteira [código] não possui um cadastro vinculado.”).

Regra 5: Moeda é obrigatória e precisa existir

O contrato precisa ter uma Moeda informada, e essa moeda precisa existir no cadastro de moedas. Sem isso, o sistema impede o salvamento com a mensagem “Não foi informada a moeda” ou “A Moeda inserida não foi encontrada.”, conforme o caso.

Regra 5.1: Valor Contrato é obrigatório

O “Valor Contrato” (valor em moeda nacional) não pode ficar vazio nem zerado. Se ficar, o sistema impede o salvamento com a mensagem “Não foi possível realizar operação — Não foi informado um valor para o contrato — É obrigatório informar um valor para o contrato de cambio”. Se o “Valor Contrato Moeda” ficar vazio ou zerado, o sistema o preenche automaticamente com o mesmo valor do “Valor Contrato”.

Regra 6: Fato Contábil precisa estar configurado para gerar movimentação financeira

Para os modelos que geram movimentação financeira (ACC, ACE, Antecipado (Banco), Antecipado (ADX)), precisa existir um Fato Contábil configurado para a combinação de operação financeira e variação daquele modelo específico. Sem essa configuração, o sistema bloqueia o cadastro com a mensagem “Não é possível executar uma operação financeira sem histórico — Configure um histórico no fato contábil do financeiro para os seguintes valores: Operação: [código] / Variação: [nome da variação]”.

Regra 7: Um contrato com faturas vinculadas não pode ser excluído

Um contrato de câmbio só pode ser excluído se o seu Valor Vinculado Moeda for igual a zero. Se houver faturas vinculadas, o sistema impede a exclusão com a mensagem “O contrato [número] [[chave fato]] possui faturas vinculadas e não pode ser excluido. — Para exclusão, desvincule faturas e tente novamente.”

Regra 8: Somente contratos “Abertos” podem ser editados ou excluídos

Se o contrato não estiver com a Situação “Aberto”, o sistema impede tanto a edição quanto a exclusão do registro. Mensagem exibida: [informação não disponível na documentação de origem, validar com analista responsável — a recusa dispara uma mensagem interna referente à situação do contrato, mas o texto literal exibido ao usuário não foi localizado na análise de origem].

Regra 9: A exclusão apaga também os lançamentos gerados pelo contrato

Confirmada a Regra 7, o sistema exclui, na mesma operação: as movimentações financeiras geradas pelo contrato, os títulos a receber gerados a partir dele, e por fim o próprio contrato. Se qualquer etapa falhar, nada é excluído e o sistema exibe “Não foi possível realizar operação — [descrição da falha] — Verifique operação e tente novamente”. Se o contrato informado já não existir, o sistema conclui a operação sem erro e sem excluir nada.

Regra 10: Critério das janelas de pesquisa de contrato usadas por outras rotinas

As lupas de contrato abertas em outras telas não mostram os mesmos registros da listagem principal:

• Pesquisa padrão (vinculação, liquidação, juros): mostra apenas contratos “Abertos” cujo saldo seja maior que zero, sendo o saldo igual a Valor Contrato Moeda menos a soma de Valor Vinculado Moeda e Valor Liquidado Moeda.
• Pesquisa de desvinculação: mostra apenas contratos “Abertos” que já tenham Valor Vinculado Moeda maior que zero, ou seja, apenas os que têm algo a desvincular.
• Pesquisa do filtro “Número Contrato” da tela principal: mostra todos os contratos, sem filtro de situação nem de saldo.

Algumas dessas pesquisas ainda restringem o resultado aos modelos ACC, ACE e TRV, conforme a rotina que as abre.

Regra 11: Divergência entre o Valor Contrato digitado e o cálculo automático

Se o usuário digitar um “Valor Contrato” diferente do resultado de Valor Contrato Moeda multiplicado pela Cotação moeda, o sistema exibe a pergunta “O valor informado no campo não corresponde ao cálculo automático, deseja prosseguir?”. Se o usuário confirmar, o sistema mantém o valor digitado e recalcula a “Cotação moeda” como Valor Contrato dividido por Valor Contrato Moeda, com 4 casas decimais. Se o usuário recusar, o sistema devolve o “Valor Contrato” ao valor calculado originalmente.

Regra 12: Alterações feitas fora da tela não passam pelas validações do cadastro

As validações de modelo, carteira, moeda e valor descritas nas Regras 3 a 6 são aplicadas apenas no cadastro de um contrato novo. A operação de edição não repete nenhuma dessas validações e também não gera nem ajusta movimentações financeiras. Como a tela de edição bloqueia todos os campos que teriam esse impacto (ver seção 7), na prática isso não afeta o usuário final, mas é uma restrição importante para qualquer integração ou importação que venha a gravar contratos sem passar pela tela: uma importação deve usar sempre o caminho de cadastro novo, nunca o de edição.

Regra 13: Cancelamento de contrato

Um contrato de câmbio só pode ser cancelado quando três condições são atendidas ao mesmo tempo: a Situação do Contrato precisa estar “Aberto”; o Valor Vinculado (soma de faturas vinculadas ao contrato) precisa ser igual a zero; e não pode haver nenhuma operação de liquidação parcial lançada para o contrato. Faltando qualquer uma dessas três condições, o sistema bloqueia o cancelamento; não basta o contrato estar sem faturas vinculadas se, por exemplo, já houver uma liquidação parcial lançada.

Erro: “Não foi possível cancelar o lançamento”

Motivo: “A situação do contrato não atende às condições necessárias para o cancelamento. O contrato deve estar aberto, sem valor de fatura vinculada (valor vinculado igual a 0), e não deve haver operação de liquidação parcial.”

Solução: “Realizar a desvinculação de Fatura ou Excluir a operação de Liquidação.”

Para conseguir cancelar um contrato bloqueado por essa regra, é necessário primeiro desvincular as faturas ligadas a ele (na rotina de desvinculação de fatura) e/ou excluir a operação de liquidação parcial lançada sobre ele.