Financeiro

O módulo Financeiro gerencia todo o ciclo financeiro da clínica: orçamentos, faturamento, pagamentos, produtos, procedimentos, relatórios de vendas, ticket médio e conciliação automática com o banco.

Visão Geral do Módulo

A tela principal exibe:

• Resumo de Caixa: Receita total do período, valores pendentes e inadimplentes
• Lista de Faturas com filtros por status, período e paciente
• Filtros Rápidos: Pendentes, Pagas, Parcialmente Pagas, Canceladas
• Atalhos: Nova Fatura, Novo Orçamento

---

Orçamentos

O que é um orçamento?

O orçamento permite apresentar ao paciente uma proposta de valor antes de emitir a fatura. Quando aprovado, é convertido em fatura com um clique.

Criar orçamento

1. Acesse Financeiro → Orçamentos → + Novo Orçamento
2. Selecione o paciente
3. Defina a data de validade (padrão: 30 dias)
4. Adicione itens:
   • Procedimento — busca da tabela de procedimentos com preço automático
   • Produto — busca do catálogo de produtos
   • Serviço personalizado — descrição e valor livres
5. Aplique desconto por item (se autorizado) ou global
6. Clique em "Salvar Orçamento"

Enviar ao paciente

Após salvar, clique em "Enviar por E-mail" ou "Copiar Link" para compartilhar o orçamento com o paciente. O paciente recebe um link de visualização onde pode aprovar ou recusar.

Converter em fatura

Quando o status do orçamento for APROVADO:

1. Abra o orçamento
2. Clique em "Converter em Fatura"
3. Confirme os dados
4. A fatura é criada automaticamente com os mesmos itens e valores

TIP

Orçamentos com validade expirada precisam ser reativados por um Admin antes da conversão.

Estados do orçamento

Status	Descrição
Rascunho	Salvo mas não enviado
Enviado	Link enviado ao paciente
Aprovado	Paciente aprovou — pronto para converter
Recusado	Paciente recusou
Expirado	Passou da data de validade
Convertido	Fatura gerada a partir deste orçamento

---

Ciclo de Vida de uma Fatura

RASCUNHO
    ↓ emissão
PENDENTE
    ↓ pagamento parcial
PARCIALMENTE PAGA
    ↓ pagamento total
PAGA → NFS-e emitida → Conciliação automática
    ↓ cancelamento
CANCELADA / ESTORNADA

---

Criação de Fatura

Pós-atendimento (manual)

Quando um agendamento é marcado como CONCLUÍDO, nenhuma fatura é gerada automaticamente. O operador deve abrir o agendamento e clicar em "Gerar Fatura" para iniciar o processo.

Nova fatura avulsa

1. Acesse Financeiro → + Nova Fatura
2. Selecione o paciente
3. Vincule a um agendamento (opcional)
4. Adicione itens:
   • Procedimento — com seleção da tabela de preços (Particular, Convênio etc.)
   • Produto — com baixa automática do estoque
   • Serviço personalizado
5. Defina a data de vencimento
6. Clique em "Emitir Fatura"

O total é calculado automaticamente conforme os itens são adicionados ou removidos.

---

Registrar Pagamento

Abra a fatura desejada e clique em "Registrar Pagamento":

Campo	Descrição
Método	Dinheiro, Cartão de Crédito, Cartão de Débito, PIX, Boleto, Plano de Saúde, Crédito
Valor	Pode ser parcial (fatura fica como "Parcialmente Paga")
Parcelas	Disponível para cartão de crédito
Gateway	Automático quando a integração está configurada

Pagamento via Gateway

1. Selecione o método de pagamento
2. PIX: QR Code gerado e exibido ao paciente
3. Cartão: Dados processados via link de pagamento seguro
4. Boleto: PDF gerado e enviado ao paciente

O status da fatura é atualizado automaticamente quando o pagamento é confirmado pelo gateway configurado — sem ação manual necessária.

---

Produtos

Em Financeiro → Produtos você gerencia o catálogo de produtos vendidos na clínica (cosméticos, materiais, suplementos etc.).

Cadastrar produto

1. Acesse Financeiro → Produtos → + Novo Produto
2. Preencha nome, SKU, categoria e preço de venda
3. Defina a unidade (UN, ML, G, KG, L, CX)
4. Informe o estoque inicial e o alerta de estoque mínimo
5. Salve

Movimentação de estoque

Sempre que um produto é adicionado a uma fatura paga, o estoque é decrementado automaticamente. Ao atingir o estoque mínimo, o Admin recebe uma notificação.

---

Procedimentos

Em Financeiro → Procedimentos você gerencia o catálogo de procedimentos e suas tabelas de preço.

