Financeiro - Transações Financeiras

O que é

A página de Transações Financeiras concentra todas as movimentações de dinheiro da sua empresa: entradas (Receita), saídas (Despesa) e movimentações entre contas próprias (Transferência). É aqui que cada lançamento ganha status, categoria, conta de origem (e destino, no caso de transferência), opcionalmente vínculo com uma excursão e o comprovante anexado.

O usuário normalmente chega nesta tela vindo do Dashboard Financeiro para registrar um pagamento que acabou de acontecer, conferir o que está pendente de confirmação, ou aplicar filtros para auditar um período. Os três KPIs no topo (Receitas, Despesas e Resultado) somam apenas as transações confirmadas dentro do filtro atual, então mudam ao estreitar por conta, categoria ou intervalo de datas.

Como usar

1. Vá em Módulos > Gestão Financeira > Transações no sidebar (ou abra diretamente /admin/financeiro/transacoes).
2. Para registrar uma entrada, clique em Receita (botão verde no canto superior direito). Para uma saída, clique em Despesa (botão vermelho ao lado). Para mover dinheiro entre contas próprias, abra /admin/financeiro/transacoes/create?tipo=transferencia.
3. No formulário, preencha:
   • Descrição - texto curto que identifica a movimentação (obrigatório, até 255 caracteres). Aparece como rótulo principal na listagem.
   • Valor - quanto a movimentação representa (mínimo R$ 0,01). O campo aceita formatação BRL e é sanitizado antes da validação.
   • Conta - conta bancária de origem (obrigatório). Mostra apenas as contas marcadas como ativas.
   • Conta de destino - só aparece quando o tipo é Transferência. Obrigatória nesse caso e precisa ser diferente da conta de origem.
   • Categoria - opcional. As opções são filtradas pelo tipo escolhido (categorias de despesa não aparecem em receita e vice-versa).
   • Data de lançamento - quando a movimentação ocorre (obrigatório).
   • Data de vencimento - opcional. Usada para identificar pendentes vencidos na listagem.
   • Status - Pendente ou Confirmado. Se marcar Confirmado já no cadastro, o sistema cria como pendente e logo em seguida executa a confirmação oficial (para garantir que o saldo da conta seja atualizado corretamente).
   • Excursão - opcional. Vincula a transação a uma excursão para que ela apareça no relatório financeiro daquela viagem.
   • Comprovante - anexo opcional. Aceita PDF, JPG, JPEG ou PNG com até 5 MB.
   • Recorrente - marque para repetir a transação. Quando ativo, é obrigatório informar a frequência (Diário, Semanal, Quinzenal, Mensal, Bimestral, Trimestral, Semestral ou Anual) e pode-se definir uma data limite em Recorrência fim.
4. Confirme em Salvar ou use Salvar e Criar Nova para abrir outro formulário já com o mesmo tipo selecionado (útil para lançar várias despesas em sequência).

Filtrar e localizar uma transação

A barra de filtros logo abaixo dos KPIs permite combinar:

• Buscar por descrição - busca parcial no texto da descrição.
• Tipo - Receita, Despesa ou Transferência.
• Status - Pendente, Confirmado ou Cancelado.
• Conta - restringe a uma conta bancária específica.
• Data início e Data fim - intervalo aplicado sobre a data de lançamento.

Os totais nos KPIs e a paginação respeitam os filtros ativos.

Ações por linha

Na coluna Ações de cada transação aparecem (conforme o status):

• Confirmar (check verde) - somente em Pendente. Aplica o valor ao saldo da conta.
• Editar (lápis) - disponível enquanto a transação não estiver Cancelada. Em transações já confirmadas, apenas descrição, observação, categoria, excursão e comprovante podem ser alterados.
• Cancelar (X vermelho) - abre modal de confirmação. Reverte o saldo da conta quando a transação estava confirmada.
• Excluir definitivamente (lixeira) - disponível apenas em pendentes ou canceladas. Confirmadas precisam ser canceladas antes de excluir, para preservar a integridade do saldo.

Casos especiais

Transferência entre contas

Use quando o dinheiro sai de uma conta sua e entra em outra conta sua (não afeta o resultado, só o saldo das duas). Selecione Conta (origem) e Conta de destino, que precisam ser diferentes. Não exige categoria de despesa nem de receita: a lista de categorias é exibida sem filtro de tipo.

Confirmar já na criação

Ao marcar Confirmado no formulário, o backend cria o registro como pendente e em seguida executa a confirmação oficial. Isso garante que o saldo da conta seja efetivamente atualizado (em versões anteriores criar direto como confirmado pulava esse passo e gerava o bug de "despesa somando ao saldo" quando depois era cancelada).

Editar uma transação já confirmada

Ao abrir Editar em uma transação confirmada, somente os campos informacionais ficam habilitados: Descrição, Observação, Categoria, Excursão e Comprovante. Tipo, conta, valor e datas não podem ser alterados sem antes cancelar e refazer.

Transação vencida

Se a data de vencimento já passou e o status ainda é Pendente, a etiqueta de status aparece como Vencido (vermelho) em vez de Pendente (amarelo). A data de vencimento também é exibida em vermelho abaixo da data de lançamento na própria coluna Data.

Lançamento recorrente

Marcar Recorrente exige escolher a frequência. A data limite (Recorrência fim) é opcional e, quando informada, precisa ser posterior à data de lançamento.

Anexar comprovante depois

Além do upload feito no formulário, existe endpoint dedicado (POST /admin/financeiro/transacoes/{transacao}/comprovante) para substituir/anexar o comprovante de uma transação existente. Comprovantes antigos são removidos do storage ao subir um novo.

Erros comuns e como resolver

• "Transações canceladas não podem ser editadas." - Causa: tentou abrir Editar ou enviar Update de uma transação com status Cancelado. Solução: crie uma nova transação para corrigir; canceladas são imutáveis para preservar o histórico.
• "Cancele a transação antes de excluir." - Causa: clicou em Excluir em uma transação Confirmada. Solução: clique em Cancelar primeiro (isso reverte o saldo) e depois em Excluir definitivamente.
• "Apenas transações pendentes podem ser confirmadas." - Causa: ação de confirmar foi enviada para uma transação já confirmada ou cancelada. Solução: atualize a página; o botão de confirmar só deve aparecer em pendentes.
• "Esta transação já está cancelada." - Causa: tentou cancelar uma transação que já está nesse status. Solução: ignore - não há ação pendente.
• Validação "different:conta_id" na conta de destino - Causa: em Transferência, escolheu a mesma conta como origem e destino. Solução: selecione contas diferentes nos dois campos.
• Validação "after:data_lancamento" em recorrência fim - Causa: a data limite da recorrência ficou antes (ou igual) à data de lançamento. Solução: escolha uma data futura ao lançamento.
• Upload de comprovante rejeitado - Causa: arquivo fora do tipo permitido (apenas PDF, JPG, JPEG, PNG) ou maior que 5 MB. Solução: converta para PDF/imagem e reduza o tamanho.

Onde encontrar

• URL: /admin/financeiro/transacoes
• Caminho no menu: Módulos > Gestão Financeira > Transações
• Permissão necessária: financeiro.transacoes (para confirmar: financeiro.transacoes.confirmar)
• Módulo necessário: Gestão Financeira (gestao-financeira)

Veja também

• Visão Geral do Financeiro
• Contas Bancárias
• Categorias Financeiras
• Contas a Pagar
• Dashboard Financeiro
• Relatório Financeiro da Excursão