Contrato de Câmbio
ContratoCambio
Rotina do módulo Financeiro, submenu “Comex” (tela “Contrato de Câmbio”), que permite cadastrar, editar, excluir e consultar Contratos de Câmbio (ACC, ACE, Antecipado Banco, Antecipado ADX, NDF, NDFC, TRV, PPE e Pronto).
Visão Geral
Rotina do módulo Financeiro, submenu “Comex” (tela “Contrato de Câmbio”), que permite cadastrar, editar, excluir e consultar Contratos de Câmbio (ACC, ACE, Antecipado Banco, Antecipado ADX, NDF, NDFC, TRV, PPE e Pronto). A rotina controla valores em moeda estrangeira e nacional, cotação, prazos, vínculo/desvínculo com faturas e dispara automaticamente lançamentos financeiros e integração contábil conforme o modelo do contrato.
Endpoints
POST /ContratoCambio/Novo
Cria um novo Contrato de Câmbio. Conforme o “Modelo” do contrato, além de gravar o registro, a ação pode gerar automaticamente movimentações financeiras (débito/crédito entre carteiras), um título a receber de adiantamento e disparar a integração contábil.
Permissão: “ContratoCambio/Novo” (ID 3059)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| dto | DTODeContratoCambio (corpo da requisição) | Sim | Dados do novo contrato de câmbio — ver campos na seção “Modelos de Dados” |
“` POST /ContratoCambio/Novo
Content-Type: application/x-www-form-urlencoded
IDDoTipo=E&IDDoModelo=ACC&Codigo=0001&IDDaFilial=100&DataAbertura=2026-08-11&IDDoStatus=A&IDDoCadastroGeral=200&IDDoBancoCaixaDestino=53119&IDDaMoeda=2&ValorMoeda=10000.00&ValorCotacao=5.35 “`
Segue o envelope padrão de “JsonParaPersistencia” (indicador de sucesso + título + mensagem + objeto persistido): “`json { “Titulo”: “Novo Contrato Câmbio”, “Mensagem”: “inserido com sucesso”, “Dados”: { “ID”: “…”, “Codigo”: “0001”, “…”: “…” } } “` [informação não disponível na análise de código — a estrutura exata (nomes de propriedades) do envelope “JsonParaPersistencia” não foi conferida; os nomes acima são ilustrativos]
POST /ContratoCambio/Editar
Altera um Contrato de Câmbio já cadastrado. Na prática, o sistema só permite alterar os campos de prazo e a observação — todo o restante do formulário fica bloqueado na tela de edição (ver Regra de Negócio 13).
Permissão: “ContratoCambio/Editar” (ID 3060)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| dto | DTODeContratoCambio (corpo da requisição) | Sim | Dados completos do contrato, incluindo o “ID” (chave de fato) do registro a alterar — ver campos na seção “Modelos de Dados” |
| dto.IDDoStatus | string (1) | Sim | Precisa ser “A” (Aberto). Qualquer outro status faz o sistema recusar a alteração (ver Regra de Negócio 12) |
“` POST /ContratoCambio/Editar
Content-Type: application/x-www-form-urlencoded
ID=000004461&IDDoStatus=A&IDDoTipo=E&IDDoModelo=ACC&Codigo=0001&IDDaFilial=100&PrazoVencimento=90&PrazoEntregaDocumento=15&Observacao=Ajuste de prazo “`
Envelope padrão de “JsonParaPersistencia” (indicador de sucesso + título + mensagem + objeto persistido): “`json { “Titulo”: “Editar Contrato Câmbio”, “Mensagem”: “Contrato Câmbio editado com sucesso”, “Dados”: { “ID”: “000004461”, “PrazoVencimento”: 90 } } “` [informação não disponível na análise de código — a estrutura exata (nomes de propriedades) do envelope “JsonParaPersistencia” não foi conferida; os nomes acima são ilustrativos]
POST /ContratoCambio/Excluir
Exclui um Contrato de Câmbio e todos os seus efeitos financeiros (movimentações financeiras e títulos a receber gerados na inclusão).
Permissão: “ContratoCambio/Excluir” (ID 3061)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| dto | DTODeContratoCambio (corpo da requisição) | Sim | Dados do contrato; apenas o “ID” (chave de fato) e o “IDDoStatus” são efetivamente usados |
| dto.IDDoStatus | string (1) | Sim | Precisa ser “A” (Aberto). Qualquer outro status faz o sistema recusar a exclusão (ver Regra de Negócio 12) |
“` POST /ContratoCambio/Excluir
Content-Type: application/x-www-form-urlencoded
ID=000004461&IDDoStatus=A “`
“`json { “Titulo”: “Excluir Contrato Câmbio”, “Mensagem”: “Contrato Câmbio excluido com sucesso”, “Dados”: null } “`
GET /ContratoCambio/ObterPorId
Retorna os dados completos de um Contrato de Câmbio, usados para preencher o formulário de edição. Além dos campos gravados, o retorno já traz calculados o “Saldo a Vincular” e o “Saldo a Liquidar”, e os nomes de Filial, Carteira de Destino, Carteira de Origem e Moeda (para exibição amigável na tela).
Permissão: ação de leitura sem permissão própria — coberta pela permissão de acesso à rotina “ListViewDeContratoCambio” (ID 1586)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | Chave de fato do contrato |
“` GET /ContratoCambio/ObterPorId?id=000004461 “`
Envelope genérico contendo uma lista de contratos (a consulta retorna coleção, ainda que sempre com no máximo um item para um ID): “`json [ { “ID”: “000004461”, “IDDaFilial”: “100”, “NomeFilial”: “FILIAL CADASTRO”, “Codigo”: “0001”, “IDDoTipo”: “E”, “IDDoModelo”: “ACC”, “IDDoStatus”: “A”, “IDDaMoeda”: 2, “Moeda”: “US$”, “ValorMoeda”: 10000.00, “ValorCotacao”: 5.3500, “Valor”: 53500.00, “ValorVinculadoMoeda”: 0.00, “ValorLiquidadoMoeda”: 0.00, “SaldoAVincular”: 10000.00, “SaldoALiquidar”: 10000.00 } ] “`
GET /ContratoCambio/Listar
Retorna a listagem paginada de Contratos de Câmbio da tela principal, com o painel “Filtros” da tela aplicado. É a consulta que alimenta a grade “Lista de Contrato Câmbio”.
Permissão: ação de leitura sem permissão própria — coberta pela permissão de acesso à rotina “ListViewDeContratoCambio” (ID 1586)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| extGrid | ConfiguracaoDeGrid (query string) | Sim | Paginação e ordenação da grade (página inicial, quantidade de registros, coluna de ordenação) |
| valorDeConsulta | string | Não (padrão: vazio) | Busca livre — o sistema procura o texto em Filial, Chave de Fato, Número do Contrato, Símbolo/Nome da Moeda, Modelo, Valor Contrato Moeda e Valor Vinculado Moeda. Se o texto for reconhecido como data, procura pela Data de Abertura |
| filial | string | Não | Filtra pela Filial exata |
| chaveFato | string | Não | Filtra pela Chave de Fato exata |
| contratoCambio | string | Não | Um ou vários números de contrato separados por barra vertical — filtra pela Chave de Fato de cada um |
| modeloContratoCambio | string | Não | Filtra pelo Modelo do Contrato (ACC, ACE, Pronto, NDF, NDFC, TRV, PPE, OPC, Antecipado(Banco), Antecipado (ADX)) |
| carteiraOrigem | int | Não | Filtra pela Carteira/Participante de Origem |
| carteiraDestino | int | Não | Filtra pela Carteira/Participante de Destino |
| status | string | Não | Filtra pela Situação do Contrato (“A” = Aberto, “L” = Liquidado, “C” = Cancelado) |
| tipoContratoCambio | string | Não | Filtra pelo Tipo do Contrato (“E” = Exportação, “I” = Importação) |
| dataAbertura | data | Não | Data de Abertura a partir de (limite inicial do período) |
| dataAberturaFinal | data | Não | Data de Abertura até (limite final do período) |
| dataCredito | data | Não | Data de Crédito a partir de |
| dataCreditoFinal | data | Não | Data de Crédito até |
| dataVencimento | data | Não | Data de Vencimento a partir de |
| dataVencimentoFinal | data | Não | Data de Vencimento até |
“` GET /ContratoCambio/Listar?valorDeConsulta=&filial=100&status=A&modeloContratoCambio=ACC&dataAbertura=2026-01-01&dataAberturaFinal=2026-12-31&page=0&start=0&limit=30 “`
Envelope padrão de listagem (“JsonParaListagem”), com o total de registros e a página corrente: “`json { “total”: 137, “registros”: [ { “ID”: “000004461”, “Filial”: “100 – FILIAL CADASTRO”, “Codigo”: “0001”, “Data”: “2026-08-26T00:00:00”, “ModeloNome”: “Adiantamento sobre Contrato de Câmbio”, “CarteiraOrigemFormatado”: “200 – BANCO ORIGEM”, “CarteiraDestinoFormatado”: “53119 – BANCO DESTINO”, “Status”: “Aberto”, “MoedaFormatado”: “2-DOLAR AMERICANO”, “Valor”: 10000.00, “ValorVinculado”: 0.00, “SaldoAVincular”: 10000.00, “SaldoALiquidar”: 10000.00 } ] } “`
GET /ContratoCambio/ListarParaLookup
Alimenta a janela de pesquisa (lookup) de Contrato de Câmbio usada por outras rotinas — Vinculação de Fatura, Liquidação, Juros, entre outras. Por padrão traz apenas contratos ainda com saldo disponível.
Permissão: ação de leitura sem permissão própria — coberta pela permissão de acesso à rotina “ListViewDeContratoCambio” (ID 1586)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| extGrid | ConfiguracaoDeGrid (query string) | Sim | Paginação e ordenação da grade da janela de pesquisa |
| idMoeda | string | Não (padrão: vazio) | Restringe a pesquisa a contratos de uma moeda específica |
| valorDeConsulta | string | Não (padrão: vazio) | Busca livre (mesmos campos do “Listar”) |
| apenasContratosAbertos | booleano | Não (padrão: verdadeiro) | Verdadeiro: só contratos Abertos e com saldo (ver Regra de Negócio 14). Falso: traz todos os contratos, sem filtro de situação nem de saldo |
| filtraVinculadoMaiorQueZero | booleano | Não (padrão: falso) | Quando verdadeiro, inverte o critério: traz contratos Abertos que já tenham Valor Vinculado maior que zero (usado em telas de desvinculação) |
“` GET /ContratoCambio/ListarParaLookup?valorDeConsulta=&idMoeda=2&apenasContratosAbertos=true&page=0&start=0&limit=30 “`
Exemplo de response: mesmo envelope de listagem do “Listar”.
GET /ContratoCambio/ListarParaLookupFatura
Variante da janela de pesquisa usada nas rotinas de fatura. Traz sempre apenas contratos Abertos e com saldo, e permite restringir aos modelos de adiantamento e trava.
Permissão: ação de leitura sem permissão própria — coberta pela permissão de acesso à rotina “ListViewDeContratoCambio” (ID 1586)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| extGrid | ConfiguracaoDeGrid (query string) | Sim | Paginação e ordenação |
| valorDeConsulta | string | Não (padrão: vazio) | Busca livre (mesmos campos do “Listar”) |
| apenasACCACETRV | booleano | Não (padrão: falso) | Quando verdadeiro, limita o resultado aos modelos ACC, ACE e TRV |
“` GET /ContratoCambio/ListarParaLookupFatura?valorDeConsulta=&apenasACCACETRV=true&page=0&start=0&limit=30 “`
Exemplo de response: mesmo envelope de listagem do “Listar”.
GET /ContratoCambio/ListarParaLookupFaturaDeDesvinculacao
Janela de pesquisa específica da rotina de Desvinculação de Fatura: traz apenas contratos Abertos que já possuam Valor Vinculado maior que zero — ou seja, apenas contratos que efetivamente têm o que desvincular.
Permissão: ação de leitura sem permissão própria — coberta pela permissão de acesso à rotina “ListViewDeContratoCambio” (ID 1586)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| extGrid | ConfiguracaoDeGrid (query string) | Sim | Paginação e ordenação |
| valorDeConsulta | string | Não (padrão: vazio) | Busca livre (mesmos campos do “Listar”) |
“` GET /ContratoCambio/ListarParaLookupFaturaDeDesvinculacao?valorDeConsulta=&page=0&start=0&limit=30 “`
Exemplo de response: mesmo envelope de listagem do “Listar”.
POST /ContratoCambio/CancelarDocumento
Cancela um Contrato de Câmbio, alterando sua situação, e devolve a nova situação do contrato.
Permissão: [informação não disponível na análise de código — não existe entrada própria em “RecursosGeraisFinanceiro.cs” para essa ação; validar com o time técnico se é intencionalmente coberta pela permissão de rotina “ListViewDeContratoCambio” (ID 1586)]
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| IDContrato | string | Sim | Chave de fato do contrato a cancelar |
“` POST /ContratoCambio/CancelarDocumento
Content-Type: application/x-www-form-urlencoded
IDContrato=000004461 “`
“`json { “Titulo”: “Contrato cancelado.”, “Mensagem”: “Contrato cancelado com sucesso”, “Dados”: “C” } “`
Regra de negócio (confirmada por observação do sistema em produção — não pelo código-fonte, ver nota abaixo): o cancelamento só é aceito quando três condições são atendidas simultaneamente: (1) a Situação do Contrato está “Aberto”; (2) o Valor Vinculado do contrato (soma de faturas vinculadas) é igual a zero; e (3) não existe operação de liquidação parcial lançada para o contrato (operação financeira “TBCOLCC”). Faltando qualquer uma delas, a ação retorna erro sem alterar a situação do contrato.
GET /ContratoCambio/ObterPorIdLookup
Retorna os dados de um contrato para preencher automaticamente um campo de pesquisa (lookup) já preenchido em outra tela — por exemplo, ao reabrir uma tela de Vinculação de Fatura que já tinha um contrato selecionado.
Permissão: ação de leitura sem permissão própria — coberta pela permissão de acesso à rotina “ListViewDeContratoCambio” (ID 1586)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| id | string | Sim | Chave de fato do contrato |
“` GET /ContratoCambio/ObterPorIdLookup?id=000004461 “`
Exemplo de response: envelope padrão de busca (“JsonParaBusca”), com o registro sob a raiz “Entidade”.
GET /ContratoCambio/ObterPorNome
Consulta de contratos por texto livre, usada como pesquisa simplificada (sem o painel de filtros completo da tela principal), com opção de restringir aos modelos ACC, ACE e TRV.
Permissão: ação de leitura sem permissão própria — coberta pela permissão de acesso à rotina “ListViewDeContratoCambio” (ID 1586)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| extGrid | ConfiguracaoDeGrid (query string) | Sim | Paginação e ordenação |
| valorDeConsulta | string | Não (padrão: vazio) | Busca livre (mesmos campos do “Listar”) |
| ACCACETRV | booleano | Não (padrão: falso) | Quando verdadeiro, limita o resultado aos modelos ACC, ACE e TRV |
“` GET /ContratoCambio/ObterPorNome?valorDeConsulta=0001&ACCACETRV=false&page=0&start=0&limit=30 “`
Exemplo de response: mesmo envelope de listagem do “Listar”.
Modelos de Dados — DTODeContratoCambio
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| ID | string (9) | Não no Novo (gerado automaticamente se vazio) | Chave de fato do contrato — identificador único |
| IDDoTipo | string | Sim | Tipo do contrato (ex: E = Exportação) |
| IDDoModelo | string | Sim | Modelo do contrato (ACC, ACE, Antecipado Banco, Antecipado ADX/Adx, NDF, NDFC, TRV, PPE, Pronto) — determina o comportamento financeiro da inclusão |
| Codigo | string (10) | Sim | Código do contrato de câmbio |
| DataAbertura | data | Não (obrigatório na tela) | Data de abertura do contrato |
| DataVencimento | data | Não | Data de vencimento do contrato |
| DataEntregaDocs | data | Não | Data de entrega dos documentos |
| Valor | decimal | Não | Valor do contrato (moeda nacional) |
| ValorMoeda | decimal | Não | Valor do contrato em moeda estrangeira |
| Juros | decimal | Não | Percentual/valor de juros do contrato |
| ValorCotacao | decimal | Não | Cotação da moeda usada no contrato |
| IDDoStatus | string (1) | Sim | Status do contrato (ex: A = Aberto) — controla se o contrato pode ser editado/excluído |
| Observacao | string (255) | Não | Observação livre |
| IDDoCadastroGeral | int | Sim (validado como carteira) | Carteira de origem — ou, quando o modelo é Antecipado ADX, o cliente/participante padrão |
| IDDoCadastroGeralParticipante | int | Não | Participante específico, usado apenas no modelo Antecipado ADX quando informado (tem prioridade sobre IDDoCadastroGeral) |
| IDDoBancoCaixaDestino | int | Sim (validado como carteira) | Carteira de destino |
| IDDaMoeda | short | Sim | Moeda do contrato |
| ValorVinculadoMoeda | decimal | Não | Valor já vinculado a faturas (moeda estrangeira) — calculado, não informado no Novo |
| IDDaFilial | string | Sim | Filial do contrato |
| PrazoVencimento | int | Não | Prazo (em dias) para vencimento |
| PrazoEntregaDocumento | int | Não | Prazo (em dias) para entrega de documentos |
| DataCredito | data | Não | Data de crédito do contrato |
| ValorLiquidadoMoeda | decimal | Não | Valor já liquidado (moeda estrangeira) — calculado |
| ValorCotacaoOriginal | decimal | Não | Cotação original do contrato |
| Faturas | lista de DTODeContratoFatura | Não (usado em Vincular/Desvincular Faturas, não no Novo) | Faturas vinculadas/desvinculadas ao contrato |
| SaldoAVincular | decimal | Não (calculado) | Saldo do contrato ainda disponível para vincular a faturas |
| SaldoALiquidar | decimal | Não (calculado) | Saldo do contrato ainda disponível para liquidar |
Tabela física — TBCONTRATOCAMBIO
O INSERT do “Novo” é feito via ORM (não é SQL literal no código-fonte, mas o mapeamento abaixo define exatamente o INSERT gerado em tempo de execução), na tabela “TBCONTRATOCAMBIO” (ver “MapeamentoDeContratoCambio.cs”):
| Coluna | Tipo SQL | Campo do DTO |
|---|---|---|
| CHAVE_FATO (chave primária) | char(9) | ID |
| TIPO_CONTRATO | char(1) | IDDoTipo |
| MODELO_CONTRATO | varchar(20) | IDDoModelo |
| COD_CONTRATO | char(10) | Codigo |
| DATA_ABERTURA | datetime | DataAbertura |
| DATA_VENCTO | datetime | DataVencimento |
| DATA_ENTREGA_DOCS | datetime | DataEntregaDocs |
| VALOR_CONTRATO | decimal(15,2) | Valor |
| VALOR_CONTRATO_MOEDA | decimal(15,2) | ValorMoeda |
| PERC_JUROS | decimal(6,4) | Juros |
| VALOR_COTACAO | decimal(15,4) | ValorCotacao |
| STATUS | char(1) | IDDoStatus |
| OBSERVACAO | varchar(255) | Observacao |
| VALOR_VINCULADO_MOEDA | decimal(15,2) | ValorVinculadoMoeda |
| PRAZO_DIAS_VENCTO | int | PrazoVencimento |
| PRAZO_DIAS_ENTREGA_DOCS | int | PrazoEntregaDocumento |
| DATA_CREDITO | datetime | DataCredito |
| VALOR_LIQUIDADO_MOEDA | decimal(15,2) | ValorLiquidadoMoeda |
| VALOR_COTACAO_ORIGINAL | decimal(15,4) | ValorCotacaoOriginal |
| COD_CONTRATO_COMPLETO | varchar | CodigoContratoCompleto |
| COD_BANCO_CAIXA_ORIG (FK) | — | IDDoCadastroGeral (Carteira Origem) |
| COD_BANCO_CAIXA_DEST (FK) | — | IDDoBancoCaixaDestino (Carteira Destino) |
| COD_MOEDA (FK) | — | IDDaMoeda |
| COD_FILIAL (FK) | — | IDDaFilial |
Conforme o Modelo do contrato (ver Regra de Negócio 3, “Fator”), a operação de “Novo” pode gerar, na mesma transação, INSERTs adicionais (também via ORM) em outras tabelas — não fazem parte da tabela principal do contrato, mas são efeito colateral direto do cadastro:
- Movimentação financeira de débito/crédito (Fator 1 e 2) — tabela “TBMOVTOFIN”.
- Título a receber de adiantamento, documento “ADX” (Fator 2 — Antecipado ADX) — tabela “TBTITULOREC”.
Tabela física — TBMOVTOFIN (movimentação financeira — Fator 1 e Fator 2)
Rastreada via “FabricaDeMovimentacaoDeEntradaESaida.NovaMovimentacaoFinanceira” (chamada por “OperacaoFinanceira.IncluirMovimentacaoSemTitulo”). Um contrato Fator 1/2 gera dois registros (débito e crédito), com “COD_CADASTROCP” e “COD_CADASTRO” invertidos entre eles:
| Coluna | Campo/origem do valor |
|---|---|
| CHAVE_FATO | mesma chave de fato do contrato |
| COD_FILIAL | Filial do contrato |
| NUM_LANCTO | 1 (débito) / 2 (crédito) |
| COD_CADASTROCP | Cadastro Geral da contrapartida (Carteira Origem no débito, Carteira Destino no crédito) |
| COD_CADASTRO | Cadastro Geral do participante (Carteira Destino no débito, Carteira Origem no crédito) |
| COD_HISTORICO_PAD | histórico padrão do Fato Contábil resolvido para a operação “TBCOCCB” + variação do modelo |
| COD_DOCTO_OPERACAO | Código do Contrato |
| STATUS_CONCILIADO | “N” (não conciliado) na inclusão |
| TIPO_PARTIDA | “D” (débito) / “C” (crédito) |
| VALOR_LANCTO / VALOR_LANCTO_MOEDA | Valor Contrato / Valor Contrato Moeda |
| DATA_MOVTO | data de movimentação (data do usuário logado) |
| ATUALIZAR_MODULO | “B” (Banco) |
| COMPLEMENTO | texto do histórico do Fato Contábil |
| CHAVE_FATO_CONTRATO | chave de fato do contrato (setada explicitamente após criar o lançamento) |
| VALOR_COTACAO_LANCTO | Cotação Moeda do contrato |
| DATAHORA | data/hora do momento da gravação |
| OPERFIN | código da operação financeira do Fato Contábil (ex.: “TBCOCCB”) |
| CHAVE_FATO_INTEGRACAO | mesma chave de fato — usada depois pela integração contábil |
Tabela física — TBTITULOREC (título a receber de adiantamento — só no Fator 2, Antecipado ADX)
Rastreada via “FabricaDeContasAReceber.NovoTituloAReceber”:
| Coluna | Campo/origem do valor |
|---|---|
| CHAVE_FATO | nova chave de fato, gerada para o título (diferente da do contrato) |
| COD_FILIAL | Filial do contrato |
| COD_DOCTO | “ADX” (fixo) |
| SERIE_DOCTO / NUM_DOCTO | série ativa e próximo número da sequência “ADX” da filial |
| NUM_PARCELA / QTDE_PARCELA | 1 / 1 |
| COD_BANCO_CAIXA | Carteira Destino |
| COD_MOEDA | Moeda do contrato |
| DATA_EMISSAO | Data de Crédito do contrato (ou data de movimentação, se vazia) |
| DATA_VENCTO / DATA_VENCTO_UTIL | Data de Vencimento do contrato (ou data de movimentação, se vazia) |
| VALOR_TITULO / VALOR_TITULO_MOEDA | Valor Contrato / Valor Contrato Moeda |
| STATUS_TITULO | “Aberto” |
| NATUREZA_TITULO | “Realizado” |
| OBSERVACAO | Observação do contrato |
| CHAVE_FATO_ORIG | chave de fato do contrato de câmbio de origem |
| COD_FUNCIONARIO / COD_VENDEDOR | Cadastro Geral do funcionário vinculado ao usuário logado |
| VALOR_COTACAO | Cotação Moeda do contrato |
| COD_FORMA_COB | Forma de Cobrança do cliente/carteira |
| COD_CLIENTE | Cadastro Geral da Carteira Origem/Participante |
| DATA_HORA | data/hora do momento da gravação |
Em seguida, para o modelo Antecipado ADX, o sistema grava ainda um terceiro registro em “TBMOVTOFIN” (crédito, desta vez vinculado ao título recém-criado via “CHAVE_FATO_TITULO”, não “SemTitulo”) — mesma estrutura da tabela acima, mais essa coluna preenchida.
Regras de Negócio
- Chave de fato (ID): se o campo “ID” vier vazio na requisição, o sistema gera uma nova chave de fato automaticamente; se vier preenchido, usa o valor informado.
- Determinação do Cadastro Geral do contrato:
- Se “IDDoModelo” for “Antecipado ADX”: usa “IDDoCadastroGeralParticipante” quando informado e maior que zero; caso contrário usa “IDDoCadastroGeral” diretamente (sem validar como carteira).
- Para os demais modelos: “IDDoCadastroGeral” é validado como carteira (ver regra 4) e o Cadastro Geral vinculado a essa carteira é usado.
- Validação do Modelo do contrato: “IDDoModelo” precisa corresponder a um modelo cadastrado.Mensagem exibida: “Não foi possível obter modelo” — “Não foi informado um modelo valido para o contrato” — “Informar um modelo valido para o contrato. Código informado: [IDDoModelo]”.
- Validação de Carteira (aplicada a “IDDoBancoCaixaDestino” sempre, e a “IDDoCadastroGeral” quando o modelo não é Antecipado ADX):
- Se a carteira não foi informada (nula ou zero):Mensagem exibida: “Não foi possível obter carteira” — “A carteira informada está inválida” — “É obrigatório informar uma carteira valida.”
- Se a carteira informada não existe no cadastro:Mensagem exibida: “Não foi possível obter carteira” — “Carteira [id] não encontrada.” — “Verifique a carteira, corrija e tente novamente”
- Se a carteira existe mas não possui um Cadastro Geral vinculado:Mensagem exibida: “Não foi possível obter carteira” — “Carteira [id] não possui um cadastro vinculado.” — “Vincule um cadastro para a carteira e tente novamente”
4.1. Validação de Valor do contrato (no construtor da entidade “ContratoCambio”, executada após todas as validações acima): “Valor” (Valor Contrato em moeda nacional) não pode ser nulo nem zero.
> Mensagem exibida: “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 “ValorMoeda” (Valor Contrato Moeda) vier nulo ou zero, o sistema preenche automaticamente esse campo com o valor de “Valor”.
- Validação de Moeda (“IDDaMoeda”):
- Se não informada:Mensagem exibida: “Não foi possível obter moeda” — “Não foi informada a moeda” — “É obrigatório informar uma Moeda.”
- Se informada mas não encontrada no cadastro:Mensagem exibida: “Não foi possível obter moeda” — “A Moeda inserida não foi encontrada.” — “Informar moeda valida e tente novamente”
- Comportamento financeiro por “Fator” do Modelo (classificação interna do modelo do contrato, não é um campo do formulário):
- Fator 1 — Normal (ACC, ACE, Antecipado Banco): gera duas movimentações financeiras (débito na carteira de origem, crédito na carteira de destino) usando o valor do contrato.
- Fator 2 — Adiantamento (Antecipado ADX): exige que o Cliente (ou a carteira, conforme o caso) tenha uma “Forma de Cobrança” cadastrada; sem ela, a inclusão é bloqueada:Mensagem exibida: “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 [ID] para a inclusão do título de adiantamento”
Além da movimentação de débito, gera automaticamente um título a receber de adiantamento (documento “ADX”, com série e número obtidos da sequência ativa da filial) vinculado ao contrato.
- Fator 3 — Apenas contrato (Pronto, NDF Gravar, NDFC, TRV, PPE): não gera movimentação financeira na inclusão, exceto NDF/NDFC, que gera um único lançamento contábil sem título (histórico padrão do sistema). Apenas grava o contrato.
- Exceção: se o modelo for “Pronto”, o sistema, imediatamente após gravar o contrato, lança a liquidação automaticamente (crédito na carteira de destino, débito na carteira de origem) e, se o valor em moeda do contrato for igual ao valor liquidado, marca o contrato como “Liquidado”.
- Falta de Fato Contábil configurado (aplica-se aos modelos de Fator 1 e Fator 2, exceto NDF/NDFC): antes de gerar as movimentações financeiras, o sistema busca um Fato Contábil cadastrado para a operação financeira “TBCOCCB” combinada com a variação do modelo do contrato (ex.: Contrato Câmbio ACC, ACE, TRV, PPE, Antecipado Banco ou Antecipado ADX). Se não existir:Mensagem exibida: “Não foi possível inserir novo Contrato de Câmbio” — “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 da operação] / Variação: [nome da variação]”
- Transação e efeitos de persistência: toda a inclusão (contrato + título de adiantamento, quando houver + movimentações financeiras) ocorre dentro de uma única transação de banco de dados. Qualquer erro durante o processo desfaz a transação (rollback) e é relançado ao usuário como uma falha genérica de “Não foi possível inserir novo Contrato de Câmbio”, com a mensagem original da falha interna.
- Integração contábil automática: se movimentações financeiras foram geradas (Fator 1 ou 2), o sistema dispara a integração contábil para essas movimentações — desde que todas elas já possuam uma Operação Financeira associada. Caso contrário, a integração é adiada (apenas log interno, sem bloqueio nem mensagem ao usuário).
- Retorno da operação: após persistir com sucesso, o sistema busca novamente o contrato pelo ID gerado/informado e devolve esse registro atualizado, junto com a mensagem de sucesso “Novo Contrato Câmbio” / “inserido com sucesso”.
- Regra de bloqueio no Excluir (contexto complementar, útil para quem for reaproveitar a lógica de “Novo” em uma importação): um contrato só pode ser excluído se o valor vinculado a faturas (“ValorVinculadoMoeda”) for zero. Caso contrário:Mensagem exibida: “Não foi possível Excluir Contrato de Câmbio” — “O contrato [Codigo] [[ID]] possui faturas vinculadas e não pode ser excluido.” — “Para exclusão, desvincule faturas e tente novamente.”
- Trava de situação para Editar e Excluir: o Controller só encaminha a alteração ou a exclusão ao serviço quando o campo “IDDoStatus” (Situação do Contrato) recebido na requisição é igual a “A” (Aberto). Para qualquer outra situação — “L” (Liquidado) ou “C” (Cancelado) — a operação é recusada.Mensagem exibida: [informação não disponível na análise de código — a recusa dispara a mensagem interna “SALVAR_CONTRATO_CANCELADO”, mas o arquivo de textos de mensagens (ver “CAMINHO_MENSAGENS” em “apoio/caminhos.md”: “AtakSolution\ATAK.Exception\Base\Linguagens\Portugues.cs”) não existe no checkout analisado, então o texto literal exibido ao usuário não pôde ser transcrito — obter com o time técnico]
Observação importante: a situação avaliada é a que vem na requisição, não a gravada no banco. Como a tela de edição bloqueia o campo “Situação do Contrato”, na prática o valor enviado é sempre o do registro carregado.
- Escopo real do Editar: o serviço de edição não executa nenhuma validação de negócio própria — ele carrega o contrato pelo “ID” recebido, aplica sobre ele todos os campos do DTO por mapeamento automático e confirma a transação. Quem limita o que pode ser alterado é a tela: no modo Edição, o sistema bloqueia Chave Fato, Filial, Número do Contrato, Situação do Contrato, Tipo do Contrato, Modelo do Contrato, Carteira Origem, Participante, Carteira Destino, Data de Abertura, Data de Crédito, Data de Vencimento, Data de Entrega Documento, Moeda, Valor Contrato Moeda, Cotação moeda, Valor Contrato, Taxa Juros, Valor Vinculado Moeda, Valor Liquidado Moeda, Código do Contrato, Saldo a Vincular e Saldo a Liquidar. Restam editáveis apenas Prazo Vencimento, Prazo Entrega Documento e Observação — e o foco inicial da tela vai para “Prazo Vencimento”.
Consequência para integrações: uma chamada direta ao endpoint “Editar” (fora da tela) consegue alterar campos que a tela bloqueia, inclusive valores e cotação, sem passar por nenhuma das validações aplicadas no “Novo” (modelo, carteira, moeda, valor) e sem gerar ou ajustar as movimentações financeiras e a integração contábil correspondentes.
- Efeitos da exclusão (além do registro do contrato): confirmada a trava de faturas vinculadas (ver Regra 11), a exclusão roda dentro de uma única transação e, nesta ordem: (a) exclui as movimentações financeiras da chave de fato do contrato, (b) apaga os títulos a receber gravados com essa mesma chave de fato — via comando SQL direto na tabela “TBTITULOREC” —, e (c) exclui o contrato. Qualquer falha no meio do caminho desfaz tudo.Mensagem exibida em caso de falha: “Não foi possível realizar operação” — “[mensagem original da falha interna]” — “Verifique operação e tente novamente”
Se o “ID” informado não corresponder a nenhum contrato existente, o sistema não faz nada e não retorna erro — a resposta de sucesso é devolvida normalmente.
- Critério de “contrato disponível” nas janelas de pesquisa (lookup): as consultas que alimentam os campos de pesquisa de outras rotinas aplicam filtros próprios, diferentes da listagem principal:
- Padrão (com saldo): apenas contratos com Situação “A” (Aberto) e Saldo do Contrato maior que zero, onde Saldo do Contrato = Valor Contrato Moeda − (Valor Vinculado Moeda + Valor Liquidado Moeda).
- Modo desvinculação: apenas contratos com Situação “A” (Aberto) e Valor Vinculado Moeda maior que zero.
- Modo “todos” (usado no filtro “Número Contrato” da tela principal, que envia “apenasContratosAbertos=false”): nenhum filtro de situação ou de saldo — traz inclusive contratos Liquidados e Cancelados.
- Saldos calculados: os campos “Saldo a Vincular” e “Saldo a Liquidar” nunca são gravados — o sistema os calcula em toda consulta:
- Saldo a Vincular = Valor Contrato Moeda − Valor Vinculado Moeda
- Saldo a Liquidar = Valor Contrato Moeda − Valor Liquidado Moeda
Quando “Valor Contrato Moeda” está vazio, ambos os saldos são devolvidos como zero.
- Filtros de data da listagem trabalham como período: na tela principal, cada uma das três datas tem um par de campos. O campo simples (“Data de Abertura”, “Data de Crédito”, “Data de Vencimento”) filtra registros a partir de (maior ou igual) a data informada; o campo “Final” correspondente filtra até (menor ou igual). Informar só um dos dois deixa o período aberto naquela ponta.
- Busca livre da grade (campo de pesquisa rápida): o texto digitado é convertido para maiúsculas, tem os espaços das pontas removidos e as vírgulas trocadas por ponto (para permitir digitar valores como “1.500,00”). O sistema então procura correspondência exata em Filial, Chave de Fato e Número do Contrato, exata em Símbolo e Nome da Moeda, e parcial em Modelo do Contrato, Valor Contrato Moeda e Valor Vinculado Moeda. Se o texto digitado for reconhecido como uma data, o sistema ignora esses campos e procura pela Data de Abertura exata.
- Cálculo automático do Valor Contrato na tela (comportamento de tela, não do servidor): ao sair dos campos “Valor Contrato Moeda” ou “Cotação moeda”, o sistema calcula “Valor Contrato” = Valor Contrato Moeda × Cotação moeda, arredondado para 2 casas. Se o usuário digitar manualmente um “Valor Contrato” diferente desse 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” como Valor Contrato ÷ Valor Contrato Moeda (4 casas); recusando, devolve o “Valor Contrato” ao valor calculado.
- Modelo “Antecipado (ADX)” troca o campo de origem na tela: ao selecionar esse modelo, o sistema esconde o campo “Carteira Origem” (e o torna opcional) e exibe o campo “Participante” como obrigatório, buscando em Clientes. Para qualquer outro modelo, o comportamento é o inverso: “Participante” some e “Carteira Origem” volta a ser obrigatório. Nesse mesmo modelo, o sistema também torna “Data de Abertura” e “Data de Vencimento” obrigatórias.
- Situação do contrato — valores possíveis: “A” = Aberto, “L” = Liquidado, “C” = Cancelado. Tipo do contrato: “E” = Exportação, “I” = Importação. Ambos são listas fixas do sistema, não cadastros do usuário.
Permissões
Acesso à rotina: “ListViewDeContratoCambio” (ID 1586) — dentro de “Financeiro > Comex” (ID 1585)
| Ação | Permissão | ID |
|---|---|---|
| Novo | “ContratoCambio/Novo” | 3059 |
| Editar | “ContratoCambio/Editar” | 3060 |
| Excluir | “ContratoCambio/Excluir” | 3061 |
| Listar, ObterPorId, ObterPorIdLookup, ListarParaLookup, ListarParaLookupFatura, ListarParaLookupFaturaDeDesvinculacao, ObterPorNome (leitura) | coberta por “ListViewDeContratoCambio” | — |
| CancelarDocumento | [informação não disponível na análise de código — não foi encontrada entrada própria em “RecursosGeraisFinanceiro.cs” para essa ação; validar com o time técnico se é intencionalmente coberta pela permissão de rotina] | — |