Skip to content

Banking e Accounts

Estado actual — calendário. Os filtros de semana e mês acompanham o dia de Londres, inclusive após retorno do app suspenso, com início e fim do período. O filtro não altera saldos acumulados nem o histórico completo de Accounts.

Estado actual — coordenação. Saldos e movimentos usam cálculos puros e contratos explícitos de recibos e transferências. A conciliação passa por application/reconcileBankCommands: envia a revisão fixada sem a recalcular, interrompe na primeira recusa e espelha somente aceites; transportes, cache e refresh permanecem na tela adaptadora.

Estado actual. Accounts é a área de controle de cada conta da entidade. Admin registra e corrige; manager consulta. A API /banking/accounts lê o histórico completo do D1, independentemente da janela do boot. A migração 0210 cria saldos iniciais, despesas, regras recorrentes, movimentos e provas de conciliação; a 0209 acrescenta a descrição opcional dos pagamentos de Drawings. A 0211 mantém extratos, linhas, vínculos auditados e uma revisão de banco de dados para proteger a conciliação contra gravações concorrentes. Banking → Conciliação é a tela única; o botão do Billing abre essa aba. Sem aba pedida e sem movimentos, Banking abre na primeira aba com itens (saldos da equipe a acertar); textos simples, com plural certo.

A tela compartilha um snapshot de contas entre as abas: entrada e retorno ao foco verificam os saldos, e gravações confirmadas ou invalidações de outros usuários os atualizam. Trocar somente a aba não relê todo o histórico. Drawings consulta suas retiradas apenas enquanto essa aba está aberta; alterações remotas deixam o cache inativo desatualizado para nova leitura ao abrir.

O saldo inicial representa o início da data escolhida, pode ser negativo e só é registrado uma vez. O saldo acumulado soma os movimentos confirmados desde aquela data, inclusive os do próprio dia. Filtros de período alteram entradas e saídas exibidas, sem recalcular o saldo como se a conta começasse em zero. Sem saldo inicial, a conta informa que o saldo inicial não foi registrado.

Recibos COMPLETED de invoices entram pela data e pelo valor realmente recebidos, inclusive pagamentos parciais e devoluções. Créditos e recebimentos em cash ou conta da equipe ficam fora das contas da empresa. O histórico normalizado é usado quando não há transações no JSON. Uma invoice PAID sem recibo não inventa dinheiro: fica fora do saldo e é sinalizada para revisão. Recebimentos brutos Stripe/GoCardless quitam a invoice, mas aguardam prova do repasse bancário; não entram como depósitos na conta. O repasse real é conciliado no extrato, sem outro recebimento do cliente; taxas retidas em clearing não são inventadas como uma saída do banco. Os pagamentos de Payroll e Drawings aparecem pela fonte original; não devem ser lançados novamente como despesas manuais.

Outras entradas e saídas exigem conta, pessoa/fornecedor, data, valor, referência e descrição. São registros de dinheiro já movimentado, sem executar pagamentos no banco.

Cada despesa tem entidade, fornecedor, categoria, descrição opcional, valor e vencimento. Pode ter link ou anexo de comprovante (PDF/imagem). O upload fica em R2 e o arquivo vinculado não pode ser apagado pela rota de mídia.

Criar uma despesa gera uma pendência, sem alterar a conta. Registrar pagamento exige conta da mesma entidade, data passada ou atual, valor e referência; descrição é opcional. Pagamentos parciais reduzem o restante. Uma única gravação guardada impede excesso e referências duplicadas; repetir a mesma instrução não cria dinheiro novamente. Alterações e cancelamento são permitidos antes de existir qualquer pagamento; ocorrências recorrentes podem ser ajustadas individualmente nesse momento. Cancelamento preserva o registro e deixa de contar como valor pendente.

A lista oferece pendentes, vencidas e todas, com paginação. O total previsto pertence à entidade (ou ao conjunto de entidades na visão geral): não presume que todas as despesas sairão de uma conta específica.

A regra define fornecedor, categoria, entidade, valor, descrição, primeiro mês, último mês opcional, dia de vencimento e frequência mensal, trimestral ou anual. Dias 29–31 usam o último dia de meses menores. O cron de cinco minutos prepara ocorrências até o mês atual; Gerar ocorrências previstas permite atualização imediata. Não há pagamento automático.

Uma ocorrência por regra/mês é garantida por índice único. A gravação da despesa e o avanço do próximo mês ficam no mesmo batch. Recuperação de períodos antigos é limitada a doze ocorrências por regra a cada execução e continua na próxima, sem perder pendências. Alterar valor ou fornecedor afeta somente ocorrências ainda não criadas. Mudar início/frequência exige pausar a regra e criar outra. Pausar não cancela despesas existentes; retomar ignora meses em que a regra esteve pausada. O último mês encerra a geração.

