Pular para o conteúdo principal

FinancialTransaction (Transacao Financeira)

A FinancialTransaction representa uma movimentacao financeira (receita ou despesa) no sistema.

Descricao​

Transacoes financeiras registram todas as entradas e saidas de dinheiro do petshop. Podem ser unicas, parceladas ou recorrentes, e se integram com vendas, faturas de cartao e conciliacao bancaria.

Dados​

Informacoes Basicas​

CampoTipoObrigatorioDescricao
nameTextoSimNome/descricao da transacao
valueMonetarioSimValor da transacao
typeSelecaoSim"expense" (despesa) ou "revenue" (receita)
statusSelecaoSim"pending" ou "paid"
dateDataSimData de vencimento
competence_dateDataSimData de competencia contabil

Valores de Pagamento​

CampoTipoObrigatorioDescricao
paid_dateDataCondicionalData do pagamento (se pago)
paid_valueMonetarioCondicionalValor efetivamente pago
discount_valueMonetarioCalculadoDesconto obtido (value - paid_value)
tax_valueMonetarioCalculadoJuros/multa (paid_value - value)
signal_valueMonetarioCalculadoValor com sinal (+ receita, - despesa)
final_dateDataCalculadopaid_date ou date

Conta de Pagamento​

CampoTipoObrigatorioDescricao
payment_accountSelecaoSim"financial_account", "credit", "payment_method"
financial_account_idReferenciaCondicionalConta financeira
credit_card_idReferenciaCondicionalCartao de credito
payment_method_idReferenciaCondicionalMetodo de pagamento
method_typeSelecaoCondicional"debit", "credit_card", "pix"

Recorrencia​

CampoTipoDescricao
payment_frequencySelecao"one_time", "fixed", "installment"
frequencySelecaoIntervalo de recorrencia
frequency_end_dateDataData final (se fixed)
installmentsNumeroNumero de parcelas
current_installmentNumeroParcela atual
financial_parent_referenceTextoID da transacao pai
frequency_updateSelecaoEscopo de edicao da serie

Categorizacao​

CampoTipoObrigatorioDescricao
financial_category_idReferenciaSimCategoria financeira
parent_financial_category_idReferenciaAutoCategoria pai
financial_cost_center_idReferenciaNaoCentro de custo unico
use_cost_center_allocationBooleanoNaoUsar rateio de custos
cost_center_allocationsArrayCondicionalRateio por centro de custo

Flags Especiais​

CampoTipoDescricao
is_invoiceBooleanoSe e fatura consolidada
is_transferBooleanoSe e transferencia entre contas
is_voucherBooleanoSe e voucher/vale
initial_balanceBooleanoSe e saldo inicial da conta
salaryBooleanoSe e salario
benefitBooleanoSe e beneficio
commissionBooleanoSe e comissao

Conciliacao Bancaria​

CampoTipoDescricao
reconciliatedBooleanoSe foi conciliado
bank_reconciliation_transaction_idReferenciaTransacao do extrato
before_reconciliate_statusTextoStatus antes da conciliacao
created_from_bank_reconciliationBooleanoSe criado via conciliacao

Relacionamentos​

Pertence a​

EntidadeObrigatorioDescricao
AccountSimConta do petshop
StoreNaoFilial
FinancialAccountCondicionalConta bancaria
CreditCardCondicionalCartao de credito
PaymentMethodCondicionalMetodo de pagamento
FinancialCategorySimCategoria
FinancialCostCenterNaoCentro de custo
CustomerNaoCliente (receitas)
ProviderNaoFornecedor (despesas)
SaleNaoVenda associada
CheckoutNaoCheckout associado
PaymentNaoPagamento associado
FinancialInvoiceNaoFatura associada
FinancialTransferNaoTransferencia associada

Possui​

EntidadeDescricao
CostCenterAllocationsRateio por centro de custo
TransactionInvoiceTransacao de fatura espelhada

Tipos de Transacao​

Expense (Despesa)​

  • Saida de dinheiro
  • signal_value negativo
  • Exemplos: compras, salarios, contas

Revenue (Receita)​

  • Entrada de dinheiro
  • signal_value positivo
  • Exemplos: vendas, recebimentos

Ciclo de Vida (Status)​

Transicao Automatica para Paid​

Quando payment_account e:

  • credit: Status automaticamente vira "paid"
  • payment_method: Status automaticamente vira "paid"

Frequencia de Pagamento​

one_time (Unico)​

  • Transacao unica
  • Sem recorrencia

fixed (Recorrente)​

installment (Parcelado)​

Frequencias Disponiveis​

