• Avisos
  • Novidades
  • Documentação
  • Depoimentos
  • Blog
  • Materiais
  • Manuais
  • Dúvidas
  • Avisos
  • Novidades
  • Documentação
  • Depoimentos
  • Blog
  • Materiais
  • Manuais
  • Dúvidas

Documentação

  • ERP
    • Cadastro Geral (ERP)
      • Aprovação
        • Comercial
        • Contabilidade
        • Financeira
      • Cadastro geral
      • Consultas
        • Cadastro via SEFAZ
      • Manutenção de Cadastro Geral
      • Órgão Público
        • Item
        • Órgão Público
      • Propriedade rural
      • Relatórios
        • WRCAD009 - Relatório de cadastro geral
        • WRCAD080 - Relatório de endereços
        • WRCAD081 - Relatório de referências
        • WRCAD082 - Relatório de contatos
        • WRCAD083 - Relatório de parâmetros logísticos
        • WRCAD084 - Relatório de crédito de pessoa física
        • WRCAD085 - Relatório de propriedades rurais
        • WRCAD088 - Relatório de parâmetros financeiros
        • WRCAD089 - Relatório de clientes
    • Contabilidade
      • Cadastros
        • Centro de Custo
        • Divisão Contábil
        • Histórico Padrão
        • Lançamento Contábil Padrão
        • Livros Contábeis/Fiscais
        • Notas Explicativas
        • Perfil Contábil Item
        • Plano de Conta x Centro de Custo/Controle
        • Plano de Contas
      • Conciliação
        • Razão Auxiliar - Financeiro x Contábil
      • Consultas
        • Consulta Balancete
        • Consultas DRE
        • Validação do TMV
      • Custeio
        • Apuração Custeio
        • Centro de Custo
      • Demonstrativos
        • Lista de Modelos
      • Geração Arquivos
        • Lançamentos Contábeis
        • Razão Auxiliar – Implantação de Saldo
      • Lalur-Presumido
        • Apuração do IRPJ e da CSLL
      • Movimentações
        • Contábil Extemporâneo
        • Exercício Social
        • Integridade de Saldos Contábeis
        • Lote Contábil
        • Movimentação Contábil - Contabilidade
          • Exclusão de Lançamento - Movimentação Contábil
        • Razão Auxiliar
        • Validar Plano de Contas
      • Orçamento
        • Entidades
        • Entidades/Gestores
        • Geração de Orçamento
        • Indicadores
        • Manutenção de Orçamentos
        • Pacotes
        • Pacotes/Gestores
      • Rateio
        • Critério Rateio
        • Geração Rateio off-line
        • Lista de Modelos Rateio off-line
      • Relatórios
        • Exportação para Excel
        • WRCTD001 - Razão Contábil
        • WRCTD002 - Diário Contábil
        • WRCTD003 – Balanço Patrimonial
        • WRCTD004 - Balancete de Verificação
        • WRCTD005 – Demonstração de Resultado do Exercício
        • WRCTD007 - Conferência Lote Contábil
        • WRCTD008 - Conferência Lote Contábil (Sintético)
        • WRCTD010
        • WRCTD011 - Demonstração de Resultado do Exercício (Trimestral)
        • WRCTD023 – Orçamento Contábil por Pacote de Gastos (Modelo A)
      • Sped Contábil (ECD)
        • Bloco I
          • I053 - Subcontas Correlatas
          • I157 - Transferência de Saldos de Plano de Contas Anterior
        • Bloco K
          • K100 - Empresas Consolidadas
          • K200 - Plano de Contas Consolidadas
          • K300 - Saldos das Contas Consolidadas
        • Geração de Arquivo SPED Contábil
      • Sped Fiscal (ECF)
        • Bloco M
          • M312 - Números dos Lançamentos Relacionados à Conta Contábil IRPJ
          • M315 - Processo do Lalur
          • M362 - Números dos Lançamentos Relacionados à Conta Contábil CSLL
          • M365 - Processo do Lacs
          • M415 - Processo da Parte B
        • Bloco V
          • V010 - DEREX - Instituição
          • V020 - DEREX - Responsável Movimentação
          • V100 - DEREX - Demonstrativo dos recursos em moeda estrangeira
        • Bloco X
          • X280 - Atividade Incentivada
          • X291 - Pessoa Vinculada
          • X292 - Pessoa Não Vinculada
          • X300/X305/X310 - Exportações
          • X320/X325/X330 - Importações
          • X340/X350-X357 - Part. Exterior
          • X400/X410 - Comércio Eletrônico e Tecnologia da Informação
          • X420 - Royalties Rec./Pag. a Beneficiários do Brasil e do Exterior
          • X430 - Rendimentos relativos a Serviços, Juros e Dividendos
          • X450 - Pagamentos/Remessas Relativos a Serviços, Juros e Dividendos Recebidos do Brasil e do Exterior
          • X460 - Inovação Tecnológica e Desenvolvimento Tecnológico
          • X470 - Capacitação de Informática e Inclusão Digital
          • X480/X485 - Benefícios Fiscais - Parte I/Parte II
          • X490 - Pólo Industrial de Manaus e Amazônia Ocidental
          • X500 - Zonas de Processamento de Exportação (ZPE)
          • X510 - Áreas de Livre Comércio
        • Bloco Y
          • Y570 - IR/CSLL Retidos na Fonte
          • Y580 - Doações a Camp. Eleitorais
          • Y590 - Ativos no Exterior
          • Y600 - Ident. Sócios ou Titular
          • Y611 - Rendimentos
          • Y620 - Coligadas/Controladas
          • Y630 - Fundos/Clubes de Investimentos
          • Y640/Y650 - Part. Consórcio de Empresa
          • Y660 - Dados de Sucessora
          • Y665 - Diferenças na Adoção Inicial
          • Y671 - Outra Informação (LR)
          • Y672 - Outra Informação (LP/LA)
          • Y680/Y681 - Refis de Lucros
          • Y690 - Paes
        • Contas e Saldos Iniciais da Parte B
        • Controle de Saldos das Contas do E-lalur e do E-lacs (ParteB)
        • ECF Apuração
    • Controle Patrimonial
      • Cadastros
        • Bem — Cadastro de Bens do Controle Patrimonial
        • Local do Bem — Controle Patrimonial
        • Motivo de Ocorrência
        • Ocorrência do Bem — Controle Patrimonial
        • Ocorrências em Lote — Controle Patrimonial
        • Perfil Contábil do Patrimônio — Controle Patrimonial
      • Fechamentos
        • Depreciação (Simulador) - Controle Patrimonial
        • Fechamento de CIAP
        • Fechamento de CPCAP (Pis/Cofins) — Controle Patrimonial
        • Fechamento do Controle Patrimonial
      • Manuais, Procedimentos, Orientações e Boas Práticas
        • Implantação do Controle Patrimonial
        • Roteiro de Boas Práticas - Orientação de uso rotineiro do módulo Controle Patrimonial do ERP Atak
      • Relatórios
        • WRCPM050 — Relatório de Inventário de Bens (Analítico)
        • WRCPM051
        • WRCPM052 — Extrato de Ocorrência do Bem
        • WRCPM053 — Demonstrativo de Saldo de Bens por Grupo Contábil (Analítico)
        • WRCPM054 — Relação de Ocorrências com Bens por Período
        • WRCPM055
        • WRCPM056 — Ocorrências com Bens por Período (Sintético)
        • WRCPM057 — Extrato do Bem: Recuperação de Tributos
        • WRCPM058 — Resumo Mensal: Recuperação de Tributos
        • WRCPM059 — Lista de Bens a Serem Alocados
        • WRCPM060 — Conferência das Contabilizações das Ocorrências
        • WRCPM061 — Demonstrativo de Tributos a Recuperar
        • WRCPM062 — Relatório de Bens por Centro de Custo/Controle e Conta Contábil
    • Curtume
      • Cadastro de Classificações de Couro
      • Ordem de Produção Classificação de Couros
    • DF-e
      • NFS-e
        • Importação de NFS-e
        • Monitoramento de NFS-e
        • Transmissão de NFS-e
    • Escrita Fiscal
      • Apuração por UF
        • Conferência da Sistemática
        • ICMS Sistemática (PE)
        • Livro SEFAZ
        • Ocorrências do ICMS Antecipado (PE)
      • Apurações
        • Fechamento Apuração de IPI
        • Fechamento Apuração ICMS Difal
        • Fechamento Apuração ICMS-ST - Escrita Fiscal
        • Fechamento Apuração ISS
        • Fechamento Apuração PIS/COFINS - Escrita Fiscal
        • Fechamento Apuração Tributo (Genérico)
        • Período Apuração Tributos - Escrita Fiscal
      • Cadastros
        • 5.3 - Tabela de Ajustes e Informações de Valores Provenientes de Documento Fiscal
        • Classificação Tributária de Crédito Presumido IBS/CBS
        • Classificação Tributária IBS/CBS
        • Classificação Tributária IS
        • Código de Serviço NBS
        • Código Serviço Tributação Nacional do ISSQN
        • INSS - Escrita Fiscal
        • Modelo Guia de Tributos
        • Pauta de Tributo
        • Pauta Produto — Escrita Fiscal
        • Situação Tributária
          • Situação Tributária COFINS — Escrita Fiscal
          • Situação Tributária IBS/CBS — Escrita Fiscal
          • Situação Tributária ICMS — Escrita Fiscal
          • Situação Tributária IPI — Escrita Fiscal
          • Situação Tributária IS — Escrita Fiscal
          • Situação Tributária PIS - Escrita Fiscal
        • Tabela de Códigos de Ajuste da Apuração do IPI
        • Tabela de Códigos de Ajustes da Apuração do ICMS / Tabela de Informações Adicionais da Apuração - Valores Declaratórios
        • Tabela de Informações Adicionais dos Itens do Documento Fiscal
        • Tabela de Tipos de Utilização dos Créditos Fiscais de ICMS
        • Tabelas Códigos Receitas (Federal)
      • Escrita X Contabilidade
        • Consulta de Documentos Eletrônicos - CT-e
        • Consulta de Documentos Eletrônicos - NF-e
        • Consulta de Lançamentos Fiscais
        • Contabilização de Lançamentos Fiscais
        • Contabilização de Tributos Fiscais
        • Importar Notas do XML - Escrita Fiscal
      • Eventos
        • ECONF - Conciliação Financeira - Escrita Fiscal
        • Registro de Eventos — Escrita Fiscal
      • Módulo De Inclusão De Tributos
        • Declaração do MIT
      • Movimentações
        • Inventário de Estoque Fiscal
        • Livro de Registro de Exportação
        • Livro Registro de Importação — Escrita Fiscal
        • Manutenção de Geração de Tributos nos Documentos — Escrita Fiscal
        • Movimentação de Apuração de Tributo — Escrita Fiscal
      • Tabelas/Modelos
        • Exportação para Excel - Escrita Fiscal
        • Modelo de Ajuste de Apuração
      • Tributos
        • Alíquota Referência - Município
        • Alíquota Referência - País
        • Alíquota Referência - UF
        • Assistente de Parametrização IBS/CBS/IS
        • Configurador IBS/CBS/IS
        • Tributação por Item
        • Tributação por TMV — Escrita Fiscal
    • Faturamento
      • Dashboard de Documentos Eletrônicos
      • Geração de Documento Destino
      • Impressão de Documento Auxiliar, Quantidade de Impressões por TMV e Ordem
      • Rotina de Transferência de Participante
    • Financeiro
      • Cadastro
        • Moeda
      • Caixa
        • Depósito Não Identificado
        • Despesas
        • Devolução de Cheque a Receber Segunda Vez
        • Devolução de Cheque Próprio pela Primeira Vez
        • Reapresentação de Cheque de Terceiro
        • Reapresentação de Cheque Próprio
        • Receitas
      • Cobranca
        • Alteração da Forma de Cobrança
        • Alteração de Carteira
        • Alteração de Comissão
        • Alteração de Vencimento
        • Baixa de Título da Cobrança
        • Baixa de Título da Cobrança Descontada
        • CobrancaAlteracaoDeFormaDeCobranca
        • Consulta de Remessa
        • Consulta de Títulos
        • Consulta e Liquidação via API (PIX e Boleto)
        • Consulta e Liquidação via API (PIX)
        • Desconto de Duplicatas
        • Inclusão de Decréscimo
        • Inclusão de Desconto na Cobrança
        • Inclusão de Juros
        • Inclusão de Multa
        • Liquidação Manual
        • Remessa (arquivo)
        • Retorno (arquivo)
      • Comex
        • Contrato de Câmbio
          • Contrato de Câmbio
        • Desvinculação de Contrato x Fatura
        • Desvinculação De Fatura
          • Desvinculação de fatura
        • Juros Do Contrato
          • Juros do contrato
        • Juros para Contrato de Câmbio
        • Liquidação de Contrato
          • Liquidação de contrato
        • Liquidação de Fatura
          • Liquidação de fatura
        • Liquidação De Fatura Sem Contrato
          • Liquidação de Fatura Sem Contrato
        • Relatórios
          • Wrexp021 - Faturas Vinculadas X Contrato De Câmbio
            • WREXP021 - Faturas Vinculadas X Contrato De Câmbio
        • Vinculação de Contrato x Fatura
        • Vinculação De Fatura
          • Vinculação de fatura
      • Comex - Relatórios
        • Wrexp011 - Posição Financeira Exportação
          • WREXP011 - Posição Financeira Exportação
        • Wrexp012 - Posição Contrato Câmbio X Faturas Não Vinculadas Por Carteira
          • WREXP012 - Posição Contrato Câmbio x Faturas Não Vinculadas por Carteira
        • Wrexp013 - Contratos De Cambio X Faturas Vinculadas
          • WREXP013 - Contratos de Cambio X Faturas Vinculadas
      • Compensações
        • Pagar X Adto. A Fornecedor
          • Pagar x adto. a fornecedor
        • Pagar X Devolução A Fornecedor
          • Pagar x devolução a fornecedor
        • Receber X Adto. De Cliente
          • Receber x adto. de cliente
        • Receber X Devolução Cliente
          • Receber x devolução cliente
        • Receber X Pagar
          • Receber x pagar
      • Fechamentos
        • Banco
          • Banco
        • Financeiro
          • Financeiro
      • Pagamento
        • Inclusão de Desconto no Pagamento
      • Relatorios
        • Movimentação Financeira por Carteira - Conciliado
        • Relatório de Negativação SERASA
        • WRBNC001 - Fluxo de Caixa Analítico
        • WRBNC002 - Fluxo de Caixa Sintético
        • WRBNC003 - Fluxo de Caixa Analítico por Conta de Resultado
        • WRBNC004 - Fluxo de Caixa Sintético por Conta de Resultado
        • WRBNC005 - Fechamento Diário
        • WRBNC006 - Movimentação Financeira por Carteira
        • WRBNC007 - Movimentação Financeira por Carteira (sintética)
        • WRBNC008 - Fechamento Diário Detalhado
        • WRBNC010 - Fluxo de Caixa
        • WRBNC011 - Movimentação Financeira por Carteira e Conta Contábil
        • WRBNC090 - Conferência Diária Vendas Cupom Loja
      • Renegociações
        • Com Clientes
          • Com clientes
        • Com Fornecedores
          • Com fornecedores
      • Serviços
        • 2ª Via Boleto Cliente
          • 2ª via boleto cliente
        • 2ª Via Comprovante Lançamento
          • 2ª via comprovante lançamento
        • Envio De Negativação
          • Envio de Negativação
        • Geração Pix
          • Geração PIX
        • Manutenção De Remessa
          • Manutenção de Remessa
        • Retorno De Negativação
          • Retorno de Negativação
      • Serviços / Orgão Público
        • Empenho
          • Empenho
      • Transferencias
        • Adiantamento de Cliente
        • Adiantamento de Fornecedor
        • Transferência Entre Contas
        • Transferência Entre Múltiplas Contas
    • Obrigações Acessórias Federais
    • Suprimentos
      • Cadastros
        • Compradores Família Produtos
        • Fornecedores Família Produtos
      • Compra
        • Aprovação de Orçamentos (Cotações)
        • Aprovação de Pedidos de Compra
        • Aprovação de solicitação
        • Cotações de compra
        • Gerar cotações
        • Orçamentos de Fornecedores
        • Pedido de Compra sem Cotação
        • Pré-aprovação de orçamentos
        • Solicitação de Compras
      • Consumo
        • Devolução de consumo
        • Requisição de consumo
        • Solicitação de Materiais
      • Recebimento
        • Registro de entregas
      • Relatórios
        • WRSUP001 - Lista de compradores
        • WRSUP002 - Lista de fornecedores
        • WRSUP003 - Sugestão de compra
        • WRSUP004 - Solicitação de compra
        • WRSUP005 - Cotação
        • WRSUP006 - Orçamento
        • WRSUP007 - Análise de orçamentos
        • WRSUP008 - Entregas em atraso
        • WRSUP009 - Previsão de entrega
        • WRSUP010 - Conferência de carga x lançamentos de notas de entrada
        • WRSUP011 - Acompanhamento de compra
        • WRSUP012 - Solicitação de material
        • WRSUP013 - Gastos por centro de custo/controle
        • WRSUP014 - Gastos por conta contábil
        • WRSUP015 - Gastos por centro de custo/controle conta contábil
        • WRSUP016 - Ficha de histórico de produto
        • WRSUP017 - Histórico de fornecedor
        • WRSUP018 - Sugestão de Compras
    • Tabelas Auxiliares
      • Cadastros Gerais
        • Mensagem