Transferências entre duas contas da mesma entidade criam saída e entrada vinculadas em uma única instrução SQL. Não são despesas e somam zero na posição consolidada. Transferências entre entidades jurídicas diferentes são recusadas neste fluxo.

Movimentos confirmados são imutáveis. Estornar registro incorreto pede motivo e confirmação, cria o inverso e mantém a prova original; não envia dinheiro. Estornar transferência restaura os dois lados atomicamente. Estornar um pagamento de despesa devolve o valor ao saldo pendente. Um segundo estorno do mesmo movimento é recusado. Contas e entidades com registros não podem ser removidas.

Drawings seguem a mesma regra (migração 0212). Estornar pagamento, no histórico da retirada, registra em owner_payment_reversals que o dinheiro voltou: mesma conta e método do original, data igual ou posterior, referência própria (única na entidade, também frente às referências de pagamento) e motivo; o original fica no histórico riscado e o valor volta a ser devido. Um estorno por pagamento; o estorno é imutável e entra no extrato como entrada (BANK_REVERSAL). Cancelar retirada só vale com saldo pago líquido zero, pede motivo e confirmação; a retirada cancelada deixa de ser devida, sai dos totais e da conciliação, e uma mensal cancelada não é preparada de novo naquele mês. O formulário de pagamento, o histórico e o cancelamento abrem dentro da própria linha, com o erro ali mesmo; Preparar o mês para todos prepara de uma vez os valores mensais que faltam.

O pagamento e sua conciliação bancária são provas distintas. O adaptador inbound consulta o PaymentID vinculado à InvoiceID e preserva AccountID, data, valor, referência e IsReconciled, quando fornecido como booleano pelo Xero. A revisão contábil mostra separadamente Conciliado no Xero, Não conciliado no Xero ou Status indisponível, com a data da observação; registros históricos sem esse campo permanecem desconhecidos. A prévia relê o pagamento antes de qualquer importação.

Um pagamento já confirmado por vínculo de organização, invoice e recibo não é outro recebimento: a importação existente reconhece a prova e não exporta dinheiro importado novamente. Uma mudança isolada em IsReconciled não altera a identidade financeira nem invalida uma aprovação; mudanças de conta, valor, data, referência, estado do pagamento ou organização continuam exigindo nova revisão. Conciliar um CSV no app nunca envia IsReconciled=true ao Xero.

O acesso atual à Accounting API não estabelece um vínculo com a linha bruta do extrato bancário. O CSV continua sendo a prova local de entrada e saída. A tela unificada não presume acesso a Bank Feeds nem trata pagamentos em clearing como dinheiro recebido na conta bancária. Antes de criar recebimentos em invoices já vinculadas ao Xero, consulta a prova atual e exige que os pagamentos externos existentes estejam comprovados e importados. A mesma tela oferece revisão e importação contábil; o aceite atualiza automaticamente a fila e os saldos. Registrar nova baixa de invoices destinadas à contabilidade conectada exige confirmar explicitamente a organização e a proteção dos valores, uma vez por lote; o servidor protege novamente essa organização na gravação.

Importe o CSV de uma conta, com início, fim e saldo final. Cada linha aparece lado a lado: o banco à esquerda, OK no meio e, à direita, o par proposto com o motivo (valor exato, nome do pagador, regra aprendida, referência, já registrado no app). Um só motor faz as propostas (statementMatching.ts): verde exige o valor exato mais quem é (nome do pagador, mesmo cortado pelo banco, regra aprendida ou o número de invoice do app na referência) e nenhum rival; valor sozinho nunca é verde, e a numeração antiga (INV1564) não conta. Âmbar mostra as opções para escolher ali mesmo; pagamento parcial (o restante continua devido) é sempre âmbar. Sem par abre o editor completo em Revisar. Um pagamento já registrado no app tem preferência sobre registrar de novo. Confirmar todas as verdes confirma o lote depois de mostrar cada linha e seu destino. Ao confirmar uma linha que não era verde, a caixa Lembrar (marcada) grava quem é aquele pagador (bank_match_rules, por empresa): cliente (manager também), funcionário ou fornecedor com categoria (só admin); a lista Regras de conciliação mostra e apaga as regras. Manager só recebe propostas de vínculo e de invoice. A lista começa pelas âmbar, depois sem par e por fim as verdes, com busca e filtros. Uma transferência do extrato pode pagar parte de um payslip: o restante continua devido, e a que completa o líquido marca PAID, pela regra de payslipSettlement.ts; acima do saldo é recusada (PAYSLIP_OVERPAID). O extrato fica salvo no servidor e pode ser retomado após recarregar. Cabeçalhos suportados incluem Date/Transaction Date, Description/Transaction Description, Amount ou Debit/Credit (também Money Out/Money In; uma saída com sinal negativo, como no Monzo, vale pelo valor), Balance, Reference e Transaction ID. Quando há uma coluna de pagador (Name, Counterparty, Payee), ela é a descrição e a Description (ou Notes) do banco vira a referência. Datas inválidas, colunas incompatíveis e valores ilegíveis impedem importar um arquivo incompleto. O limite é 2 MB e 2.000 linhas; saldo final ambíguo é informado manualmente, em qualquer convenção (1,234.56 ou 1.234,56); um valor ilegível mostra o erro em vez de não fazer nada. Sem saldo inicial, a diferença oferece Registrar saldo de abertura, que abre Accounts nessa conta.