Cadastrar procedimento

1. Acesse Financeiro → Procedimentos → + Novo Procedimento
2. Preencha nome, categoria, descrição e duração (em minutos)
3. Defina se requer sala específica
4. Adicione as entradas de preço na Tabela de Preços:
   • Ex: "Particular — R$ 850,00", "Convênio ABC — R$ 320,00"
5. Salve

INFO

O campo de duração é usado pelo módulo de agendamento para bloquear a agenda do profissional automaticamente.

Múltiplas tabelas de preço

Cada procedimento pode ter vários preços para diferentes convênios ou modalidades. Ao criar uma fatura, o operador seleciona qual tabela utilizar. O preço selecionado fica fixado na fatura e não se altera se a tabela for atualizada posteriormente.

---

Descontos

Papel	Limite de desconto
Owner	Sem limite
Admin	Sem limite
Recepcionista	Até o percentual configurado pelo Admin
Profissional	Não pode aplicar desconto

---

Emissão de NFS-e

Após o pagamento total de uma fatura, o sistema emite automaticamente a NFS-e via NFE.io:

1. Pagamento registrado
2. Background job enfileirado no Hangfire
3. NFS-e emitida em até 60 segundos
4. Número e URL da nota salvos na fatura
5. PDF disponível para download na fatura

Tratamento de falhas: Se a emissão falhar, a fatura permanece como paga e a NFS-e fica em status "Pendente". O sistema tenta reemissão automática até 5 vezes. Após falha definitiva, um alerta é exibido para o Admin.

---

Conciliação Bancária Automática

O sistema concilia automaticamente os pagamentos processados pelo gateway com as transações bancárias correspondentes.

Como funciona

Todos os pagamentos confirmados pelo gateway são conciliados automaticamente no momento da confirmação, sem nenhuma ação manual. O engine de matching usa o ID da transação do gateway como chave primária de correspondência.

Revisar pendentes

Transações que o sistema não conseguiu conciliar automaticamente aparecem em Financeiro → Conciliação → Pendentes de Revisão.

Para cada transação pendente:

• O sistema sugere os pagamentos mais prováveis (com percentual de confiança)
• Selecione o pagamento correto e clique em "Confirmar"
• Ou clique em "Ignorar" para transações sem correspondência

Acompanhar a conciliação

Em Financeiro → Conciliação → Resumo você vê:

• Total de transações processadas
• Taxa de conciliação automática (%)
• Valor conciliado vs. valor pendente
• Divergências que requerem atenção

Importação de extrato OFX

A importação manual de extratos bancários (para cobrir pagamentos fora do gateway) estará disponível em uma versão futura do sistema.

---

Relatório de Vendas

Em Financeiro → Relatórios → Vendas:

1. Selecione o período (data inicial e final)
2. Opcionalmente filtre por profissional, categoria ou unidade
3. Visualize:
   • Receita total e comparação com período anterior
   • Ticket médio e variação
   • Vendas por procedimento (ranking)
   • Vendas por produto
   • Vendas por profissional
   • Distribuição por método de pagamento
   • Evolução diária de receita

Exportação disponível em PDF e CSV.

---

Ticket Médio

Em Financeiro → Relatórios → Ticket Médio:

• Compare o ticket médio atual com o período anterior
• Identifique profissionais acima e abaixo da média
• Veja quais categorias de procedimento têm maior valor agregado

---

Confirmação via Gateway

O endpoint /webhooks/payment recebe notificações do gateway configurado pelo tenant:

• Valida a assinatura HMAC-SHA256 usando o secret do provider ativo
• Normaliza o evento para o formato interno (provider-agnostic)
• Atualiza o status da fatura para PAGA
• Inicia a conciliação automática

Idempotência

Cada notificação possui uma chave de idempotência que evita processamento duplicado caso o gateway reenvie a confirmação.

---

Permissões

Ação	Owner	Admin	Recep.	Prof.	Viewer
Ver faturas / orçamentos	✅	✅	✅	❌	✅
Criar fatura / orçamento	✅	✅	✅	❌	❌
Converter orçamento	✅	✅	✅	❌	❌
Registrar pagamento	✅	✅	✅	❌	❌
Aplicar desconto	✅	✅	Até limite%	❌	❌
Gerenciar produtos	✅	✅	❌	❌	❌
Gerenciar procedimentos	✅	✅	❌	❌	❌
Conciliar manualmente	✅	✅	❌	❌	❌
Ver relatório de vendas	✅	✅	❌	❌	✅
Emitir NFS-e	✅	✅	❌	❌	❌

Acesso

• URL: /app/finance
• Guard: Requer autenticação + papel Receptionist ou superior