FrequenciaDescricao
dailyDiario
weeklySemanal
biweeklyQuinzenal
monthlyMensal
bimonthlyBimestral
quarterlyTrimestral
half_yearlySemestral
yearlyAnual

Atualizacao de Series​

Opcoes (frequency_update)​

OpcaoDescricao
update_onlyAtualiza apenas esta transacao
update_nextAtualiza esta e futuras
update_allAtualiza toda a serie

Campos Propagados​

  • name, value, type
  • payment_account, financial_account_id, etc.
  • financial_category_id
  • cost_center_allocations
  • Datas (recalculadas)

Conta de Pagamento​

financial_account (Conta Bancaria)​

  • Status editavel (pending/paid)
  • Suporta conciliacao bancaria
  • Afeta saldo da conta

credit (Cartao de Credito)​

  • Status automaticamente "paid"
  • Gera ou vincula FinancialInvoice
  • Calculado na fatura do cartao

payment_method (Metodo de Pagamento)​

  • Status automaticamente "paid"
  • Aplica taxas do metodo
  • Gera fatura do metodo

Geracao de Faturas​

Cartao de Credito​

Metodo de Pagamento​

Rateio de Centros de Custo​

Modo Simples​

  • Um financial_cost_center_id por transacao
  • 100% para um centro de custo

Modo Rateio (use_cost_center_allocation)​

Validacao​

  • Soma dos percentuais deve ser exatamente 100%
  • Valores calculados automaticamente

Conciliacao Bancaria​

Processo​

  1. Importar extrato bancario
  2. Sistema cria BankReconciliationTransaction
  3. Vincular transacao existente ou criar nova
  4. Transacao marcada como "paid" e "reconciliated"

Desfazer Conciliacao​

  • Se criada via conciliacao: transacao e destruida
  • Se existia antes: volta para status anterior

Transferencias​

Caracteristicas​

  • Marcada com is_transfer = true
  • Vinculada a FinancialTransfer
  • Status sincronizado entre as transacoes da transferencia

Tipos​

TransacaoTipoConta
SaidaexpenseConta origem
EntradarevenueConta destino

Calculos Automaticos​

signal_value​

Se type = "expense": signal_value = value * -1
Se type = "revenue": signal_value = value

discount_value​

Se status = "paid" e paid_value < value:
discount_value = (value - paid_value) * -1

tax_value​

Se status = "paid" e paid_value > value:
tax_value = paid_value - value

final_date​

Se status = "paid": final_date = paid_date
Senao: final_date = date

Validacoes​

CampoRegra
nameObrigatorio
valueObrigatorio, diferente de zero
typeDeve ser "expense" ou "revenue"
statusDeve ser "pending" ou "paid"
paid_dateObrigatorio se status = "paid"
paid_valueObrigatorio se status = "paid"
financial_accountObrigatorio se payment_account = "financial_account"
credit_cardObrigatorio se payment_account = "credit"
payment_methodObrigatorio se payment_account = "payment_method"
frequency_end_dateMaximo 5 anos apos date
cost_center_allocationsSoma = 100%

Automacoes​

Ao Criar​

  1. Define financial_parent_reference (se recorrente)
  2. Gera parcelas/recorrencias
  3. Vincula conciliacao bancaria (se aplicavel)
  4. Resolve divergencia de caixa (se aplicavel)

Ao Atualizar​

  1. Propaga alteracoes para serie (se frequency_update != "update_only")
  2. Sincroniza status de transferencia
  3. Atualiza voucher/pagamento
  4. Recalcula fatura

Ao Salvar​

  1. Calcula signal_value, discount_value, tax_value
  2. Atualiza saldo da conta
  3. Atualiza valor da fatura

Escopos​

EscopoDescricao
only_accountsApenas payment_account = "financial_account"
expensesApenas type = "expense"
revenuesApenas type = "revenue"
pendingApenas status = "pending"
paidApenas status = "paid"
not_reconciliatedNao conciliadas
only_invoicesApenas faturas
not_invoicesExceto faturas

Restricoes de Edicao​

TipoRestricao
initial_balanceNao pode editar/excluir
is_transferNao pode editar/excluir individualmente
is_voucherNao pode excluir
is_invoiceNao pode editar (somente leitura)
frequencyNao pode alterar apos criacao

Permissoes​

AcaoDescricao
CriarCriar nova transacao
EditarAlterar transacao (com restricoes)
ExcluirExcluir transacao (com restricoes)
PagarMarcar como pago
Desfazer pagamentoVoltar para pendente
ReconciliarVincular ao extrato