A identidade de uma linha usa a conta e o ID verdadeiro do banco; sem esse ID, usa data, valor assinado, referência e descrição normalizados. Reimportações e períodos sobrepostos reaproveitam a linha e o vínculo existentes; uma linha com ID bancário ainda não conciliada (sem vínculo vivo, fora de extrato fechado) recebe a referência e a descrição novas (migração 0223); uma linha já conciliada mantém o texto com que foi conciliada e o resto do arquivo entra normalmente; a conta, a data e o valor continuam imutáveis. Uma coluna Account Name nunca é lida como pagador. Enquanto houver no app um pagamento registrado com o mesmo valor, só ligá-lo pode ficar verde. Linhas indistinguíveis no mesmo arquivo precisam de IDs bancários distintos. Uma referência bancária não comprova, sozinha, a identidade de uma transação.

Sugestões de pagamentos registrados exigem conta, direção, referência exata, valor exato e data próxima, com correspondência única nos dois sentidos. Uma linha pode agrupar até dez recibos da mesma referência, com soma exata. Valor igual sozinho nunca confirma. Sugestões de invoices reconhecem número completo ou cliente/apelidos e uma combinação exata, sem ambiguidade ou competição pela mesma invoice entre linhas. Confirmar correspondências exatas abre uma confirmação que lista cada linha e o destino (pagamentos vinculados, ou invoice, cliente e valor) antes de registrar o lote; casos ambíguos ficam para revisão manual. Ao resolver uma linha à mão, o botão só libera quando a soma escolhida bate com a linha; a lista de invoices traz as escolhidas e sugeridas primeiro e uma busca por número ou cliente.

Vincular pagamentos registrados associa uma ou mais fontes de dinheiro já confirmadas da mesma conta/direção, com soma exata. Não registra caixa novamente. A linha real determina a data de lançamento bancário na projeção de saldos, enquanto a data original do recibo permanece imutável. Cada movimento só pode ter um vínculo ativo; mudança ou desaparecimento da prova original deixa o vínculo pendente de revisão.

Recebimentos de invoices aloca a entrada a até dez invoices abertas do mesmo cliente, empresa e conta. Parciais deixam o saldo devido. O recibo e o vínculo bancário são gravados no mesmo batch protegido; falha reverte tudo. O ID real do banco distingue transferências de mesma data/valor/referência. Repetir a instrução não gera outra baixa. Sincronização contábil e recibos automáticos seguem a configuração existente, depois do aceite.

Admin também pode pagar despesa existente parcialmente, registrar despesa já paga (fornecedor/categoria), transferir entre contas da mesma entidade, pagar retirada pendente parcialmente, pagar uma folha aprovada de valor integral e registrar outra entrada/saída com pessoa e descrição. Fonte e vínculo compartilham um único batch. Transferências criam os dois lados, e o extrato da outra conta vincula sua ponta já existente. Folha usa o registro normalizado de payout e marca o payslip PAID, liquidando somente adiantamentos que existiam quando ele foi calculado; não cria uma despesa genérica duplicada. Retiradas usam owner_payments e preservam o saldo pendente. Manager importa, vincula e baixa invoices; outras gravações de caixa são exclusivas de admin.

Fechar extrato conciliado exige saldo inicial registrado em ou antes do início, todas as linhas vinculadas com provas atuais, todos os movimentos do app no intervalo presentes nesse extrato e diferença de saldo zero. Saldo acumulado anterior ao período é incluído. Uma diferença nunca gera ajuste fictício. O fechamento conserva histórico de provas datadas; novas alterações nas fontes tornam visível a necessidade de revisar o período.

Admin pode Reabrir para revisão com motivo e Desvincular pagamento registrado com motivo. Desvincular libera a correspondência, preservando o pagamento e o histórico anterior; corrigir um lançamento financeiro usa a origem e seu estorno/correção próprios. Um extrato fechado deve ser reaberto antes de alterar seus vínculos. Contas com extratos não podem ser removidas nem ter seus dados bancários substituídos.

As mutações preservam a instrução para retry, bloqueiam toque duplo e ignoram respostas após logout. Em lote, cada linha é atômica; se uma falhar, a mensagem diz quantas foram gravadas antes dela, e a fila atualizada mostra as restantes. O erro de uma linha aparece nessa linha; o aceite é um aviso (toast). Falha ao atualizar a lista depois do aceite informa que os registros foram salvos. O endpoint antigo de baixa de extratos do Billing responde 410 para clientes antigos atualizarem o app e usarem Banking.