Nenhum resultado encontrado
Inteligência Atak / Documentação / ERP / Financeiro / Comex

Contrato de Câmbio

Criado por Igor Ribeiro em 03 de setembro de 2026
•
Atualizado por Igor Ribeiro em 09 de outubro de 2026
Documentação Técnica

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).

01. VISÃO GERAL

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.

Observação de organização de código: o Controller físico está em “Controllers\Exportacao\ContratoCambioController.cs”, mas a rotina é registrada no menu e nas permissões sob o módulo “Financeiro” (“Menu.Financeiro” > “Comex” > “Contrato de Câmbio”).
02. ENDPOINTS

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:

NomeTipoObrigatórioDescrição
dtoDTODeContratoCambio (corpo da requisição)SimDados do novo contrato de câmbio — ver campos na seção “Modelos de Dados”
Exemplo de request:

“` 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 “`

Exemplo de response:

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:

NomeTipoObrigatórioDescrição
dtoDTODeContratoCambio (corpo da requisição)SimDados completos do contrato, incluindo o “ID” (chave de fato) do registro a alterar — ver campos na seção “Modelos de Dados”
dto.IDDoStatusstring (1)SimPrecisa ser “A” (Aberto). Qualquer outro status faz o sistema recusar a alteração (ver Regra de Negócio 12)
Exemplo de request:

“` 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 “`

Exemplo de response:

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:

NomeTipoObrigatórioDescrição
dtoDTODeContratoCambio (corpo da requisição)SimDados do contrato; apenas o “ID” (chave de fato) e o “IDDoStatus” são efetivamente usados
dto.IDDoStatusstring (1)SimPrecisa ser “A” (Aberto). Qualquer outro status faz o sistema recusar a exclusão (ver Regra de Negócio 12)
Exemplo de request:

“` POST /ContratoCambio/Excluir

Content-Type: application/x-www-form-urlencoded

ID=000004461&IDDoStatus=A “`

Exemplo de response:

“`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:

NomeTipoObrigatórioDescrição
idstringSimChave de fato do contrato
Exemplo de request:

“` GET /ContratoCambio/ObterPorId?id=000004461 “`

Exemplo de response:

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:

NomeTipoObrigatórioDescrição
extGridConfiguracaoDeGrid (query string)SimPaginação e ordenação da grade (página inicial, quantidade de registros, coluna de ordenação)
valorDeConsultastringNã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
filialstringNãoFiltra pela Filial exata
chaveFatostringNãoFiltra pela Chave de Fato exata
contratoCambiostringNãoUm ou vários números de contrato separados por barra vertical — filtra pela Chave de Fato de cada um
modeloContratoCambiostringNãoFiltra pelo Modelo do Contrato (ACC, ACE, Pronto, NDF, NDFC, TRV, PPE, OPC, Antecipado(Banco), Antecipado (ADX))
carteiraOrigemintNãoFiltra pela Carteira/Participante de Origem
carteiraDestinointNãoFiltra pela Carteira/Participante de Destino
statusstringNãoFiltra pela Situação do Contrato (“A” = Aberto, “L” = Liquidado, “C” = Cancelado)
tipoContratoCambiostringNãoFiltra pelo Tipo do Contrato (“E” = Exportação, “I” = Importação)
dataAberturadataNãoData de Abertura a partir de (limite inicial do período)
dataAberturaFinaldataNãoData de Abertura até (limite final do período)
dataCreditodataNãoData de Crédito a partir de
dataCreditoFinaldataNãoData de Crédito até
dataVencimentodataNãoData de Vencimento a partir de
dataVencimentoFinaldataNãoData de Vencimento até
Exemplo de request:

“` GET /ContratoCambio/Listar?valorDeConsulta=&filial=100&status=A&modeloContratoCambio=ACC&dataAbertura=2026-01-01&dataAberturaFinal=2026-12-31&page=0&start=0&limit=30 “`

Exemplo de response:

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:

NomeTipoObrigatórioDescrição
extGridConfiguracaoDeGrid (query string)SimPaginação e ordenação da grade da janela de pesquisa
idMoedastringNão (padrão: vazio)Restringe a pesquisa a contratos de uma moeda específica
valorDeConsultastringNão (padrão: vazio)Busca livre (mesmos campos do “Listar”)
apenasContratosAbertosbooleanoNã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
filtraVinculadoMaiorQueZerobooleanoNã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)
Exemplo de request:

“` 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:

