Pagamentos, transações, IVA e promoções

Cada movimento financeiro é uma Transaction com:

• Tipo — income (recebimento) ou expense (despesa).
• Montante e data da transação.
• Método de pagamento — campo livre que tipicamente recebe valores como "cash", "card", "bank_transfer", "check".
• Descrição em texto livre.

Ligação ao histórico

Cada transação pode ligar-se a:

• Uma marcação (booking).
• Uma linha específica (booking_item) — útil quando há múltiplos serviços e o cliente paga separadamente.
• Um cliente directamente, mesmo sem marcação associada.

Quem registou também fica gravado (user_id) para auditoria.

O FIRO calcula o estado de pagamento ao nível da linha (BookingItem):

• amountPaid() — soma de transações income na linha.
• remainingAmount() — preço da linha menos pago.
• isFullyPaid() — booleano que indica se está totalmente saldada.

Isto significa que numa marcação multi-serviço com 3 itens, o cliente pode pagar 1 hoje e os outros depois. O sistema mantém o tracking certo.

O campo payment_method é livre. A equipa do negócio define os valores que faz sentido usar:

• Cash / dinheiro presencial.
• Cartão presencial (TPA físico).
• Transferência bancária com referência manual.
• MB Way com confirmação do recebimento.

Pagamento online vs. manual

Hoje o registo é manual: a equipa marca a transação no backoffice quando recebe. Integração com gateway online (Stripe, MB Way directo, Multibanco) está no roadmap. Vantagem actual: zero comissões cobradas pelo FIRO sobre o que o teu cliente paga.

Cada tenant tem o seu conjunto de VatRate:

• Por defeito: 0%, 6%, 13%, 23% (taxas portuguesas correntes).
• Cada taxa é editável (rótulo, valor) e pode estar activa/inactiva.
• Há sempre uma marcada como default para serviços que não escolhem explicitamente.

Cada serviço aponta a uma taxa via vat_rate_id e tem o flag price_includes_vat que indica se o preço apresentado já contém IVA.

O motor de Promotion é mais flexível do que parece. Cada promoção tem:

• Tipo — percent (% de desconto) ou fixed (valor absoluto).
• Valor do desconto.
• Datas (starts_at, ends_at) e flag active.
• Código de cupão opcional (coupon_code).

Scope flexível

O scope determina quando a promoção se aplica:

• Serviço específico — só vale para um serviço.
• Categoria — todos os serviços de uma categoria.
• Total do carrinho — desconto sobre o total da marcação.
• Mínimo de total — só aplica acima de um valor.
• Cupão — só aparece quando o cliente insere o código.

Snapshot da promoção

Quando uma promoção é aplicada, o estado é "congelado" em booking.promo_snapshot_json. Mesmo que a promoção seja alterada ou apagada depois, a marcação histórica mostra exactamente o que foi aplicado na altura.

Cupões são úteis para casos específicos:

• Campanhas de aquisição — código distribuído num parceiro ou influenciador.
• Recuperação de cliente inactivo — código pessoal para incentivar regresso.
• Pacotes especiais — código único para uma promoção sazonal.

O cliente insere o código no fluxo público. Se válido, o desconto entra no preview de preço antes de finalizar.

O backoffice dá visões essenciais:

• Receita por período — diária, semanal, mensal.
• Receita por profissional — base para cálculo manual de comissões enquanto o módulo dedicado não chega.
• Receita por método de pagamento — cash, cartão, transferência separados.
• Listagem completa de transações com filtros.

Relatórios mais avançados (churn, LTV, projecções) estão no roadmap dos planos Pro/Business.

Atenção a uma distinção importante: o módulo Invoice é para a faturação que o FIRO emite ao tenant pela subscrição, não para faturas que o tenant emite ao cliente final.

• Cada fatura cobre um período (period_start / period_end).
• Tem subtotal, extras, total, moeda EUR.
• Atravessa estados: draft → approved → published → paid.
• Pagamentos são registados via ManualPaymentEvent.

Para faturas ao cliente final integradas com Vendus, Moloni ou InvoiceXpress — está no roadmap.