Despesas
Despesas
A rotina “Despesas” pertence ao módulo Financeiro, dentro da tela “Caixa” (submenu raiz “Caixa”, recurso 1589).
Visão Geral
A rotina “Despesas” pertence ao módulo Financeiro, dentro da tela “Caixa” (submenu raiz “Caixa”, recurso 1589). Ela permite registrar o pagamento de uma despesa (saída de dinheiro) diretamente a partir de uma carteira do tipo Caixa ou Banco, gerando ao mesmo tempo a movimentação financeira e a respectiva integração contábil.
Endpoints
[POST] /Despesas/Salvar
Confirma o lançamento de uma única despesa informada pelo usuário na tela. Recebe o cabeçalho da operação com o parâmetro “TitulosAProcessar” (estrutura de contrato compartilhada com outras rotinas financeiras; nesta tela sempre contém um único elemento) e aciona a inclusão da despesa (movimentação financeira + lançamento contábil) a partir do primeiro (e único) item dessa lista. Ao final, retorna as movimentações financeiras e os lançamentos contábeis gerados para exibição/impressão do comprovante.
Permissão: “Despesas/Salvar” (ID 1858)
Parâmetros:
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| dto | DTOCabecalhoDeOperacoes | Sim | Cabeçalho da operação. Campos relevantes usados por esta ação: |
| dto.TitulosAProcessar | Lista de DTODeTituloAProcessar (contrato compartilhado; nesta tela sempre 1 item) | Sim (não pode ser vazia) | Estrutura interna que carrega o único lançamento de despesa desta tela; apenas o primeiro item é efetivamente gravado nesta ação |
| dto.IDDaCarteiraDePagamento (no título) | int | Sim | Carteira (Caixa/Banco) de onde sai o valor da despesa |
| dto.VariacaoDoFatoContabil | string (formato “algo|N”) | Sim | Fato Contábil + Variação escolhidos pelo usuário no lookup de Fato Contábil; a parte após o “|” é convertida para número (rotinaDeVariacao) e usada para localizar o registro de fato contábil |
| dto.IdHistoricoPadrao | int | Sim | Identificador do histórico padrão (texto/complemento do lançamento) |
| dto.Documento | string | Não | Número/identificação do documento associado à despesa |
| dto.IdCentroDeCusto | string | Não | Centro de custo para rateio da despesa |
| dto.Observacao | string | Não | Observação livre sobre o lançamento |
“` POST /Despesas/Salvar { “TitulosAProcessar”: [{ “IDDaCarteiraDePagamento”: 12, “Valor”: 500.00, … }], “VariacaoDoFatoContabil”: “Descrição|1”, “IdHistoricoPadrao”: 45, “Documento”: “NF-1234”, “IdCentroDeCusto”: “10”, “Observacao”: “Pagamento de fornecedor” } “`
“`json { “success”: true, “listaDeOperacoesFinanceiras”: [], “listaDeOperacoesContabeis”: [] } “`
[POST] /Despesas/Imprimir
Prepara o modelo de relatório (arquivo “.rpt”) usado para gerar o comprovante de movimentação financeira. Se a pasta de comprovantes do cliente ainda não existir, cria a pasta; se o arquivo de layout do comprovante ainda não existir na pasta do cliente, copia o layout padrão do sistema para lá. Não recebe parâmetros de negócio — apenas garante que a estrutura de arquivos para impressão do comprovante exista antes da geração do relatório.
Permissão: “Despesas/Imprimir” (ID 1859)
Parâmetros: nenhum.
“` POST /Despesas/Imprimir “`
“`json { “success”: true } “`
[GET] /Despesas/ObterCentroDeCustoDefault
Retorna o centro de custo padrão configurado para o financeiro, além de informações de moeda estrangeira (símbolo e cotação) da carteira padrão do usuário, quando aplicável. Usado para pré-preencher a tela de lançamento de despesa.
Permissão: ação marcada como acesso anônimo no código ([PermiteAcessoAnonimo]); na prática, o acesso à tela onde este dado é usado já é controlado pela permissão de acesso à rotina “EditViewDeDespesas” (ID 1591) — ver seção Permissões.
Parâmetros: nenhum (usa a carteira padrão configurada no XML de filtros do usuário logado).
“` GET /Despesas/ObterCentroDeCustoDefault “`
“`json { “success”: true, “centroDeCustoDefault”: “10”, “ehMoedaEstrangeira”: false, “simboloMoeda”: “”, “cotacao”: 0 } “`
Modelos de Dados
DTOCabecalhoDeOperacoes (campos relevantes para Despesas)
| Campo | Tipo | Descrição |
|---|---|---|
| TitulosAProcessar | Lista de DTODeTituloAProcessar (contrato compartilhado; nesta tela sempre 1 item) | Estrutura interna que carrega o único lançamento de despesa desta operação |
| VariacaoDoFatoContabil | string | Fato Contábil + Variação escolhidos pelo usuário no lookup de Fato Contábil |
| IdHistoricoPadrao | int | Histórico padrão usado para compor o texto do lançamento |
| Documento | string | Documento de referência da despesa |
| IdCentroDeCusto | string | Centro de custo para rateio |
| Observacao | string | Observação livre |
DTODeTituloAProcessar (campos relevantes para Despesas)
| Campo | Tipo | Descrição |
|---|---|---|
| IDDaCarteiraDePagamento | int | Carteira de onde sai o valor da despesa |
| Valor | decimal | Valor da despesa na moeda corrente |
| ValorMoeda | decimal | Valor da despesa em moeda estrangeira (quando aplicável) |
| DataEmissao | DateTime | Data de emissão do documento/lançamento |
Regras de Negócio
- Lista de títulos obrigatória. A ação “Salvar” só processa a despesa se “dto.TitulosAProcessar” existir e tiver ao menos um item. Se a lista estiver vazia ou nula, o sistema não realiza nenhum lançamento e dispara a mensagem de erro abaixo.Mensagem exibida: “Não foi possível Salvar. Os dados informados podem estar incorretos. Verifique se os dados informados estão corretos.”
- Carteira obrigatória e deve existir no cadastro geral. A inclusão da despesa busca o cadastro geral correspondente à carteira informada (“IDDaCarteiraDePagamento”). Se a carteira não for encontrada, a operação é interrompida antes de qualquer gravação.Mensagem exibida: “Não foi possível incluir Despesas. Carteira não encontrada. Favor informe uma carteira.”
- Reconciliação contábil entre filiais (mútuo) — condicionada ao tipo de carteira. A despesa em si é sempre lançada na carteira selecionada, na filial em que essa carteira está cadastrada (não há transferência entre carteiras). O sistema só avalia mútuo quando a carteira selecionada NÃO é do tipo Caixa: nesse caso, se a filial da carteira for diferente da filial em que o usuário está logado, o sistema entende que precisa reconciliar contabilmente as duas filiais (já que o lançamento foi originado por um usuário logado em uma filial diferente da filial dona da carteira) e gera, além da despesa, dois lançamentos adicionais de mútuo — um de crédito na carteira de mútuo da filial do usuário logado e outro de débito na carteira de mútuo da filial da carteira selecionada. Quando a carteira selecionada É do tipo Caixa, o próprio sistema força a filial da carteira a ser igual à filial do usuário logado antes dessa checagem — portanto, para carteiras do tipo Caixa, mútuo nunca é gerado, independentemente da filial cadastrada na carteira.
- A “lista de títulos” do contrato interno não corresponde a uma lista de itens na tela. O parâmetro “dto.TitulosAProcessar” é uma estrutura de dados compartilhada com outras rotinas financeiras (algumas das quais realmente processam múltiplos títulos em lote); nesta tela de Despesas não existe um recurso de tela que permita ao usuário lançar várias despesas de uma vez — cada confirmação representa um único lançamento, e a ação “Salvar” sempre grava apenas o primeiro elemento da lista (dto.TitulosAProcessar[0]). A lista que o usuário efetivamente visualiza e utiliza nesta tela é o lookup de seleção de Fato Contábil, descrito a seguir.
- Seleção de Fato Contábil (lookup de Fato Contábil + Variação). O usuário escolhe o fato contábil do lançamento por meio de uma lista de consulta (lookup) que combina “Fato Contábil” e “Variação” (ex.: “35 – DESPESAS (BCODESP)” com variações como “200”, “201” etc.), cada combinação associada a uma “Conta Fato”/”Conta fixa” específica. O valor escolhido é enviado como “dto.VariacaoDoFatoContabil” (formato “descrição|número”) e usado para localizar, no backend, o registro de fato contábil correspondente (“ObterPorChaveAlternativa” com o código fixo “BCODESP” e o número da variação escolhida) — determinando assim qual conta contábil recebe o lançamento.
- Transação única e reversível. Toda a gravação (movimentação financeira + integração contábil) ocorre dentro de uma única transação de banco de dados. Se qualquer etapa falhar, nada é gravado e o sistema lança um erro de execução da movimentação financeira.
- Integração contábil automática. Após gravar a movimentação financeira, o sistema executa automaticamente a integração contábil (gera o lançamento contábil correspondente) e reprocessa o histórico financeiro e contábil da operação, sem ação adicional do usuário.
Lógica Contábil e Financeira
- Tabelas envolvidas: TBMOVTOFIN (movimentação financeira), gravada a partir da entidade “MovimentacaoFinanceira”.
- Fato(s) contábil(is) utilizado(s): “BCODESP” (rótulo de negócio: “DESPESAS”), combinado com a variação escolhida pelo usuário no lookup de Fato Contábil (“dto.VariacaoDoFatoContabil”). Quando a operação envolve mútuo entre filiais (apenas possível para carteiras que NÃO são do tipo Caixa — ver Regra de Negócio 3), é usado adicionalmente o fato “BCOMUT” (“MUTUO”), sem variação (Sem Variação).
- Lógica de gravação: o sistema obtém uma nova chave de operação (“idDaOperacao”) via serviço de sequência de numeração, monta a movimentação financeira (ou as três movimentações, no caso de mútuo) usando o fato contábil “BCODESP”/”BCOMUT”, a carteira e o histórico padrão informados, e vincula tudo a uma única chave de fato (“ChaveDeFato” = idDaMovimentacao, devolvida ao Controller). No caso simples (sem mútuo), apenas essa movimentação é enviada para “IServicoDeIntegracaoContabilDoFinanceiro.Execute(…)”; no caso de mútuo, as três movimentações mutuamente relacionadas são processadas juntas por “ProcessaLancamentosFinanceirosParaDespesaReceita(…)”. Toda a operação (gravação financeira + integração contábil) ocorre dentro de uma única transação (“GerenciadorDeUnidadeDeTrabalho.Corrente.BeginTran()”), com “Commit()” ao final ou reversão total em caso de erro.
- Compensação/baixa futura: não se aplica — a despesa lançada por esta rotina já nasce quitada (saída direta de caixa/banco), não gera título em aberto para baixa posterior.
Permissões
Acesso à rotina: “EditViewDeDespesas” (ID 1591) — recurso filho de “Caixa” (ID 1589).
| Ação | Permissão | ID |
|---|---|---|
| Salvar | “Despesas/Salvar” | 1858 |
| Imprimir | “Despesas/Imprimir” | 1859 |
| ObterCentroDeCustoDefault | coberta por “EditViewDeDespesas” (acesso à rotina) | — |