NomeTipoObrigatórioDescrição
extGridConfiguracaoDeGrid (query string)SimPaginação e ordenação
valorDeConsultastringNão (padrão: vazio)Busca livre (mesmos campos do “Listar”)
apenasACCACETRVbooleanoNão (padrão: falso)Quando verdadeiro, limita o resultado aos modelos ACC, ACE e TRV
Exemplo de request:

“` 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:

NomeTipoObrigatórioDescrição
extGridConfiguracaoDeGrid (query string)SimPaginação e ordenação
valorDeConsultastringNão (padrão: vazio)Busca livre (mesmos campos do “Listar”)
Exemplo de request:

“` 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:

NomeTipoObrigatórioDescrição
IDContratostringSimChave de fato do contrato a cancelar
Exemplo de request:

“` POST /ContratoCambio/CancelarDocumento

Content-Type: application/x-www-form-urlencoded

IDContrato=000004461 “`

Exemplo de response:

“`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.

Mensagem exibida quando bloqueado: 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 (operfin TBCOLCC).” Solução: “Realizar a desvinculação de Fatura ou Excluir a operação de Liquidação (TBCOLCC).”
Atenção — origem da evidência: o método de serviço “CancelarContrato” chamado por esta ação não foi encontrado no código-fonte analisado (nem na interface “IServicoDeContratosCambio”, nem em nenhuma implementação dentro de [C:\Branches\ERP_Trunk]) — o texto acima foi confirmado por captura de tela do sistema em produção, fornecida pelo usuário, e não pela leitura do código. Recomenda-se ao time técnico localizar o código-fonte real desse método (pode estar em outra branch/repositório não sincronizado neste checkout) para validar se há alguma condição adicional não coberta pela mensagem.

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:

NomeTipoObrigatórioDescrição
idstringSimChave de fato do contrato
Exemplo de request:

“` GET /ContratoCambio/ObterPorIdLookup?id=000004461 “`

Exemplo de response: envelope padrão de busca (“JsonParaBusca”), com o registro sob a raiz “Entidade”.

Atenção — retorno não verificável: o método de consulta “ObterPorIdLookup” chamado por esta ação não foi encontrado na interface “IConsultaDeContratoCambio” nem na implementação “ConsultaDeContratoCambio.cs” do código-fonte analisado. Os campos exatos devolvidos não puderam ser levantados. [informação não disponível na análise de código — validar com o time técnico; o código-fonte desse método parece estar fora do checkout analisado]

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:

NomeTipoObrigatórioDescrição
extGridConfiguracaoDeGrid (query string)SimPaginação e ordenação
valorDeConsultastringNão (padrão: vazio)Busca livre (mesmos campos do “Listar”)
ACCACETRVbooleanoNão (padrão: falso)Quando verdadeiro, limita o resultado aos modelos ACC, ACE e TRV
Exemplo de request:

“` GET /ContratoCambio/ObterPorNome?valorDeConsulta=0001&ACCACETRV=false&page=0&start=0&limit=30 “`

Exemplo de response: mesmo envelope de listagem do “Listar”.

Atenção — assinatura não confirmada: a versão de “ObterPorNome” com esses 4 parâmetros não foi encontrada na interface “IConsultaDeContratoCambio” nem na implementação analisada (que só possui a versão com os 17 parâmetros de filtro usada pelo “Listar”). O comportamento descrito acima é a leitura direta do Controller. [informação não disponível na análise de código — validar com o time técnico; o código-fonte dessa versão parece estar fora do checkout analisado]
03. MODELOS DE DADOS — DTODECONTRATOCAMBIO

Modelos de Dados — DTODeContratoCambio

CampoTipoObrigatórioDescrição
IDstring (9)Não no Novo (gerado automaticamente se vazio)Chave de fato do contrato — identificador único
IDDoTipostringSimTipo do contrato (ex: E = Exportação)
IDDoModelostringSimModelo do contrato (ACC, ACE, Antecipado Banco, Antecipado ADX/Adx, NDF, NDFC, TRV, PPE, Pronto) — determina o comportamento financeiro da inclusão
Codigostring (10)SimCódigo do contrato de câmbio
DataAberturadataNão (obrigatório na tela)Data de abertura do contrato
DataVencimentodataNãoData de vencimento do contrato
DataEntregaDocsdataNãoData de entrega dos documentos
ValordecimalNãoValor do contrato (moeda nacional)
ValorMoedadecimalNãoValor do contrato em moeda estrangeira
JurosdecimalNãoPercentual/valor de juros do contrato
ValorCotacaodecimalNãoCotação da moeda usada no contrato
IDDoStatusstring (1)SimStatus do contrato (ex: A = Aberto) — controla se o contrato pode ser editado/excluído
Observacaostring (255)NãoObservação livre
IDDoCadastroGeralintSim (validado como carteira)Carteira de origem — ou, quando o modelo é Antecipado ADX, o cliente/participante padrão
IDDoCadastroGeralParticipanteintNãoParticipante específico, usado apenas no modelo Antecipado ADX quando informado (tem prioridade sobre IDDoCadastroGeral)
IDDoBancoCaixaDestinointSim (validado como carteira)Carteira de destino
IDDaMoedashortSimMoeda do contrato
ValorVinculadoMoedadecimalNãoValor já vinculado a faturas (moeda estrangeira) — calculado, não informado no Novo
IDDaFilialstringSimFilial do contrato
PrazoVencimentointNãoPrazo (em dias) para vencimento
PrazoEntregaDocumentointNãoPrazo (em dias) para entrega de documentos
DataCreditodataNãoData de crédito do contrato
ValorLiquidadoMoedadecimalNãoValor já liquidado (moeda estrangeira) — calculado
ValorCotacaoOriginaldecimalNãoCotação original do contrato
Faturaslista de DTODeContratoFaturaNão (usado em Vincular/Desvincular Faturas, não no Novo)Faturas vinculadas/desvinculadas ao contrato
SaldoAVinculardecimalNão (calculado)Saldo do contrato ainda disponível para vincular a faturas
SaldoALiquidardecimalNã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”):

ColunaTipo SQLCampo do DTO
CHAVE_FATO (chave primária)char(9)ID
TIPO_CONTRATOchar(1)IDDoTipo
MODELO_CONTRATOvarchar(20)IDDoModelo
COD_CONTRATOchar(10)Codigo
DATA_ABERTURAdatetimeDataAbertura
DATA_VENCTOdatetimeDataVencimento
DATA_ENTREGA_DOCSdatetimeDataEntregaDocs
VALOR_CONTRATOdecimal(15,2)Valor
VALOR_CONTRATO_MOEDAdecimal(15,2)ValorMoeda
PERC_JUROSdecimal(6,4)Juros
VALOR_COTACAOdecimal(15,4)ValorCotacao
STATUSchar(1)IDDoStatus
OBSERVACAOvarchar(255)Observacao
VALOR_VINCULADO_MOEDAdecimal(15,2)ValorVinculadoMoeda
PRAZO_DIAS_VENCTOintPrazoVencimento
PRAZO_DIAS_ENTREGA_DOCSintPrazoEntregaDocumento
DATA_CREDITOdatetimeDataCredito
VALOR_LIQUIDADO_MOEDAdecimal(15,2)ValorLiquidadoMoeda
VALOR_COTACAO_ORIGINALdecimal(15,4)ValorCotacaoOriginal
COD_CONTRATO_COMPLETOvarcharCodigoContratoCompleto
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:

ColunaCampo/origem do valor
CHAVE_FATOmesma chave de fato do contrato
COD_FILIALFilial do contrato
NUM_LANCTO1 (débito) / 2 (crédito)
COD_CADASTROCPCadastro Geral da contrapartida (Carteira Origem no débito, Carteira Destino no crédito)
COD_CADASTROCadastro Geral do participante (Carteira Destino no débito, Carteira Origem no crédito)
COD_HISTORICO_PADhistórico padrão do Fato Contábil resolvido para a operação “TBCOCCB” + variação do modelo
COD_DOCTO_OPERACAOCódigo do Contrato
STATUS_CONCILIADO“N” (não conciliado) na inclusão
TIPO_PARTIDA“D” (débito) / “C” (crédito)
VALOR_LANCTO / VALOR_LANCTO_MOEDAValor Contrato / Valor Contrato Moeda
DATA_MOVTOdata de movimentação (data do usuário logado)
ATUALIZAR_MODULO“B” (Banco)
COMPLEMENTOtexto do histórico do Fato Contábil
CHAVE_FATO_CONTRATOchave de fato do contrato (setada explicitamente após criar o lançamento)
VALOR_COTACAO_LANCTOCotação Moeda do contrato
DATAHORAdata/hora do momento da gravação
OPERFINcódigo da operação financeira do Fato Contábil (ex.: “TBCOCCB”)
CHAVE_FATO_INTEGRACAOmesma chave de fato — usada depois pela integração contábil
Os códigos exatos de “STATUS_CONCILIADO”/”ATUALIZAR_MODULO” e o id de “COD_HISTORICO_PAD” dependem de listas fixas e do Fato Contábil configurado no ambiente — confirmar os valores literais com o time técnico antes de reproduzi-los na importação.

Tabela física — TBTITULOREC (título a receber de adiantamento — só no Fator 2, Antecipado ADX)

Rastreada via “FabricaDeContasAReceber.NovoTituloAReceber”:

ColunaCampo/origem do valor
CHAVE_FATOnova chave de fato, gerada para o título (diferente da do contrato)
COD_FILIALFilial do contrato
COD_DOCTO“ADX” (fixo)
SERIE_DOCTO / NUM_DOCTOsérie ativa e próximo número da sequência “ADX” da filial
NUM_PARCELA / QTDE_PARCELA1 / 1
COD_BANCO_CAIXACarteira Destino
COD_MOEDAMoeda do contrato
DATA_EMISSAOData de Crédito do contrato (ou data de movimentação, se vazia)
DATA_VENCTO / DATA_VENCTO_UTILData de Vencimento do contrato (ou data de movimentação, se vazia)
VALOR_TITULO / VALOR_TITULO_MOEDAValor Contrato / Valor Contrato Moeda
STATUS_TITULO“Aberto”
NATUREZA_TITULO“Realizado”
OBSERVACAOObservação do contrato
CHAVE_FATO_ORIGchave de fato do contrato de câmbio de origem
COD_FUNCIONARIO / COD_VENDEDORCadastro Geral do funcionário vinculado ao usuário logado
VALOR_COTACAOCotação Moeda do contrato
COD_FORMA_COBForma de Cobrança do cliente/carteira
COD_CLIENTECadastro Geral da Carteira Origem/Participante
DATA_HORAdata/hora do momento da gravação
Os códigos literais exatos de “STATUS_TITULO” e “NATUREZA_TITULO” (prováveis “A” e “R”) não foram confirmados olhando a lista fixa correspondente — validar antes de reproduzir na importaçã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.

04. REGRAS DE NEGÓCIO

Regras de Negócio

  1. 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.
  2. 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.
  1. 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]”.
  2. 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”.

  1. 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”
  1. 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”.
  1. 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]”
  2. 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.
  3. 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).
  4. 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”.
  5. 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.”
  1. 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.

  1. 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.

  1. 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.

  1. 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.
  1. 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
05. PERMISSÕES

Permissões

Acesso à rotina: “ListViewDeContratoCambio” (ID 1586) — dentro de “Financeiro > Comex” (ID 1585)

AçãoPermissãoID
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]—
Observação relevante para uma futura funcionalidade de importação via Excel: não existe hoje nenhuma permissão “ContratoCambio/Exportar” nem “ContratoCambio/Importar” cadastrada em “RecursosGeraisFinanceiro.cs” — uma ação de importação nova precisaria de um ID de permissão próprio, a ser cadastrado nesse arquivo (backend legado) e replicado como enum em “EnumRecursosUsuario.cs” e navegação em “ModulosERP.cs”, caso a importação seja exposta também no novo frontend (ATAK-FrontendV2).

NA PÁGINA

  • Visão Geral
  • Endpoints
  • Modelos de Dados — DTODeContratoCambio
  • Regras de Negócio
  • Permissões
NEWSLETTER

Conteúdo para quem vive a indústria de alimentos

Receba conteúdos sobre tecnologia, gestão e inovação para a indústria de alimentos.

Acompanhe novidades, tendências e soluções para melhorar a eficiência da sua operação.

Produtos

  • ERP
  • Frigosoft
  • Força de Vendas
  • Coleta de Resíduos
  • Venda Ambulante
  • Coleta de Leite
  • BI Atak
  • EasyPAC
  • Delivery B2B

Soluções

  • Bovinos
  • Suínos
  • Aves
  • Ovinos
  • Pescados
  • Laticínios
  • Curtumes
  • Charqueadas
  • Distribuidores Entrepostos
  • Indústria de Alimentos em Geral

Conteúdos

  • Blog
  • E-books (em breve)
  • Podcasts (em breve)
  • Webinars (em breve)
  • Depoimentos

Ajuda

  • Dúvidas
  • Documentação (em breve)
  • Manuais (em breve)
  • Avisos (em breve)
  • Novidades (em breve)

Empresa

  • Sobre
  • Carreiras
  • Privacidade
  • Contato
  • llms.txt
  • llms-full.txt

Social

  • LinkedIn
  • Instagram
  • YouTube

© 2026 Atak Sistemas Todos os direitos reservados.

Av. Nildo Ribeiro da Rocha, 5766 Parque Tecnológico, Maringá/PR. CNPJ: 73.500.290/0001-06