Skip to content

Módulo 5 - Faturamento & Inteligência Financeira (billing)

Módulo 5: Faturamento & Inteligência Financeira (billing)

Section titled “Módulo 5: Faturamento & Inteligência Financeira (billing)”

Estado actual — notificações do QuickBooks. O webhook aceita CloudEvents e o formato anterior para faturas e pagamentos. A assinatura determina o ambiente que recebe a notificação.

Estado actual — conexões contábeis. A aba Accounting nas configurações fiscais oferece a conexão de produção do QuickBooks. A ativação da entrega automática é separada do OAuth. A transição para produção faz backup e limpa as cópias do sandbox antes de liberar a fila.

Estado actual — link da fatura. E-mail, WhatsApp e compartilhamento identificam o link como acesso à fatura. As opções de pagamento, quando disponíveis, ficam dentro da fatura. O botão no e-mail e nos novos modelos de WhatsApp é View invoice.

Estado actual — fatura no telefone. Na janela da fatura, as ações do documento ficam em Mais ações e o link de pagamento manual fica depois do documento, para a fatura aparecer primeiro. O campo do link tem rótulo persistente.

Estado actual — Conferência da equipe. As abas de Billing aparecem na barra conforme o espaço disponível. Em Conferência, a fila mantém as ações de baixa. O histórico consulta os recebimentos registrados pela data do pagamento em Londres, inclusive fora da janela operacional. Agrupa um mesmo recebimento lançado em várias visitas, mostra valores divididos por funcionário quando registrados e inclui pagamentos antigos atribuídos à equipe na fatura. Os totais do histórico representam entradas registradas e excedentes, separados do saldo ainda em posse da equipe.

Estado actual — forma de pagamento em Draft. A lista de visitas mostra a forma de pagamento efetiva, considerando a escolha da visita, o padrão do cliente e as opções da empresa emissora.

Estado actual — ordem das visitas. A fatura no app, no PDF e na página de pagamento lista os serviços da data mais antiga para a mais recente. Extras ficam logo abaixo da tarefa correspondente, com seus valores individuais e sem repetir o código ou a data. Tarefas sem data aparecem ao final.

Depósitos legados — adiantamentos no QuickBooks. Exportações de faturas de depósito emitidas antes da migração 0270 usam o item ativo Customer Deposit ligado ao passivo circulante Customer Prepayments. A linha do depósito identifica o serviço futuro, a data prevista e a referência da visita quando disponível. A fatura final referencia a fatura do depósito e só aplica o abatimento após conferir o depósito pago na mesma organização. Vínculos históricos continuam verificáveis no formato original.

Estado actual — depósito é pedido de pagamento. Desde a migração 0270, o depósito de uma visita avulsa é um pedido de pagamento (payment_request), não uma fatura: o documento, a página de pagamento e o e-mail dizem “Deposit request — this is not a VAT invoice”, ele mantém a referência DEP-, o link de pagamento, Stripe/GoCardless e a conciliação bancária, nunca vai ao QuickBooks/Xero e não entra nos totais faturados. A visita tem uma única fatura, com o serviço inteiro; quem emite (Billing, rascunho enviado, fatura automática na conclusão, cancelamento) aplica o pedido pago como pagamento (depositApplicationsFor, source: DEPOSIT_REQUEST, método CREDIT — o dinheiro conta uma vez, no pedido) e o documento mostra “Deposit paid” e o saldo. O cancelamento sempre fatura o depósito retido (CAN-), quitado pelo pedido quando ele cobre a taxa. Empresas com VAT só pedem depósito no mesmo trimestre de VAT da visita (cadastro da entidade: trimestres terminando em jan/abr/jul/out, fev/mai/ago/nov ou mar/jun/set/dez; Prime = jan/abr/jul/out); sem o trimestre preenchido o pedido é recusado. Uma visita com pedido de depósito não pode ser remarcada para outro trimestre de VAT (Edit task e Admin recusam, explicando como refazer). Quando as horas mudam, a fatura usa o valor real e o depósito entra como valor fixo; se a fatura ficar menor que o depósito, só o que ela deve é aplicado, a sobra vira crédito do cliente na emissão e a fatura (com as visitas) já sai paga. No QuickBooks, o valor do depósito no feed bancário é lançado como recebimento do cliente e aplicado à fatura da visita; o app liga esse pagamento ao depósito aplicado. Depósitos emitidos antes continuam faturas, com a linha “Less deposit paid” na final.

Estado actual — data da fatura. A fatura recebe a data do dia em que é emitida, mas admin e manager podem escolher outra ao emitir o rascunho (campo Invoice date no painel de emissão) ou corrigir a de uma fatura já emitida em Correções da fatura → A data da fatura (prévia, motivo obrigatório, auditado). A regra é uma só (issueDateRefusal): nunca no futuro, no máximo 14 dias antes da emissão real (a janela do VAT britânico depois do serviço), no ano da série do número e em ordem de data com as faturas vizinhas da série. A emissão com data usa a série do ano escolhido. A correção é recusada quando a fatura já está no QuickBooks ou no Xero; número, linhas, valores e recebimentos nunca mudam. Uso típico: visitas do mês faturadas no dia 1º com a data do último dia do mês, para o VAT cair no trimestre certo.

Estado actual — pagamentos no QuickBooks. O QuickBooks recebe só as faturas. A baixa é feita no QuickBooks, conciliando com o feed bancário, e volta ao app pela sincronização bidirecional. Com o QuickBooks conectado, o app não registra recebimento bancário (transferência, conta da empresa) de uma fatura que está nos livros: a baixa manual, a confirmação de uma transferência do cliente e o vínculo de uma linha do extrato recusam (paymentRecordedInBooks, 409 RECORD_IN_QUICKBOOKS), e a tela de pagamento da fatura troca Record payment por um aviso e Abrir no QuickBooks (booksInvoiceUrl). Dinheiro e conta de um cleaner, gateways (Stripe, GoCardless) e pedidos de depósito continuam sendo registrados no app. Uma fatura que o cliente disse ter pago (PENDING_REVIEW) é quitada pelo pagamento importado do QuickBooks: é o banco confirmando o que o cliente disse. Uma fatura reemitida numa correção de preço (o documento REISSUE é ela mesma) importa a baixa como uma fatura comum; um documento que ainda corrige a fatura (crédito, complemento, nova reemissão) continua pedindo conferência. Um recebimento registrado no app antes desta regra continua no app e nunca é criado no QuickBooks: uma fatura já paga aqui chega lá em aberto. Quando a baixa é feita lá, o app liga o pagamento do QuickBooks ao recebimento local (linkLocalReceipts, vínculo LINK-, sem dinheiro novo e sem alterar a fatura) se houver exatamente um recebimento local com o mesmo valor, o mesmo cliente e conta bancária confirmada; o vínculo guarda data, referência e conta do pagamento remoto, e qualquer alteração posterior volta a pedir conferência. Pagamentos divididos de forma diferente ficam para conferência. Faturas de depósito também importam a baixa do QuickBooks: o depósito da visita passa a pago, a visita não. Recebimentos já exportados antes desta regra continuam sendo conferidos. A importação automática revisa e aprova numa só passagem (importAutomatically, prepareInboundImport(..., 'SELF')): com uma pré-visualização separada antes, as duas passagens estouravam o limite de consultas e toda baixa vinda do QuickBooks (ou do Xero) era recusada. O limite conta o que o D1 conta (countedInboundDatabase): cada consulta executada e um batch() inteiro como uma só, então uma fatura com muitas visitas importa como uma de uma visita. Uma baixa encontrada e não registrada vira uma linha em System Errors (ACCOUNTING_IMPORT_REFUSED, uma por fatura por dia, com o motivo). Um pagamento do QuickBooks que paga várias faturas vira um recebimento por fatura, a parte dela (paymentShare, id <pagamento>#<fatura>); Pagamento a mais: cada fatura importa só o que o QuickBooks aplicou a ela, e a sobra fica como crédito do cliente no QuickBooks; quando ela é aplicada lá a outra fatura (uma linha nova no mesmo pagamento), essa fatura importa a sua parte, e o app nunca lança a sobra como crédito próprio (contaria duas vezes). A sobra é identificada no app (accounting_unapplied_credits, 0279, gravada a cada leitura do pagamento e apagada quando zera ou o pagamento é excluído): a tela de pagamento da próxima fatura do cliente mostra o crédito junto de Abrir no QuickBooks, e a aba de faturas do perfil do cliente lista o crédito por empresa, para o escritório aplicá-lo lá. Um pagamento com sobra já recebe id por fatura, que não muda quando a sobra é aplicada. Pagamento a menos: importa como pagamento parcial, a fatura mostra “Paga em parte” (StatusBadge partPaid; o cliente vê o que falta, “restante de £…”) e o resto continua devido nos dois lados, como o “Partially paid” do QuickBooks. Para perdoar o resto, o escritório aplica uma nota de crédito no QuickBooks (ele faz isso por um pagamento, às vezes de £0, com uma linha na nota): o app lê a nota (paymentShare credits, número e data) e importa o abatimento sem dinheiro (method: CREDIT, source: BOOKS_CREDIT_NOTE, isBooksCreditNote), que fecha a fatura quando o saldo zera e sai do faturamento por empresa no mês da nota, pelo líquido, como um reembolso; não conta como dinheiro recebido. Nota de crédito só é aceita num pagamento que paga uma fatura; outro crédito sem evidência continua em conferência. Uma leitura da contabilidade só vira linha nova quando o resultado muda (observeAccountingInbound): uma leitura idêntica à última, e os avisos que ela responde, não deixam linha (o aviso é gravado antes de responder ao webhook e descartado depois de lido); a mesma falha guarda uma linha só. O que foi lido continua imutável (o trigger só deixa apagar aviso sem leitura, 0274), e a 0274 apagou as leituras repetidas antigas, nunca uma que um recebimento importado cita. As leituras vão pelas chaves: um aviso de pagamento lê as faturas das linhas do pagamento e as de accounting_invoice_receipts, nunca o histórico inteiro nem todas as faturas; um aviso perdido do webhook é achado por uma consulta por hora, por empresa, à API de mudanças do QuickBooks (checkQuickBooksChanges, /cdc): ela lista só as faturas e pagamentos que mudaram, que seguem o caminho dos avisos; não há mais releitura em rodízio das faturas (0276 removeu o índice dela). Settings → Accounting mostra as faturas cujo dinheiro difere da última leitura do QuickBooks (quickBooksPaymentDifferences): pagas lá e não aqui (importação que não aconteceu) e pagas aqui e em aberto lá (a registrar no QuickBooks).

Estado actual — datas no QuickBooks. O Sandbox inclui faturas emitidas elegíveis de qualquer data, na fila automática e na sincronização manual. A data de corte aplica-se à primeira exportação para produção.

Estado actual — endereço no QuickBooks. O rascunho mostra o rótulo desde a primeira visualização. O apelido identifica o endereço no app. A descrição opcional do endereço na fatura é um campo separado e aparece junto ao serviço no app, no PDF, no link de pagamento e nas novas exportações para o QuickBooks. Se estiver em branco, a linha não exibe o apelido. A conferência de um vínculo existente também aceita a descrição original sem o rótulo. O link de pagamento mostra o mesmo rótulo ao lado da data do serviço, inclusive na cobrança de depósito.

Estado actual — endereço de cobrança e nome interno do cliente. No cadastro do cliente (aba Endereços) há o endereço de cobrança, marcado por padrão como “igual ao endereço principal” (clients.billing_address_json nulo, 0262). Desmarcar copia o endereço principal para editar. O campo Nome na fatura aceita o nome de uma pessoa ou empresa, inclusive com o endereço principal. Se estiver vazio, vale o nome do cliente. O nome é gravado na emissão e alterações no cadastro não mudam faturas já emitidas. Quando há um endereço de cobrança próprio, toda fatura nova (PC, DEP, CAN, controle da equipe) o grava no clientSnapshot (clientInvoiceAddresses), e o contato do Xero e o BillAddr do QuickBooks também o usam; sem ele vale o endereço principal. Ao lado do Display name há o Nome interno (clients.internal_name): apelido só da equipe. Para funcionários e gerentes, todo lugar do app que nomeia o cliente usa a primeira opção preenchida entre nome interno → display name (o primeiro, se houver vários) → nome: telas (clientStaffName), chat (channelStaffName; /api/channels manda clientInternalName só para a equipe), pushes e listas do servidor para a equipe, resumos e o calendário da equipe (clientStaffNameSql); a busca encontra pelos três. Nunca vai ao cliente: o servidor o remove de tudo que um CLIENT lê (redactClientForViewer, /auth/me, canais), e mensagens, e-mails, faturas, PDFs, páginas de pagamento e o Google Calendar do cliente usam o nome ou o display name; client_internal_name_contract.test.ts impede esses módulos de lerem o nome interno. Só ADMIN/MANAGER gravam os dois campos.

Estado actual — ambiente automático QuickBooks. Settings → Business → Accounting → QuickBooks mostra “Enviando para” para a entidade fiscal selecionada. Cada entidade conecta sua própria organização de sandbox e de produção. Entidades existentes conservam o destino anterior até a primeira troca individual. A lista manual mostra as últimas 50 faturas, sem limitar a sincronização automática. Sandbox usa D1 dedicado validado e credenciais próprias; novos documentos usam DEMO- e vínculos históricos comprovados são preservados. O envio registra a prova financeira verificada, e somente essa prova permite importar pagamentos: empresa, cliente, GBP, número, datas, linhas, VAT, total, alocação e saldo devem corresponder. Saldo zero sem Payment nunca cria caixa. Um pagamento sandbox comprovado dá baixa no app como transferência para a conta cadastrada, com marca de teste e sem comprovante automático ao cliente; esse recibo não é exportado ao sandbox nem aos livros reais. Recibos de teste pendentes de revisão/reversão, inclusive importações legadas do sandbox desde o corte, bloqueiam ativação de produção; uma prova remota de outra organização nunca é transplantada. Uma correção de conta de recebimento legada só é aceita no sandbox isolado quando seu evento imutável comprova os mesmos ID, cliente, moeda, valor, data e alocação antes/depois; não altera a prova original do app nem vale em produção. Um aviso de Payment do QuickBooks não diz a fatura: é guardado antes da resposta (quickbooksPaymentNotice:<realm>:<id>) e resolvido depois (resolveQuickBooksPaymentNotices, webhook e cron) — uma leitura do Payment dá as faturas onde ele está aplicado (LinkedTxn), e vínculos/leituras anteriores dão as que ele deixou (Delete não consulta); só essas são relidas. Oito falhas na consulta caem na releitura de todas. Cada fatura guarda no máximo uma leitura pendente, porque essa leitura já vê o estado mais recente; e uma leitura concluída registra a mesma observação nos avisos pendentes do mesmo documento criados antes dela começar (observeAccountingInbound, também Xero). Parciais são importados uma vez, um recibo por execução; alterações/exclusões após a baixa geram divergência visível no indicador e na conferência, preservando a evidência original. A busca avança inclusive por faturas fechadas e avisos ficam em fila durável.

Estado actual — entrega e troca de ambiente. Webhooks de desenvolvimento e produção têm tokens de assinatura distintos e só alimentam seu ambiente; notificações sandbox são persistidas antes da confirmação. A entrada usa uma chamada cron autenticada separada, com orçamento compartilhado entre os dois D1, reserva renovável e proteção de ambiente/revisão/conta no lote da baixa. Produção processa uma invoice por chamada isolada e encadeia no máximo 20 chamadas por rodada. A ativação exige ADMIN, a empresa selecionada em GBP, VAT/serviço e contas confirmadas. Pausa as entregas da entidade, espera as reservas relevantes, cifra o backup e limpa as cópias de teste locais daquela entidade. Preserva as conexões, os documentos remotos da Intuit e as cópias das outras entidades. A fila de produção usa a data de corte da conexão da entidade. Falhas mantêm a troca pausada e retomável. Só segura a troca o trabalho com lease ativo (token presente): o horário de nova tentativa de uma entrega falhada (lease_until sem lease_token) não conta. O backup cifrado (encryptSecret) converte para base64 em blocos, porque o espalhamento do buffer inteiro estourava a pilha acima de ~100 KB e prendia a troca na fase backup. Enquanto espera, o cartão diz o que está em andamento e em qual ambiente (waitingFor, quickBooksCutoverBlockers). Pedidos e conclusão ficam no histórico imutável.

Estado actual — transição para produção. Os dados operacionais e financeiros são reais. A limpeza autorizada remove somente metadados dos ambientes de teste Xero/QuickBooks, após backup privado e validação dos IDs; documentos, recebimentos locais, clientes, visitas e numeração são conservados. Prime e Crown iniciam a primeira exportação de produção em 01/11/2026, incluindo as faturas desse dia; Madrid fica fora. A primeira conexão aplica o corte antes de montar a fila, e reautorizar conserva o corte configurado.

Estado actual — QuickBooks e segurança contábil. A entrega de faturas usa lease renovável por documento e chave idempotente estável. Repetir confere o documento emitido sem sobrescrevê-lo; vínculos existentes também aceitam o formato legado comprovado de quantidade/preço e horas na descrição e, no Sandbox, a descrição histórica com a data por extenso e referência da visita, sem migrar o documento remoto; recuperação por número exige uma única correspondência, marca de origem, cliente, GBP, datas, linhas e totais/VAT originais. Números acima de 21 caracteres são recusados sem truncamento. Organização e ambiente permanecem vinculados aos documentos após desconexão; reautorização da mesma origem conserva os vínculos. Os dois provedores não podem coexistir na mesma entidade, inclusive em callbacks concorrentes. Histórico de configuração e confirmações de contas é imutável e registra ator; configuração fiscal é ADMIN-only.

Estado actual — contas e recuperação QuickBooks. Em Accounting → Receipt accounts, o Admin confirma a conta GBP para cada banco local ou rota Stripe/GoCardless, com motivo. Recebimentos exigem esse mapeamento ainda válido; alterações da conta local, moeda, tipo ou identidade remota invalidam a confirmação. Entrada automática aceita somente banco confirmado: fundos não depositados e outros ativos não são dinheiro bancário. Recibos confirmados são consultados novamente; ausência ou divergência exige conciliação e nunca recria dinheiro importado. O cutoff controla somente a primeira exportação: faturas já vinculadas continuam elegíveis para conferência e anulação sem recebimento remoto. O consumidor periódico retoma exportações interrompidas e eventos pendentes com espera progressiva, processa notificações Invoice/Payment e, sem backlog, consulta uma fatura vinculada por rodada para recuperar notificações perdidas. Lotes excessivos são recusados, sem truncamento silencioso. Falhas persistentes exigem revisão manual.

Estado actual — provas e entrada em produção QuickBooks. A operação é exclusivamente GBP; conectar exige moeda-base GBP. Créditos, despesas de devolução e liquidações são relidos por ID antes de confirmar; origem, cliente, data, moeda, valores e vínculos devem corresponder à instrução imutável, inclusive nas recuperações. O histórico mostra uma orientação de recuperação sem expor stack/JSON; o diagnóstico permanece interno. A coluna Accounting e seus detalhes consultam os vínculos do destino automático ativo (sandbox isolado ou produção); o tooltip identifica a empresa sandbox, e repetir usa o mesmo destino sem importar caixa de teste. Um estado recebido do servidor não é ocultado pela ausência de conexão de produção. A janela da fatura, para o escritório, mostra o mesmo ícone na linha do número e do estado, e o clique abre a conferência. A conferência, quando já há fatura remota, abre essa fatura no QuickBooks do ambiente em que foi enviada. A coluna mostra QuickBooks apenas pelo ícone, sem borda nem fundo externo: verde sincronizado, âmbar pendente, vermelho falha e cinza ainda não enviado/carregando; tooltip e nome acessível preservam provedor, estado e diagnóstico, e o clique abre a conferência. Tabela e carregamento usam o rótulo neutro Accounting até conhecer o provedor, e a conferência não presume alíquota VAT de 20%. Evidências observadas do QuickBooks também oferecem prévia e importação manual pelo fluxo compartilhado de recibos, com motivo e aprovação, sem depender de uma nova notificação. O início real aprovado é 01/11/2026 (Londres): o corte limita a primeira exportação, não converte registros de teste em transações reais. A base operacional contém tarefas reais e deve ser preservada. Remover somente as fixtures QA identificadas do agente, sem reciclar números; vínculos sandbox ficam separados da produção. Prime e Crown sincronizam desde 01/11/2026 (nenhuma fatura desse dia foi lançada manualmente); documentos anteriores já lançados manualmente não devem ser reenviados. Madrid permanece fora da integração.

Estado actual — configuração de vendas QuickBooks. O item ativo Cleaning Services deve existir com a conta de receita aprovada; conectar ou atualizar não cria item contra uma conta escolhida automaticamente. Códigos VAT são descobertos por nome específico e suas alíquotas de venda são verificadas antes da escrita. Taxas diferentes de 20% e códigos compostos exigem configuração/tratamento próprio. Faturas emitidas preservam a base fiscal e a identidade postal; recibos novos fixam a conta de destino no lançamento. A homologação contra uma empresa sandbox real e a migração controlada para produção continuam necessárias: estas proteções não autorizam retargeting de documentos históricos do sandbox para livros reais.

Estado actual — uso de créditos. A consulta de faturas elegíveis para aplicar crédito ou registrar devolução aceita o timestamp de cache enviado pelo cliente HTTP, mantendo a validação estrita dos filtros financeiros. Devolução registrada documenta dinheiro já devolvido e não aciona gateway. No QuickBooks, a contrapartida de clientes a receber deve ser única na moeda GBP do documento; contas de outras moedas não são elegíveis e ambiguidade em GBP continua bloqueada.

Estado actual — divisão de dinheiro entre participantes. A baixa manual da invoice permite escolher um recebedor ou dividir o valor recebido entre os participantes, igualmente ou com valores manuais; a soma deve fechar ao penny. O recebimento gera um recibo por participante e visita, conserva o parcial devido e reutiliza a mesma identificação nas tentativas repetidas. Em invoices agrupadas, a divisão usa os participantes comuns às visitas e o rateio por visita informado na baixa. A divisão exige manter a cobrança atual; alterações de empresa/cobrança conservam a prévia de reemissão. No Admin → Billing, uma coleta paga em dinheiro permite corrigir a divisão ou concentrá-la em um recebedor, com motivo, prévia e proteção de versão/folha. O total recebido é preservado; folhas abertas recebem apenas a diferença de dedução e folhas fechadas conservam seus valores com ajuste na próxima folha. Coletas com devoluções ou valores previstos pendentes exigem conciliação antes dessa correção.

Estado actual — links públicos. Invoices anuladas mostram Void e nenhuma instrução ou ação de pagamento na página pública. Substitutas e complementos de correção têm link abreviado próprio, inclusive documentos já emitidos; abreviações ambíguas são recusadas. Links antigos com identificador codificado continuam abrindo o documento correspondente.

Estado actual — coordenação. Recebimento manual, drafts, emissão/envio, anulação, carteira, conferência e recebimento da equipe usam fluxos em src/application; hooks e billing/api mantêm HTTP, cache e avisos. Respostas são reconciliadas com o estado vivo: não substituem fatura alterada, revisão superior, visita removida ou holerite aprovado/pago enquanto a gravação aguardava. Reversão exige propriedade ainda não confirmada por leitura/recibo autoritativo; não espelha a fatura anterior sobre outro owner. Emitir só confirma visualmente após aceite explícito, um documento pago não gera aviso de cobrança pendente e o lote conta apenas recibos aceitos. Transporte e feedback financeiro carregam sob demanda. Regras fiscais, cálculos, pagamentos parciais, reemissão, consentimento e comprovantes continuam no servidor e nos contratos públicos, sem UI nas funções de domínio.

Estado actual — fronteiras. O contrato público @billing/cancellation é dono do rateio do pagamento e da leitura dos custos de cancelamento (cancellationAmounts). Agendamento mantém a confirmação e consome esse contrato; relatórios e faturamento leem a mesma regra financeira, sem importar agendamento. O grafo de imports diretos entre os domínios, incluindo aliases, reexports e tipos, é validado contra ciclos; isso não implica serviços ou publicações separados nem independência transitiva de UI/stores.

Estado actual — atualização econômica. O indicador Xero consulta a cada 15 segundos enquanto há sincronização pendente; estados estáveis usam reconciliação de cinco minutos, foco e invalidação financeira. A entrega VAT consulta enquanto PENDING/RUNNING e encerra o intervalo nos demais estados; ações e alterações financeiras continuam invalidando os dados. Histórico e resumo administrativo da visita mantêm atualização por versão/eventos e reconciliação de cinco minutos.

Estado actual — consultas do Xero. A consulta de estados a cada 15 s pertence aos cards ou à tabela montados: envia somente as faturas exibidas, sem drafts. Abas de preparação, recebimentos, integridade e documentos não mantêm uma consulta paralela de todo o arquivo. A paginação e a busca trocam a audiência da leitura, sem mudar ações, estados ou frequência de atualização.

Estado actual — paginação. Atualizações automáticas das invoices preservam a página selecionada. Mudar busca, período, estado ou ordenação reinicia a paginação; quando a lista encolhe, a tabela mostra a última página disponível.

Estado actual — layout e PDF da invoice (2026-10-14). O emissor aparece uma vez, no topo: nome, endereço e “HMRC · VAT Reg” (não há mais bloco Legal Issuer no rodapé). Tudo o que é para pagar fica numa só barra cinza-clara no fim (fatura não paga): como pagar, os dados (conta da empresa, da funcionária ou dinheiro) com a referência e, quando há página de pagamento (link ou gateway), uma coluna com o provedor em cima (Monzo/Crezco pelo endereço do link, senão Stripe/GoCardless), o QR e, logo abaixo, um botão pequeno “Click to pay”; o titular da conta é omitido quando é o próprio emissor. O PDF (PdfExportService, onePage na fatura) cabe sempre numa folha A4, encolhendo a captura em vez de cortar o rodapé, e cada elemento com data-pdf-link (QR e botão de pagar) vira um link clicável no PDF. O QR é um SVG de tamanho fixo: sem width/height a captura o desenhava como um quadrado preto. Desde 2026-10-20 a captura é uma folha plana (flat: sem a moldura, os cantos arredondados, as sombras e o círculo decorativo data-pdf-hide do cartão da tela); o Download PDF do escritório e o Save PDF da /pay baixam o arquivo direto no navegador (no app nativo, folha de compartilhar); e o e-mail da invoice (/billing/send-invoice) anexa esse mesmo PDF, gerado na hora do envio a partir do documento na tela, com o mesmo nome do download (invoicePdfFileName: PRIME_CROWN_INV_<n>.pdf / PAYMENT_REQUEST_<n>.pdf) — antes não anexava nada, embora o composer mostrasse um invoice_<n>.pdf e o texto dissesse “attached”; sem PDF o envio é recusado no app. O e-mail vai só para o endereço digitado em “Recipient email address” na hora do envio (o cadastro do cliente não muda) e aceita uma cópia oculta opcional (“BCC”, um endereço, validado no app e no servidor; bcc em sendEmail, Cloudflare e Resend), registrada no log de entrega. Endereço que não existe (2026-10-20): o Cloudflare aceita o envio e diz na resposta quem recusou de vez (permanent_bounces: endereço inexistente ou na lista de supressão dele); o devolvido ao remetente vai para o Cloudflare, não há e-mail de retorno configurável. sendEmail lê isso (bounced): todos os destinatários recusados = falha sem tentar o Resend, log EMAIL_BOUNCED; o /billing/send-invoice responde 422 RECIPIENT_BOUNCED com o endereço, não marca a invoice como enviada, e o composer mostra o motivo ao lado do botão Send (ActionResult), aberto para corrigir. Só o BCC recusado: o e-mail sai e o aviso de sucesso diz que a cópia oculta foi recusada. Devoluções que chegam depois (aceito e recusado minutos depois) só aparecem na analytics do Cloudflare — ainda não acompanhadas. As linhas do e-mail usam total ?? amount (as gravadas só com amount saíam £0.00). O WhatsApp da invoice enviado à mão (botão WhatsApp da invoice e o de mensagem de invoice, ClientMessageButtons) leva no texto livre o valor ainda devido, o vencimento e o link /pay/<código> (invoiceWhatsAppText, src/shared/clientMessages.ts; depósito: “please pay the deposit of £x (DEP-…)” + link) — antes dizia só “ready to view and pay” sem link; o template aprovado, fora da janela de 24 h, continua com o botão “View and pay”. O corpo do e-mail segue a regra do documento (depositPaidOnInvoice): numa fatura final com depósito pago, o serviço inteiro nos itens (sem a linha negativa nem o código da tarefa embaixo dela), Subtotal e VAT do serviço inteiro, Total, “Deposit paid (DEP-…)” com VAT e “Balance due” — antes listava “Less deposit paid −£375” sem VAT e o VAT só do saldo. Valores com separador de milhar (£1,050.00). O quadro de pagamento do e-mail (conta da empresa ou da funcionária) termina com “Reference: <número da invoice>”, como a barra de pagamento do documento; em dinheiro, sem referência. O QR e o botão da invoice levam direto ao link de pagamento salvo na invoice (Monzo/Crezco); sem link (gateway Stripe/GoCardless), ao nosso link curto /pay/<código> (publicInvoicePayUrl), nunca ao longo com ?method=&amount=&ref=. Na página /pay, “Pay on Mobile (QR)” só aparece quando a invoice tem link de pagamento salvo, e o QR abre esse link direto no provedor; o rodapé não fala mais em “Bank-grade security”: só com link salvo diz quem processa o pagamento — Monzo ou Crezco, pelo endereço do link (paymentLinkProvider, src/shared/paymentLink.ts); sem link, nada.

Estado actual — Bills do cliente (2026-10-21). O saldo do topo (“Current balance due”) e o “£x to pay” do Dashboard são a mesma conta (clientAmountDue, src/features/billing/services/clientAmountDue.ts): as faturas que o cliente ainda pode pagar (não PAID/VOID/DRAFT, nem PENDING_REVIEW, que já está em conferência), cada uma pelo total menos os pagamentos confirmados (calculateBalanceDue), com VAT. Antes o saldo era stats.clientPendingPay, uma receita do período escolhido e sem VAT: £60 numa fatura de £72. O cliente paga sempre na página /pay/<código>, a mesma do e-mail (openInvoicePayPage): “Pay Latest Bill” e o pagar de cada fatura em Bills, e o Pay do Dashboard quando há uma fatura só (com várias, abre Bills). Antes esses botões mandavam a fatura para a janela da visita e o app caía; a janela de fatura do app não serve ao cliente, que não recebe os dados bancários da empresa. A /pay tem uma barra presa no topo, na largura da fatura: Save PDF à esquerda e o X à direita (sempre visível, inclusive em tela cheia/standalone; carregando e erro: o X na mesma coluna) — volta à tela que a abriu (history.back, sai de tela cheia se ativa, senão /?view=FINANCIALS). Passado o limite da página (20 aberturas por endereço em 10 min, public-invoice), o erro diz para esperar alguns minutos, não para verificar a conexão. A tela se chama Bills para o cliente (título, menu lateral e barra de baixo, nav.bills; para a equipe continua Financials), sem seletor de período, sem o cartão “open invoices” que repetia o selo da aba e sem o falso “Visits are billed automatically 24h before starting”; está traduzida (bills.*). Dentro da fatura, cada visita mostra o valor com VAT (splitVat), como o total. O Statement lista as faturas pagas pela data e forma do pagamento que as quitou (antes: data de emissão e sempre “Bank Transfer”), sem sinal de menos, e os documentos financeiros do cliente.

Estado actual — fatura como documento (2026-10-14, 2ª rodada). Endereço do cliente: o snapshot lê a tabela addresses (padrão primeiro, clientInvoiceAddresses), com clients.addresses_json só de reserva — 219 dos 282 clientes (importados) não tinham endereço no JSON e suas faturas saíam sem ele; o país GB não é impresso; faturas já emitidas mantêm o snapshot congelado. Dados bancários sempre com o beneficiário e rótulos com dois-pontos (“Bank:”, “Account name:”, “Sort code:”, “Account number:”, formatBankAccount, em todo lugar). Sem o título “Items”. A tarefa aparece na mesma linha do serviço, entre parênteses (“Deep Cleaning (T26-0042)”), como texto, sem link. A fatura de depósito usa a mesma tabela da fatura normal (o serviço com o código da tarefa, data, horas e valor; o endereço fica só sob o nome do cliente) e nos totais Subtotal/VAT/Total do serviço, “Balance due on completion” e, em destaque, “Deposit due now (x%)”; o quadro DepositBreakdown ficou só na /pay. O PDF é sempre diagramado a 672 px (layoutWidth), igual do celular ou do computador. Drafts: sem a contagem de jobs acima da tabela; o período do Billing (Drafts e Invoices) abre no mês.

Cada envio por e-mail fica registrado; o segundo é lembrete (2026-11-05). Todo e-mail aceito por /billing/send-invoice grava uma linha em invoice_email_sends (0259: tipo INVOICE ou REMINDER, destinatário, BCC, quem enviou, quando; o histórico ignora registros antigos sem destinatário, criados a partir da emissão). Abrir o compositor apenas consulta o histórico de e-mails. Se a fatura já foi enviada por e-mail, o servidor manda um lembrete: selo “Reminder”, título “Reminder: Invoice ”, assunto com “Reminder: “ (se o digitado ainda não começa assim) e a primeira linha “This is a reminder of invoice , which we first sent you on ” (dia de Londres do primeiro envio). Ao abrir o composer, o manager vê uma barra âmbar com cada envio anterior (“This invoice was sent on …” / “A reminder was sent on …”, com o endereço), lida em GET /billing/send-invoice?invoiceId=; assunto, texto e botão já vêm como lembrete (“Send reminder”). Envio recusado (endereço que não existe) não grava nada.

Rótulo do endereço na linha (2026-11-03). Quando o cliente tem mais de um endereço no cadastro, a segunda linha de cada item da fatura traz a data e o rótulo do endereço da visita, separados por “ - “ (“12 Mar 2026 - Main”); com um endereço só, apenas a data. O rótulo é lido na hora (não fica gravado no items_json), junto com o código da tarefa em addInvoiceTaskNumbers (invoiceTaskNumbers.ts): o rótulo atual da linha de addresses da visita, senão o do address_snapshot_json. Vale no app, no PDF e na /pay, que recebe só o rótulo, nunca o endereço. O e-mail de envio não mostra datas e ficou igual.

Estado actual — a fatura como porta de entrada (2026-10-14). O código da tarefa, na mesma linha do serviço entre parênteses, e uma linha discreta no rodapé (“Manage your bookings, chat with your team and pay in the Prime Crown app — open it here”) levam ao app, na invoice (PDF incluído) e na /pay. O código é um link curto e permanente /task/<ano>-<seq> (taskPath, functions/task/[code].ts): um redirecionamento para /?view=DASHBOARD&reqId=<visita> que não faz login sozinho (pode ficar num PDF por anos; o /go/, que faz login e vale 48 h, não serve aqui). Quem está autenticado abre direto; quem não está vê o login do app nessa URL e, ao entrar, a visita (reqId, App.tsx), sempre pela regra do papel — um cliente só abre as próprias visitas. Código desconhecido ou malformado, ou mais de 30 aberturas em 10 min do mesmo IP, vai à raiz do app. A /api/public/invoice não envia mais o id interno da visita. Limite: uma visita fechada fora da janela carregada no boot não abre para o cliente.

Estado actual — numeração das tarefas e das invoices por ano (2026-10-14). Tarefa: T<aa>-<seq> (T26-0042, desde 2026-10-28 sem o primeiro hífen; T-26-0042 ainda abre; o ano impresso são os dois últimos dígitos, e um link 2026-0042 ainda abre a visita), o ano em que a visita foi criada, numerada por um contador por ano (task_number_counters, migração 0214) no gatilho do banco; guardada como um inteiro, ano × 100000 + seq (202600042), e mostrada só por taskReference (src/shared/taskReference.ts, também taskCode, taskPath, taskNumberFromCode). Nunca muda (mover a visita não muda o código) nem volta (apagada, o contador não recua; task_references guarda o número das apagadas para as invoices que as citam). A migração 0214 renumerou as referências existentes na ordem antiga, dentro do ano de criação (uma apagada herda o ano da vizinha). Virada: o primeiro cadastro de um ano abre o contador dele e recomeça em 0001 — o gatilho usa o ano UTC, igual ao de Londres na virada (GMT). Invoices: <PREFIXO><aa>-<n> (PC26-0001, desde 2026-10-28 sem o primeiro hífen, quatro dígitos com zeros à esquerda para ordenar certo; depósitos e cancelamentos usam <PREFIXO><aa>-DEP<nnnn> e <PREFIXO><aa>-CAN<nnnn>, ex.: PC26-DEP0001 e CR26-CAN0001; o prefixo T é reservado às tarefas; um número já emitido como PREFIXO-26-n ou PREFIXO-2026-n permanece e entra na mesma sequência; o conciliador do extrato lê PC26-0001, PC260001, PC 26 0001 e o formato antigo como a mesma fatura), o maior número emitido no ano mais um (nextInvoiceNumber e nextTypedInvoiceNumber): em 1º de janeiro (Londres) recomeça em 0001 sem passo manual; anuladas mantêm o número, rascunhos não consomem. Seguem o ano civil, não o exercício fiscal da empresa: o HMRC exige só uma sequência única e contínua, e o ano no número já a torna única.

Estado actual — datas da invoice. Novas invoices e reemissões vencem na data de emissão, inclusive emissão automática, depósitos e cancelamentos. O PDF exibe somente Due; a data de emissão permanece armazenada para histórico e contabilidade. Documentos já emitidos conservam as datas registradas.

Estado actual — confirmação ao concluir e liquidação de múltiplas tarefas. Para visitas pagas em dinheiro ou na conta da equipe (ou transferência da empresa), funcionário e manager confirmam quanto foi recebido nesta ocasião, com opção de incluir visitas anteriores em aberto do mesmo cliente. Ao finalizar no escritório com mais de uma pessoa na equipe e pagamento em dinheiro, é possível atribuir a uma pessoa ou dividir a distribuição entre as profissionais (com botão de divisão igualitária e validação estrita da soma), registrando a parte de cada uma para desconto individual correspondente na folha. O valor recebido quita as tarefas em ordem cronológica. Tarefas com faturas em aberto recebem baixa de pagamento em suas faturas existentes (Caminho 1); tarefas sem faturas emitidas são consolidadas em uma única fatura com o valor total e linhas por visita (Caminho 2). O campo de valor recebido começa preenchido com o saldo total devido e permite editar um recebimento menor; alterações manuais são preservadas. O valor devido continua independente: recebimento parcial deixa a mesma invoice em aberto pelo saldo, e o recebimento seguinte quita essa invoice. A folha considera o dinheiro realmente recebido por pessoa; confirmação sem dinheiro zera a estimativa, sem inventar um recibo. Cada confirmação tem referência estável contra duplicação e histórico imutável; um excedente fica separado da receita faturada, visível ao escritório para revisar crédito/devolução. A confirmação usa a versão devolvida pelo servidor após concluir e emitir a invoice automática, evitando conflito com a própria finalização. A equipe aguarda a gravação da finalização e do recebimento; falha conserva o último passo e uma nova tentativa não finaliza de novo uma tarefa já concluída. Transferências para a empresa continuam no fluxo de conferência/recebimento de Billing.

Estado actual — usabilidade e acessibilidade das invoices. A consulta de inicialização tem prazo de 20 segundos para evitar recusar uma resposta válida mais lenta; continua cancelável ao sair/trocar sessão, e demais leituras mantêm seu prazo padrão. A gestão tem uma ação principal por estado: Registrar recebimento na invoice em aberto, Ver pagamento na paga; meios alternativos ficam em Outras opções de pagamento. Corrigir informações abre escolhas por intenção (valor/hora, pagamento incorreto, empresa/VAT, devolução ou histórico), mostrando somente o fluxo escolhido. A confirmação de preço fiscal separa O que muda, Documentos gerados e Efeito no dinheiro. Busca global e busca do Billing reconhecem termos de correção/baixa; comandos locais toleram acentos e usam os handlers existentes. Se o recebimento falhar, a tela preserva dados e consulta a referência exata no servidor; um recibo já concluído recupera a mesma operação, sem novo caixa. Falha de consulta orienta conferir a invoice antes de registrar outro pagamento. Botões comuns mantêm a legenda durante processamento, bloqueiam repetição, têm foco de teclado visível e área mínima de 44px no celular; as opções de pagamento mostram seleção acessível, e os painéis usam textos maiores e contraste reforçado.

Confirmação de correções fiscais. O painel de Correções da fatura oferece só o que ela permite: preço com fatura viva, pagamento com recebimento, emissor com fatura paga e não substituída, devolução com dinheiro recebido; a anulada só mostra o histórico. Desfazer a baixa só aparece quando a mesma regra do servidor permite (revertPaymentRefusal, lida em GET /billing/verify-payment): depósito, livros, gateway, complemento e recebimento extra da equipe ficam de fora, e a recusa aparece no lugar do botão. PDF, WhatsApp e email ficam na barra da fatura; o painel da paga não os repete. Nos formulários, um botão cuja ação a regra recusa não aparece (antes ficava desativado). Não há escolha de “intenção”: uma visita sozinha numa fatura local oferece a correção no mesmo registro; sem fatura viva, o preço muda só no registro; com fatura que exige documentos, a prévia lista os documentos com um aviso (“Nada foi salvo”), o botão nomeia complemento, crédito ou substituição e uma confirmação detalha tudo antes de gravar. O valor pago num holerite fechado sem snapshot só é pedido de quem tem pagamento ou gorjeta mudados pela correção (uma correção só de preço não pede nada — unchangedPay no servidor). O resultado (erro ou “Salvo”) aparece junto do botão que agiu (ActionResult), em Valores, Execução e Recebimento — nunca no topo do formulário. O recebimento manual explica que só registra dinheiro real e orienta correções pela invoice. O salvamento rápido local só aplica uma prévia que confirme correção no mesmo registro. Antes de aplicar uma correção de preço que gera complemento, crédito ou substituição, uma janela informa os valores, os documentos novos, o destino da invoice original e os efeitos sobre recebimentos, dívida, crédito disponível e devolução registrada. Cancelar não grava a correção; complementar não dá baixa automática. Correções simples de registros locais conservam o salvamento direto.

Estado actual — Billing simplificado. Duas áreas principais: Draft (Rascunhos) reúne automaticamente as tarefas prontas para faturamento e as tarefas de rascunhos locais existentes, agrupadas por cliente e empresa; não existe uma etapa anterior de Serviços para faturar nem uma troca Pool/Drafts. Fechar uma tarefa não paga marca DONE e preserva seu estado financeiro: sem documento salvo e com emissão automática desativada, continua NONE e aparece diretamente na lista Draft; DRAFT no cadastro significa que existe um documento em rascunho. O agrupamento da lista é visual: fechar outra tarefa do mesmo cliente não altera um rascunho existente nem decide se a emissão será individual ou agrupada. Recebimentos já registrados e cobranças de cancelamento continuam seguindo seus fluxos próprios. Cada tarefa pode ser selecionada individualmente, ou pelo grupo, para emitir uma fatura por tarefa ou uma fatura agrupada por cliente e empresa. Revisar rascunho abre o documento salvo; uma tarefa nova só ganha um documento persistido quando revisada ou emitida, sem número fiscal antes da emissão. Valores exibidos dos rascunhos respeitam seus totais salvos. A preparação da seleção reorganiza apenas documentos locais não emitidos, numa transação auditada: tarefas não selecionadas permanecem no rascunho original. Divergências de VAT, banco, método/recebedor, notas ou prazo exigem revisão antes de agrupar; recibos, vínculos contábeis, depósitos e correções conservam seu fluxo próprio. Uma resposta perdida ou emissão parcial retoma pelos mesmos documentos, sem duplicar faturas. A recuperação compara o prefixo literal da operação, sem depender do limite de padrões LIKE do D1. A barra de ferramentas do Billing Hub integra o filtro de entidade fiscal posicionado antes do período na mesma linha (permitindo filtrar rascunhos e faturas por empresa específica ou todas) e o filtro de período padrão (<PeriodFilter>), idêntico ao do Service History, abrindo por padrão no Mês atual, com seleção rápida (Semana, Mês, Ano, Personalizado) e intervalo de datas em horário de Londres. Em Drafts, quando há tarefas operacionais concluídas pendentes de períodos anteriores à data inicial selecionada, um banner de aviso em destaque indica a quantidade e o montante pendente com botão rápido para incluir tarefas anteriores, expandindo a data inicial para que nenhuma pendência histórica fique esquecida. Todas as visualizações contam com paginação padronizada (<Pager>): cartões (12 por página), tabela de faturas (15 por página) e listas de preparação/pools (10 grupos por página). A emissão de rascunhos reutiliza rascunhos existentes sem duplicidade e restringe o bloqueio de tarefas apenas a faturas já emitidas ativas. Invoices (Faturas) reúne aguardando pagamento, pagas e anuladas, com as pílulas padrão de estado dentro da barra de pesquisa e cartões/tabela. Os cartões de fatura seguem apresentação padronizada uniforme em fundo branco com borda suave independente do estado (rounded-2xl border border-slate-200/80), com identificação por StatusBadge e botão primário padronizado. A tabela de faturas tem checkbox por linha e no cabeçalho (seleciona todas as faturas da lista, em todas as páginas), com a mesma barra flutuante de ações em lote dos cartões; a coluna de ações mostra o olho (prévia) e o menu de opções da fatura. A coluna Xero apresenta indicador de sincronização por cor e modal detalhado de conciliação; onde a integração com o Xero não se aplica (entidade fiscal sem sincronização ativa ou fatura fora do escopo contábil), exibe -. A tabela Draft mostra cabeçalhos de cliente/empresa com quantidade, total e seleção do grupo quando há mais de uma tarefa. Links antigos Pool/Drafts abrem a única lista Draft; Awaiting/Paid/Void abrem Invoices no estado correspondente. Depósitos e rascunhos especiais continuam disponíveis para revisão na mesma área. Documentos fiscais, conferência de caixa e integridade ficam em Mais; as proteções financeiras existentes permanecem.

Estado actual — emissão automática por cliente. No cadastro do cliente → Financeiro, Emitir invoices automaticamente emite uma invoice numerada por serviço ao concluir a tarefa, com a empresa fiscal, VAT, método e recebedor da tarefa. A invoice fica aguardando pagamento e a tarefa AWAITING; A dedução no payroll segue a regra própria das tarefas concluídas com pagamento à equipe (cash ou conta do funcionário), incluindo valores previstos; não depende da baixa da invoice. O registro de recebimento com valor, recebedor e data reais confirma a quitação financeira. Ao confirmar o pagamento (baixa manual, gateway ou conciliação bancária), o comprovante de pagamento é inserido de forma automática no chat direto do cliente como nota interna HELD (receipt), aguardando liberação posterior pelo manager. Colocar invoices no chat é uma opção separada, sujeita à automação INVOICE: cria uma única nota interna HELD no chat do cliente, mesmo quando a entrega geral está em APP ou inclui email. Não envia ao cliente; o manager pode optar pelo release no fluxo existente. Com a opção desligada, a invoice é emitida sem nota automática. A configuração não emite tarefas antigas em massa, não altera drafts já salvos e não duplica documentos existentes. Clientes com emissão manual conservam as tarefas na lista Draft, onde a seleção permite agrupá-las por semana ou mês. Ao emitir a invoice manual, uma nota interna HELD é criada no chat da última tarefa concluída incluída no documento (data de conclusão, com desempate pelo ID), com release opcional pelo manager e respeitando a automação INVOICE. Pagamentos confirmados e cobranças em conta do funcionário preservam seus fluxos de emissão próprios.

Estado actual — conciliação de extrato bancário. A conciliação está em Banking → Conciliação: o botão do Billing abre a mesma fila de entradas, saídas, invoices e provas do Xero. A baixa de invoices e seu vínculo ao extrato compartilham uma gravação protegida. Não existe outro conciliador bancário no Billing; o endpoint antigo responde 410 para clientes atualizarem o app.

Estado actual — faturamento fiscal no app. Billing → Documentos fiscais reúne créditos, complementos e substituições de todas as empresas, com filtros por empresa/tipo e paginação; apenas ADMIN/MANAGER acessa essa consulta global. Cada documento conserva sua origem, identidade histórica, saldo disponível, aplicações/devoluções e estado da entrega contábil; Abrir fatura consulta o documento histórico mesmo fora da janela operacional e abre os controles existentes de correção. Crédito reduz dívida; aplicação não é dinheiro recebido, e devolução registra dinheiro já devolvido. Correções de preço, VAT ou emissor continuam passando por motivo, prévia e provas específicas. As novas emissões comuns, depósitos, cancelamentos e comprovantes de coleta congelam o endereço postal padrão (ou primeiro) do cliente, sem notas de acesso nem país — lido da tabela addresses, onde o app guarda os endereços, e só sem linha nela do antigo addresses_json (clientAddressesSql; antes só o JSON era lido, vazio na maioria dos clientes, e as faturas saíam sem endereço); o documento mostra o endereço logo abaixo do nome em “Bill to”; emitir um rascunho captura a identidade postal atual. A empresa tem endereço fiscal na configuração, capturado nas novas emissões. Faturas e PDFs mostram cliente, endereço registrado, emissão e vencimento; os documentos emitidos não recebem endereço retroativo. Contabilidade geral, despesas de fornecedores e declarações de VAT/HMRC permanecem no Xero.

Estado actual — regra de VAT na correção de valores recebidos. O total recebido comprovado é preservado: corrigir VAT ou emissor não adiciona imposto por cima do dinheiro que entrou. A parcela líquida é ajustada para que líquido + VAT sejam exatamente o mesmo bruto, com motivo e documentos vinculados; caixa, recibos e originais permanecem intactos. Exemplo: £100 recebidos, VAT de 20% → £83,33 líquidos + £16,67 VAT. Ajuste de preço não representa desconto com devolução ou nova cobrança por si só. A substituição de emissor usa esse cálculo comum; valores que não permitem reproduzir o bruto ao penny exigem revisão, sem inventar diferença. A mesma empresa pode corrigir a base de VAT de uma fatura local integralmente recebida: gera crédito integral e substituta quitada por alocação, conserva os recibos originais e a conta planejada, e propaga lucro/partilha por ajustes auditados. A UI oferece a empresa atual como correção de VAT, com motivo, referência, consentimento e prévia. Recibos já conciliados, bases divergentes e correção sem mudança de VAT são recusados; entregas contábeis seguem o fluxo dedicado abaixo. A prévia de VAT no mesmo emissor conectado consulta o original no Xero e seus pagamentos individuais: comprova cliente, documento, datas, moeda, valores e banco cadastrado, e mostra conciliação conhecida/desconhecida. A prévia permite aprovação explícita para taxas de 0% e 20%, com validade de dez minutos e nova conferência antes de salvar. A aprovação registra uma instrução imutável e uma entrega dedicada: crédito integral, substituta com bruto preservado, reversão dos pagamentos individuais não conciliados, alocação ao original e reatribuição dos mesmos recibos. Cada ação “Continuar” executa no máximo uma gravação no Xero; a ação seguinte relê as provas completas. Datas fiscais e datas dos recibos originais são conservadas. Respostas perdidas retomam pela identidade e referência aprovadas, sem duplicar documentos ou recibos. CONFIRMED exige nova prova completa de documentos, alocação e pagamentos; mudanças de organização, banco, valores, datas ou conciliação recusam a execução. Durante entrega pendente, ficam protegidos os vínculos contábeis, bancos e movimentos financeiros envolvidos. Nenhuma etapa transfere dinheiro ou devolve valores ao cliente; efeito final de caixa e dívida é zero. Recibos conciliados, desconhecidos ou em lote e taxas não suportadas continuam bloqueados. Homologado na Demo Company (UK) com recebimento GBP, correção de VAT de 20% para 0%, crédito e substituta quitados, recuperação de resposta perdida, anulação de fatura de teste e efeito final zero de caixa/dívida.

Estado actual — prova de sincronização Xero. Recuperar uma fatura pelo número exige correspondência de cliente, tipo, moeda GBP, datas e líquido/VAT/bruto; nova consulta ao documento precede qualquer recebimento. A exportação usa a conta bancária escolhida na fatura, incluindo contas secundárias e o snapshot emitido, com sort code e número completos; não escolhe outro banco como fallback. Recibos novos, recuperados e já confirmados são conferidos por identidade, fatura, banco, valor, data disponível e referência. Créditos, alocações e devoluções só confirmam após consulta nova às provas remotas correspondentes.

Estado actual — indicadores e clientes Xero. Awaiting, Paid e Void mostram por fatura o status no Xero através de um símbolo/badge compacto com código de cores (verde para sincronizado, âmbar para pendente, vermelho para erro e ardósia para não conectado/ignorado). Ao clicar no símbolo do Xero (na tabela ou nos cartões), abre-se a janela de detalhes de sincronização (XeroSyncDetailsModal) com o status em ambas as vias: Prime Crown → Xero (organização, ID remoto da fatura, ID do pagamento, data de sync, mensagem de erro e ação para sincronizar novamente) e Xero → Prime Crown (eventos de webhook recebidos, observações, estado da conferência, conciliações e divergências). O indicador só confirma a versão local comprovada: recibos, datas, valores, estado ou organização alterados tornam a fatura pendente até nova conferência. Documentos de correção de VAT usam sua entrega dedicada; documentos fora do fluxo ordinário não ganham confirmação genérica. Registros antigos sem fingerprint exigem nova conferência. Nosso sistema é a fonte dos nomes, e-mails, celulares/telefones e endereço postal dos clientes: clientes já vinculados atualizam ao salvar, e a configuração da empresa oferece envio inicial dos clientes ativos em lotes de cinco. A confirmação relê o contato, conserva sua identidade e recusa contatos arquivados ou correspondência ambígua. O endereço padrão (ou o primeiro cadastrado) é enviado como POBOX, utilizado nas invoices do Xero: linhas 1/2, cidade, postcode e país; remoção local limpa o endereço postal. Outros tipos de endereço no Xero são preservados. Notas de acesso, coordenadas e notas operacionais não são enviadas; alterações feitas no Xero não são importadas. Falhas ficam registradas e podem ser retomadas. A homologação financeira na demo exige um banco GBP com número britânico completo de 14 dígitos; bancos de exemplo incompatíveis não autorizam pagamentos.

Estado actual — baixa simples e prioridade Xero. A baixa manual comum usa uma única tela, com saldo, data de Londres, método e conta da invoice preenchidos; a nota é opcional e o parcial exige apenas mudar o valor. Mudar empresa ou cobrança mantém a prévia de reemissão. Nas invoices efetivamente destinadas à contabilidade conectada, a tela recomenda conciliar no Xero e oferece acesso à invoice externa; registrar no app exige confirmar o recebimento, o envio contábil e a proteção dos valores. A aprovação de uma transferência declarada pelo cliente exige a mesma confirmação, uma vez por lote. O servidor revalida e protege a organização na gravação; recibos da equipe fora do escopo contábil não recebem promessa de exportação. Após aceite, pagamento registrado, sincronização pendente/falha e sincronizado são fatos separados: sincronização nunca significa conciliação bancária confirmada. A invoice oferece retomada de sincronização sobre os mesmos documentos e recibos, sem outra baixa. Corrigir baixa marcada por engano é distinto de devolver dinheiro; vínculos contábeis continuam exigindo seu fluxo de correção próprio. Baixa em lote (BulkReceiptModal): selecionadas faturas SENT/OVERDUE (tabela ou cartões), Dar baixa registra o saldo inteiro de cada uma na forma e na conta que a fatura já tem, hoje, sem campo para mudar forma, conta, recebedor, dia, referência ou nota, pela mesma gravação da baixa manual (processManualSettlement, um settlementId por fatura, então repetir não duplica recibo). Faturas com contabilidade conectada pedem uma única confirmação contábil para o lote. Dinheiro e conta de cleaner usam o recebedor que a fatura já nomeia; se o servidor ainda exigir o rateio por visita, essa fatura fica sem baixa para registrar uma a uma. Parcial e mudança de cobrança continuam uma fatura por vez; PENDING_REVIEW segue Aprovar. O resultado aparece junto do botão (ActionResult); as recusadas ficam listadas e selecionadas para tentar de novo.

Estado actual — correção simples de registros locais. Uma invoice de uma única tarefa, sem vínculo Xero/QuickBooks, depósito, conciliação, checkout ou documentos de correção, pode ser corrigida no mesmo número, inclusive após baixa manual no fechamento da tarefa. O editor oferece essa opção por padrão e permite salvar tarifa, horas, total e o valor realmente recebido, sem criar complemento ou crédito. Alterar o preço não inventa pagamento: o recebimento só muda quando informado explicitamente, mantendo identidade, data, método e recebedor. A auditoria conserva os valores anteriores e posteriores; diferenças de coleta pela equipe atualizam a folha aberta ou geram ajuste na próxima folha quando a original já estiver fechada. A interface simples salva diretamente, com validação e proteção contra mudanças concorrentes. Devoluções reais, múltiplos recebimentos e registros vinculados continuam no fluxo próprio.

Estado actual — confirmação e devolução no Admin. A correção de tarifa do cliente distingue £/hora, quantidade de horas e preço total, conservando os extras. Tarifa e horas devem reproduzir o total ao penny. Corrigir esses campos sem mudar o total de uma invoice paga preserva os recibos e não cria outro documento; nos fluxos contábeis ou com documentos de correção, uma mudança real do total conserva a invoice paga e mostra o complemento/crédito na prévia. A área Valores usa o editor protegido para reduzir o preço, escolher crédito ou registrar devolução comprovada; é o único caminho de devolução: o antigo painel de estorno (RefundPanel, issueRefund, RefundLogic) foi removido, pois nada mais o montava e a gravação comum o recusaria. A gravação comum da visita encerrada recusa alterar quantidades/status de devolução e histórico de caixa sem o comando vinculado. Ao aprovar ou confirmar um pagamento, o status da fatura é atualizado imediatamente (otimista) para PAID tanto no modal quanto nas listas e cartões de aprovação, prevenindo que o usuário clique duas vezes durante o processamento da rede; havendo recusa ou falha na resposta, o estado anterior é revertido com aviso de erro. Confirmação/reversão de pagamentos só fecha o diálogo após aceite. Respostas após logout ou fechamento não atualizam dados nem anunciam conclusão; a reconciliação em lote interrompe próximas gravações quando a sessão muda, preservando os itens já aceitos.

Estado actual — reversão contábil de compensações. O Admin permite entregar várias compensações comprovadas entre o mesmo par de empresas, cada uma com aprovação e dois lançamentos próprios, e revisar/aprovar dois lançamentos inversos de cada compensação CONFIRMED, preservando os originais. A leitura revalida bases, organizações, contas e os mesmos IDs/datas/referências confirmados; exige data válida em Londres, posterior ou igual à compensação. Referências próprias já existentes bloqueiam uma nova aprovação, sem provar ausência de reversões manuais sem vínculo; a gestão confirma isso no consentimento. Reverter uma compensação relê o saldo atual sem alterar os documentos/recibos/contas congelados; alterações de outras compensações não autorizam mudar valores ou IDs históricos. Ações contábeis pendentes em qualquer compensação que compartilhe os recibos bloqueiam reversões. A instrução durável entrega uma contraparte por chamada, protege ambas as empresas/recibos e retoma falhas pelas mesmas referências e IDs conhecidos. Somente nova leitura dos dois lançamentos inversos POSTED, sem imposto/caixa, confirma a entrega e restaura atomicamente as duas obrigações locais. Se a restauração for recusada, a confirmação também é desfeita; os lançamentos remotos ficam disponíveis para retomada. Histórico e PDF conservam prova original, reversão e tentativas; prova histórica não é consulta atual. A reversão operacional comum continua bloqueada para entregas contábeis aprovadas.

Estado actual — entrada contábil comum. Integrações recebem dados pelo mesmo contrato versionado de organização, fornecedor, documento, cliente, datas, moeda, valores e pagamentos identificados. Eventos e observações ficam em histórico durável; diferenças de documento/VAT, cliente, situação ou recebimentos exigem conciliação. Pagamento bancário, crédito e quitação patrimonial são fatos distintos: nenhuma notificação cria dinheiro, altera fatura/visita ou reabre folha automaticamente. O Xero persiste notificações assinadas de faturas já vinculadas antes de responder e consulta até duas por chamada; as demais e falhas ficam disponíveis em Correções financeiras → Accounting para conferência manual. Observações correspondentes são prova histórica, não entrega confirmada nem consulta atual. Retomar uma leitura não substitui prova já registrada; eventos posteriores criam outra observação. O cadastro de recibos contábeis e a entrada aceitam identificadores de futuros provedores, preservando as mesmas regras e provas; os adaptadores Xero e QuickBooks estão habilitados para entrada, com as restrições próprias de cada provedor. A ação Revisar correção consulta novamente o documento e os pagamentos atuais, sem substituir a prova histórica. A prévia comum separa recibos já vinculados, ainda não registrados localmente e conflitantes; mostra valor adicional, data e referência. Divergências de identidade, cliente, VAT/moeda, comprovantes incompletos, recibos locais sem vínculo e documentos com correções existentes bloqueiam a proposta. Prova remota alterada exige outra observação; não se reaproveita o histórico como autorização. A prévia não importa dinheiro nem confirma entrega. A confirmação dos cenários bancários comuns segue o fluxo de importação aprovada abaixo; entidades sem vínculo e outros tipos de documento continuam pendentes. A entrada QuickBooks segue as restrições de conta e prova descritas no Estado actual.

Estado actual — importação aprovada. ADMIN/MANAGER confirma recibos bancários já recebidos com motivo e prévia válida por dez minutos. Documento, pagamentos atuais, conta efetiva da mesma empresa, visitas e vínculos contábeis são revalidados antes da gravação; alteração exige outra revisão. A conta precisa corresponder integralmente a sort code e número de uma única conta cadastrada, sem fallback pela conta principal. Faturas comuns emitidas ou vencidas, com até duas visitas concluídas e até três novos recibos, aceitam recebimento integral ou parcial. Cada recibo conserva ID externo, valor, data e referência; baixa, auditoria e vínculo contábil CONFIRMED entram no mesmo batch protegido. Falha desfaz o conjunto, e confirmação repetida recupera o resultado aceito sem repetir dinheiro ou exportação. O parcial conserva o saldo devido e não marca visitas pagas; o integral quita as visitas. Dados aceitos atualizam store e cache, e o histórico distingue o valor importado da observação original. Depósitos, coleta de equipe, crédito/clearing, correções vinculadas, contas ambíguas e grupos fora desses limites precisam de conciliação própria; folhas e impostos históricos permanecem intactos. Recebimentos importados bloqueiam a anulação comum e a remoção dos pagamentos no Xero; a correção exige seu fluxo financeiro dedicado.

Estado actual — instruções de recebimento. Trocar a conta pedida na fatura propaga a conta planejada às visitas vinculadas, inclusive depósito, com versões e gravação conjunta; a empresa/cliente de cada visita precisa corresponder ao documento. Contas de faturas pagas/anuladas ou com recebimento parcial/malformado exigem conciliação. Alterar somente a conta bancária de cobrança não reabre nem recalcula folha; mudar método ou recebedor continua verificando as deduções já existentes. A janela usa o snapshot aceito pelo servidor e serializa alterações de conta, método/recebedor e link, ignorando respostas de outro documento/sessão. Escolhas recusadas não são anunciadas como salvas.

Estado actual — execução sem divergência no recarregamento. Corrigir horários, resolver incidentes ou reabrir uma visita grava a tarefa e seus eventos/incidentes normalizados no mesmo batch com versão e ator próprios. Reabrir elimina o check-out normalizado e, ao voltar para agendada, também o check-in; os registros originais permanecem na auditoria. Horários não alteram horas faturadas ou folha. Incidentes legados são normalizados integralmente, sem perder os não alterados; IDs de outra visita não podem ser apropriados. As gravações de campo e planejamento também aguardam os eventos/incidentes normalizados; não deixam uma atualização atrasada restaurar valores antigos. Duplicidade de evento exige conciliação; falha desfaz o conjunto.

Estado actual — planejamento com rascunho. Visitas abertas permitem ajustar preço, horas, serviço e data quando a fatura vinculada ainda é um rascunho local sem recibos. O servidor confirma identidade, linhas, totais, VAT e ausência de vínculo contábil, revalida os documentos na gravação e atualiza visita, equipe normalizada e linhas da fatura no mesmo batch. Faturas agrupadas conservam as outras visitas, taxas e depósitos. A gravação comum de faturas também inclui linhas e recibos normalizados no batch do documento; documentos emitidos preservam identidade, datas, linhas, valores e taxas, exigindo correção vinculada para alterá-los; equivalência de ordem das chaves ou formato do mesmo instante não reescreve o JSON original; recebimentos existentes não podem ser apagados/reescritos por este caminho e um estorno é um novo registro distinto; identidades duplicadas e concorrência desfazem a tentativa antes da resposta. Quantidades ambíguas, extras com IDs repetidos e VAT/bruto incompatíveis com a base comprovada são recusados; a edição local conserva a data de sincronização contábil. Divergências prévias, múltiplos rascunhos, documentos emitidos ou vínculo remoto exigem conciliação; não são sobrescritos. O planejamento e a equipe atual, incluindo custo e duração, são enviados na mesma alteração de visita; a etapa posterior apenas promove o lead, avisa a equipe e trata as visitas futuras. Fechar/trocar a visita ou sair da sessão impede ações posteriores de uma resposta atrasada. A resposta aceita atualiza a fatura visível sem substituir outra alteração local mais recente ou dados de uma sessão encerrada. Alterações nas visitas futuras são aguardadas antes do anúncio de sucesso; uma recusa mantém o editor aberto e informa que a visita atual já foi salva. Depois de uma gravação que o Worker propaga para faturas (correção de horas/preço da visita realizada, depósito, crédito, pagamento), resync(API.INVOICES) recarrega a lista de faturas do store (refreshInvoiceStore, queryCacheSync.ts) — antes não fazia nada e o rascunho reaberto na visita mostrava os valores antigos até abrir o Billing (13/10); linhas alteradas localmente durante a busca ficam.

Estado actual — acesso às correções e documentos (2026-10-08). A aba Admin abre em Correções: primeiro a barra executiva do estado do registro (AdminRecordState) — situação da visita, situação do pagamento e chips indicadores de fatura vinculada e holerites (com atalho para alternar à aba correspondente), mantendo o topo compacto e sem poluição visual. O que cada mudança pode tocar é dito onde ela é feita, não numa lista no topo: o bloqueio de reabrir (reopenBlockers no GET /visits/:id/admin: fatura ativa, folha, depósito, pagamento, sem equipe) fica na linha da situação, e a regra de valores (faturada / encerrada, holerite fechado ou rascunho) no topo de Equipe e preço. Depois quatro áreas: Execução (VisitExecutionCorrection) lista cada registro — situação, entrada, saída, nota de encerramento, checklist, incidentes, nota para a equipe, avaliação e comentário — ao lado do valor atual, com Corrigir na própria linha, botão no topo para Editar todos os campos de execução (ou cancelar todas), atalhos rápidos de timestamp (Início agendado, Fim agendado, Agora) para entrada e saída, aviso visual de rascunho em edição, campo de motivo opcional (assumindo justificativa administrativa padrão quando omitido) e envio de várias correções juntas sob uma prévia em tabela (antes/depois) e uma versão (patches no POST, um só UPDATE); reabrir uma visita concluída vai sozinho, pela guarda própria. Equipe e preço: visita aberta mostra o atalho para o Editar tarefa (o mesmo do lápis do cabeçalho, sem segundo editor); visita encerrada usa a correção financeira (VisitCostCorrection), que permite escolher Todas as seções (visão unificada) ou focar em seções individuais — Preço do cliente, Equipe e pagamento ou Outros custos (“Corrigir outra parte” ou pílulas de alternância rápida trocam de foco sem perder os valores já digitados); motivo opcional sem bloqueio de gravação; aviso visual de rascunho em edição; e um cartão de Resumo de cálculo em tempo real calculando preço do cliente, custo da equipe, custos extras, lucro e margem instantaneamente à medida que os campos são alterados, alertando também quando houver valor excedente recolhido que ficará de crédito para o cliente; enquanto ela está aberta, o cartão de valores da visita não aparece (repetiria os mesmos números). Grupos: equipe e pagamento, preço do cliente, outros custos, folha anterior quando exigida; com a equipe em linhas (adicionar/remover) e o pagamento de cada pessoa já preenchido com o que o holerite pagou (recordedStaffPay no GET /visits/:id/financial, a mesma leitura do snapshot usada nos deltas, então valor não tocado não gera diferença), senão o custo registrado da visita, senão a regra da folha (calculateEmployeeEarnings): cada linha mostra o valor/h da pessoa, as horas com −/+ (como no Editar tarefa) e o pagamento: mexer nas horas recalcula o pagamento (horas × valor/h), digitar um pagamento o define à mão até as horas mudarem de novo; quem entra na equipe começa com a parte igual das horas combinadas e quem fica mantém as suas; Dividir igualmente reparte de novo e recalcula todos; novas horas faturadas são um novo combinado (como no Editar tarefa): a equipe é redividida sobre elas, o preço acompanha o valor/h e o servidor grava também estimated_effort e agreedHours, para cartões e faturas refeitas mostrarem as horas corrigidas (antes só financials.billedHours mudava); a prévia é uma tabela com documentos emitidos e diferenças de folha. Com dinheiro recebido pela equipe (baixa registrada ou pagamento em dinheiro/conta da funcionária), a prévia em tabela é obrigatória (sem salvamento direto) e destaca o dinheiro recebido por quem recolheu antes e depois; divergência entre o novo preço e o valor em mãos alerta no formulário com atalho para igualar. Na aba Evidence / Relatório (ManagerPresenceBlock e TelemetryMap), o mapa de telemetria renderiza também o ponto do endereço do cliente com marcador residencial e traçado até o check-in da equipe para conferência visual de proximidade. Recebimento (AdminBillingControls) reúne forma de pagamento, a lista de faturas vinculadas com botões para visualizar o documento e abrir as Correções financeiras da fatura (InvoiceCorrectionsPanel), transações e quem recebeu, com métodos e situações pelo nome (nunca o código). Histórico fica somente para consulta. No painel de Correções financeiras da fatura, a correção do destino do recebimento só aparece quando a fatura tem recebimento ou correção anterior; métodos, situações de holerite e entregas contábeis aparecem pelo nome. A checagem de ordem entrada/saída só vale quando a alteração mexe num horário, para que horários antigos fora de ordem não travem outras correções. A leitura da aba usa a chave só da visita: uma versão nova é relida no lugar e os formulários abertos em outras áreas conservam os valores (antes, a versão na chave desmontava todos). Os formulários impedem envios simultâneos e ignoram respostas após logout, troca de visita ou desmontagem. Cancelamentos em revisão abrem a revisão existente com a visita consultada. A correção de equipe e o registro de devolução oferecem o cadastro de funcionários, incluindo quem não está na equipe atual. PDFs de documentos financeiros usam o compartilhamento/download da plataforma, com tentativa única e erro visível. Correção de preço ou horas numa visita sem VAT já confirmado não pergunta mais o VAT: a base (taxBasis) sai da empresa da visita (registrada ou não, taxa) e do VAT absorvido do cliente, a regra do splitVat, mostrada numa linha (“VAT original: Sem VAT · Crown”); o servidor ainda confere com faturas e depósitos. Na visita encerrada, Equipe e preço também adiciona ou tira itens cobrados do cliente (extras, sem VAT, dentro do preço: o preço anda junto e a correção de preço fica ligada, então fatura emitida recebe complemento/crédito pelo plano de documentos) e extras pagos à equipe (staffExtras, só para quem está na equipe corrigida: entram no custo e, com holerite já fechado, a diferença vai para o próximo); o POST /visits/:id/financial recebe as listas inteiras em changes.extras/changes.staffExtras. Numa visita de plano recorrente, adicionar um item cobrado do cliente pergunta Só esta visita / Esta e as próximas visitas (igual no Editar tarefa): a segunda marca o item repeat, que, depois da correção aceita, entra pelo mesmo id nas próximas visitas abertas e não faturadas da série com o preço e o VAT de cada uma (futureExtraPatches), e as visitas que a série ainda criar o copiam (copiedVisitRecord mantém só itens repeat). Remover um item que repete faz a mesma pergunta.

Estado actual — emissor de fatura paga. Correções financeiras permite substituir uma fatura integralmente paga por recebimentos manuais, após conciliar cada destino. A gestão confirma o fornecedor correto, a aplicação do pagamento com acordo do cliente, endereços e VAT na data do serviço. O original conserva número, valores e recibos: um crédito vinculado é consumido exclusivamente pela substituição, já quitada, sem novo dinheiro ou crédito livre entre empresas. O total do cliente fica igual; lucro, beneficiários e reserva usam bases históricas, com diferenças em DRAFT ou ajustes futuros em folha fechada. Relatórios atribuem o valor fiscal à substituição e preservam uma única entrada de dinheiro. Obrigações por fundos retidos continuam pendentes e compensáveis; destinos ficam congelados. Uma fatura conectada/exportada ao Xero com até duas visitas pode ser corrigida após comprovar a organização, cliente, documento e um a três recebimentos bancários manuais integralmente retidos pelo fornecedor original; as contas de conciliação das duas empresas precisam estar verificadas. Essa aceitação local congela a prova e continua pendente da entrega contábil específica, sem escrever no Xero. Trocar organização, conta ou os recibos comprovados impede a entrega; reconfirmar a mesma conta ou reautorizar a mesma organização mantém a prova histórica. Faturas conectadas com mais de duas visitas, VAT divergente, outros destinos, gateway, depósitos, pagamentos parciais e documentos de preço vinculados continuam recusados. QuickBooks permanece em espera. A leitura de folha e rateio é compartilhada entre visitas, preservando o escopo de cada uma. Antes de gravar, o servidor reserva consultas para a resposta e renovação do acesso ao Xero; correções históricas que ultrapassariam o limite do D1 são recusadas sem gravação e precisam de processamento em etapas.

Estado actual — composição de recebimentos. O cálculo comum, independente do provedor, separa dinheiro já no fornecedor correto, fundos retidos pelo original e fundos retidos por terceiros/equipe. Pacotes locais sem histórico de compensações, com até três recibos integrais, combinam correção de registro bancário com fundos retidos no Xero. Original, substituta e respectivos clientes devem existir; somente o crédito ausente pode ser criado com consentimento. A prévia confere separadamente banco correto, banco original e detentores manuais; congela os IDs errados, que precisam estar explicitamente não conciliados. Cada chamada cria o crédito, reverte um registro errado, quita a parcela do crédito retida pelo original, aloca o restante ou quita somente fundos retidos na substituta. Recibos reais no fornecedor correto e no original ficam preservados; detentores externos continuam comprovados apenas pelo histórico manual. A confirmação exige nova leitura completa dos saldos, recibos, reversões, alocação e quitações patrimoniais; respostas perdidas retomam a mesma instrução sem repetir caixa. A recuperação assistida recusa acertos parciais e conserva a prova das reversões e das duas parcelas. Tela, consentimento e PDF separam dinheiro preservado, registros revertidos e fundos ainda devidos. A qualificação inicial de troca de emissor já conectado mantém seus limites próprios descritos abaixo; este fluxo não os amplia.

Estado actual — detentor externo no Xero. Pacotes de substituição local com um a três recebimentos integralmente retidos por funcionário (dinheiro/conta pessoal) ou terceira empresa podem entregar o acerto após revisão dos dois clientes e organizações. Compensações anteriores integralmente revertidas e comprovadas preservam o histórico, restauram o saldo integral e permitem a entrega; prévia, resultado e PDF mostram a reversão sem alegar quitação líquida nos livros. A original precisa existir nos livros sem pagamento bancário/patrimonial: o crédito é aplicado à original, e a substituta é quitada exclusivamente pela conta de ativo circulante habilitada, registrando o valor devido pelo detentor real. Identidade, valor, data e conciliação de cada detentor ficam congelados; são provas de recebimento manual, não consulta ao banco ou aos livros de quem reteve o dinheiro. O saldo retido permanece pendente, sem transferências, estorno ao cliente ou alteração de faturas, visitas e folha locais. Créditos ausentes podem ser criados somente com autorização explícita; original e substituta precisam existir. A execução faz uma ação por chamada, retoma a mesma instrução em falha e confirma somente após nova leitura integral; entradas já concluídas também podem resolver FAILED pela revisão assistida. Prévia, consentimento, resultado e PDF distinguem a alocação do crédito do recebível patrimonial. Pagamentos existentes na original, contas bancárias no destino, compensações ativas ou sem prova de reversão, mistura com retenção no fornecedor original e provas divergentes exigem conciliação dedicada. Pacotes antigos de detentor externo precisam ser preparados novamente para congelar as tarefas de revisão corretas. A homologação em organizações Xero reais continua pendente.

Estado actual — preparação contábil do acerto. A configuração da entidade permite escolher uma conta patrimonial de conciliação em GBP fora do banco, validada na organização atual: Xero exige conta corrente patrimonial habilitada para pagamentos; QuickBooks oferece ativo circulante e exclui fundos não depositados. Cada confirmação guarda organização, ambiente, conta e motivo em histórico imutável. Após uma substituição local de emissor pago, Correções financeiras prepara um pacote para revisão com crédito original, substituição, identidades e VAT congelados, recibos reais, compensações, reversões e saldos retidos. Prévia, referência e confirmação recusam mudanças concorrentes. O PDF mantém data e prova do pacote; novas configurações ou compensações locais marcam o histórico como desatualizado. PREPARED significa apenas preparação: não altera caixa, folha ou obrigações, não cria entrega automática nem confirma lançamentos nos livros. Conferir livros e exportar consulta os três documentos pelo número exato na organização congelada, exige o vínculo explícito do cliente e compara tipo, moeda, líquido, VAT, total e saldo pago das faturas. Documentos ausentes, duplicados, divergentes ou sem cliente vinculado aparecem no PDF; respostas inválidas e mudanças de evidência recusam a conferência. A conferência consulta também pagamentos existentes: no Xero, crédito e substituição precisam de pagamentos autorizados, vinculados ao documento e à conta patrimonial escolhida, com soma integral e sem alocações alternativas; no QuickBooks, verifica pagamentos exclusivos da substituição, cliente, moeda, conta, linhas e valor não aplicado zero. IDs duplicados, conta bancária diferente, pagamento eliminado, câmbio ou provas incompletas recusam a correspondência. A liquidação do crédito no QuickBooks permanece não suportada. O PDF distingue esses resultados da conferência documental. A consulta não grava lançamentos nem muda PREPARED: mesmo quando ambos os pagamentos de clearing coincidem, a rota do recebimento original e a conciliação completa continuam não verificadas. A prova do recebimento original e a entrega são feitas exclusivamente pelo fluxo dedicado abaixo; faturas já conectadas/exportadas exigem a prova específica descrita acima.

Estado actual — entrega de clearing no Xero. Após uma substituição local e a preparação, a gestão pode entregar a quitação patrimonial dos documentos no Xero das duas empresas: passivo circulante no emissor original e ativo circulante no correto. O caminho de fundos retidos aceita até três transferências manuais integralmente retidas pela empresa original, sem compensações ativas ou com histórico integralmente revertido e comprovado; uma compensação ativa entre as duas empresas usa o preparo-base específico abaixo; correções apenas de registro usam o fluxo próprio abaixo, e funcionários, terceiros, QuickBooks e diferenças de VAT original exigem tratamento específico. Confere o recebimento original pelo documento, banco com sort code e número completos, data, valor e referência quando registrada; preserva o dinheiro e a fatura original. A prévia mostra os clientes contábeis, documentos e contas; a confirmação explícita vincula IDs de cliente ausentes, sem sobrescrever vínculos existentes. Uma instrução durável por substituição fixa data, motivo, referência, organizações e prova. Com autorização explícita na prévia, cria crédito e substituição ausentes, um por chamada, com números e datas congelados, cliente ativo e conta de receita verificada. A linha contábil agregada preserva líquido e VAT históricos: este caminho aceita VAT registrado de 20% ou fornecedor não registrado sem VAT; outras classificações exigem revisão específica. A substituição conserva seu vencimento local. Documentos já existentes são conferidos, sem reescrever. Instruções antigas mantêm a exigência de documentos existentes; a retomada de criações usa número, referência e payload congelado, e relê a prova antes da liquidação. Cada chamada processa uma criação ou um lançamento, com reserva de execução e referência idempotente; a interface continua a sequência autorizada e falhas retomam os mesmos dados. CONFIRMED exige consultar e comprovar os dois pagamentos e o recebimento original; a lista separa entrega pendente, falha e confirmação, e o histórico/PDF distingue esta prova datada de uma conferência atual. Falhas parciais exibem os IDs comprovados e tentativas sem resultado verificado; uma resposta perdida não significa ausência de lançamento. A retomada recupera a prova pela referência original, e a instrução existente permanece consultável mesmo se o pacote ficou desatualizado. Contas, organizações e compensações ficam protegidas durante uma entrega pendente; reconectar a mesma organização preserva o vínculo para retomar. Não cria transferência bancária ou devolução ao cliente, não altera folha, reserva, recibos ou saldos operacionais: os fundos retidos continuam devidos entre as empresas. Criar recebimento original ou clientes contábeis continua pendente; destinos mistos de origem e detentores externos seguem o fluxo específico abaixo; detentores externos seguem o fluxo específico acima.

Estado actual — recebimentos mistos no Xero. Um pacote pode reunir até três recibos integralmente retidos, parte na conta da empresa original e parte com equipe ou terceira empresa. A conferência preserva os pagamentos bancários reais da origem, por conta completa, valor, data e referência; os demais detentores continuam identificados pela prova manual imutável. O crédito conserva o valor integral e o VAT histórico: somente a parcela recebida pela origem é quitada em conta de passivo circulante; o restante do crédito é aplicado ao saldo aberto da fatura original. A substituta é quitada pelo valor integral em ativo circulante, mantendo identificável quanto cada detentor ainda deve. Exemplo £120, sendo £60 na origem e £60 com funcionário: passivo de £60, aplicação de crédito de £60 na original e recebível de £120 na empresa correta. Prévia e PDF mostram parcelas, recibos preservados, alocação e lançamentos separados. Cada chamada executa no máximo um lançamento; resposta perdida retoma pela prova existente, e confirmação exige nova conferência completa. A recuperação assistida de FAILED verifica ambas as pernas e a alocação sem gravar no Xero. Não movimenta dinheiro, devolve ao cliente ou reescreve documentos, recibos e folha locais; o saldo retido integral continua devido. Compensações ativas, recibos de modos diferentes e dinheiro já na empresa correta exigem outro fluxo; compensações integralmente desfeitas conservam o histórico com efeito ativo zero.

Estado actual — contas contábeis por finalidade. A configuração permite manter a conta principal histórica ou acrescentar uma contrapartida distinta, de obrigação e recebível, fora do banco e em GBP. ADMIN/MANAGER revisa organização, ambas as contas e motivo antes de salvar um novo perfil imutável; alteração de qualquer conta ou vínculo invalida a prévia. Perfis antigos continuam válidos sem par. Nos novos pacotes com par, a origem usa obrigação e o destino recebível, e as duas finalidades ficam congeladas; a exportação identifica ambas. Finalidades canônicas são compartilhadas pelo domínio, permitindo que outro provedor forneça seu mapeamento sem mudar as regras; não ativa uma integração nova. Perfil usado por entrega pendente/FAILED continua protegido contra reconfiguração. Não cria contas remotas, lançamento, quitação, transferência ou saldo novo. A execução de compensações ativas ainda requer conferir e vincular as obrigações de ambos os lados.

Estado actual — prova de contrapartidas no Xero. Depois de conferir as duas dívidas-base, a ação de conferir livros procura lançamentos manuais pelo identificador determinístico da compensação e da empresa. Somente POSTED com duas linhas exatas — débito da obrigação, crédito do recebível, mesmo valor, contas/códigos congelados, sem imposto ou tracking — corresponde à proposta; a data não pode preceder a compensação, o recebimento ou a quitação-base. Duplicidade, paginação ambígua, rascunho e linhas alteradas recusam a prova. Ausência do identificador não prova ausência de outras compensações manuais. Tela/PDF mostram o lançamento encontrado; a conferência não autoriza nem envia journal; a entrega usa autorização separada. OAuth passa a solicitar accounting.manualjournals; conexões existentes precisam renovar consentimento e o usuário do Xero deve ter acesso a Reports. Recusa de acesso aparece como necessidade de reconexão, nunca como journal ausente. A autorização durável e a execução protegida seguem o fluxo de entrega de compensações abaixo.

Estado actual — vínculos das dívidas-base. A conferência de compensações vincula cada um dos dois recibos à substituição de emissor e à entrega contábil CONFIRMED que originou obrigação/recebível. Recibo atual, detentor, documento, organização, finalidade e valor precisam corresponder às provas congeladas; entrega ausente, FAILED, parcial ou prova incompatível permanece pendente. Consultar o pacote mostra apenas correspondência histórica. A ação de conferir livros relê, no Xero, as contas, os documentos quitados, a eventual alocação do crédito e os pagamentos não bancários identificados, preservando suas datas e referências efetivas; organização reconectada ou lançamento alterado recusa a prova. O estado local dos dois lados é revalidado após as consultas. Tela e PDF identificam a entrega-base e a data da conferência, sem afirmar que os recibos bancários originais foram novamente verificados ou que a compensação foi lançada. Não cria, modifica ou repete lançamento no provedor; a autorização/execução usa o fluxo separado descrito abaixo. Outros provedores conservam o contrato de vínculo e exigem adaptador próprio para conferência remota.

Estado actual — bases com compensação operacional ativa. Quando as duas substituições locais já estão registradas e preservam seus recibos, a entrega-base aceita até três compensações atuais entre as duas empresas, parciais ou integrais. Exige Xero nas duas organizações distintas, pares de obrigação/recebível configurados e recebimentos bancários integralmente retidos pelo emissor original; equipe, terceiros e registro incorreto permanecem nos fluxos próprios. A base liquida o crédito e a substituta pelo bruto integral, mesmo que o saldo operacional restante seja zero: não desconta a compensação nem cria journal. Os recibos dos dois lados, suas faturas e o uso cumulativo do saldo entram na prévia/instrução e nas guards de gravação; mudanças exigem nova revisão. Consulta as referências de compensação nas duas organizações e recusa qualquer lançamento existente, resposta ambígua ou acesso incompleto. A gestão confirma que não há compensação manual já lançada fora deste fluxo; a ausência da referência não substitui essa conferência. Durante PENDING/RUNNING/FAILED, nenhum lado aceita nova compensação ou reversão operacional; a retomada conserva a instrução e recupera respostas perdidas pela referência. UI/PDF separam a dívida-base integral da futura entrega da compensação. Somente depois das duas bases CONFIRMED e novamente verificadas é possível aprovar os journals de compensação; a exigência de conferir as bases é resolvida por essa prova, não tratada como um bloqueio estrutural permanente. Homologado na Demo Company (UK) com recebimento GBP, correção de VAT de 20% para 0%, crédito e substituta quitados, recuperação de resposta perdida, anulação de fatura de teste e efeito final zero de caixa/dívida.

Estado actual — entrega de compensações ativas. A conferência operacional permanece somente leitura; a autorização contábil é separada. Um pacote atual com compensações ativas entre as duas empresas permite selecionar cada uma para prévia e consentimento de ADMIN/MANAGER quando as duas entregas-base já estão CONFIRMED e novamente verificadas no Xero, com pares de contas de obrigação/recebível habilitados e organizações distintas. A gestão confirma também que não existem compensações manuais fora deste fluxo: a ausência da referência não comprova essa ausência nos livros. Motivo, referência, data, valor, contas, organizações, recibos e IDs-base ficam em uma instrução imutável e única por compensação. Cada chamada cria no máximo um ManualJournal POSTED equilibrado: débito no passivo e crédito no ativo, sem banco, VAT ou participação em relatórios de caixa; a UI continua a sequência aprovada. Referência determinística e chave idempotente permitem retomar resposta perdida; IDs conhecidos removidos, substituídos ou alterados recusam repetição. CONFIRMED exige outra chamada com nova leitura dos dois lançamentos, na data e política aprovadas, além das duas obrigações-base. Falha parcial conserva tentativas e instrução, permite retomada e protege contas, organizações e novos usos dos recibos. Uma compensação com entrega aprovada não aceita reversão operacional: precisa da reversão contábil dedicada nos dois livros descrita acima. UI e PDF distinguem autorização, tentativa, prova histórica datada e consulta atual, preservando recibos, faturas, folha e caixa. Bases ausentes, equipe, empresa fora do pacote e outros provedores continuam recusados; a homologação em organizações Xero reais permanece pendente.

Estado actual — reversões e recuperação contábil. Compensações operacionais integralmente desfeitas permitem a entrega normal do saldo original: o servidor confere a prova dos dois destinos opostos, valor original, reversão integral e histórico imutável. A prova conserva as compensações e reversões, com efeito ativo zero; não afirma entrega contábil de uma compensação. Compensações ainda ativas, prova incompleta ou história fora do limite de conferência continuam recusadas. Uma instrução FAILED sem lease pode ser encerrada pela gestão somente após revisão dos lançamentos já existentes nos dois livros, motivo, referência e confirmação da mesma prévia. A revisão não cria ou altera lançamentos no Xero: conserva documentos, contas, valores, recibos reais e organização congelados; aceita referência ou data efetiva diferente na quitação existente apenas dentro das datas válidas dos documentos. Os IDs de pagamentos conhecidos em tentativas anteriores precisam continuar na quitação atual ou ter reversão comprovada; resposta parcial ou pagamento anterior sem destino comprovado não permite encerramento. CONFIRMED conserva a instrução, as tentativas, as provas anteriores e a nova resolução com ator, motivo, referência e data em prova imutável. A tela mantém a prévia após falha ambígua e o PDF distingue a conferência histórica de lançamentos existentes de uma entrega executada pelo sistema. Alterações reais de valor, cliente, organização ou destino exigem tratamento próprio; não há abandono que apague a execução parcial ou libere seus vínculos sem comprovação.

Estado actual — correção de registro nos livros. Quando todos os recibos de um pacote são correções apenas de registro, a conferência comprova separadamente até três pagamentos bancários já existentes na fatura substituta do Xero da empresa correta, por cliente, organização, documento, banco completo, valor, data e referência congelados. A entrega tem prévia e consentimento próprios: fixa os IDs dos lançamentos bancários indevidos na empresa original, cria somente o crédito ausente quando autorizado, desfaz um lançamento por chamada e aplica o crédito integral à fatura original. Exige lançamentos individuais explicitamente não conciliados, sem batch, câmbio, compensações ou outra quitação; prova original incompleta, ambígua ou alterada recusa o fluxo. Cada tentativa preserva a instrução e a prova parcial; resposta perdida é recuperada consultando os mesmos IDs, inclusive DELETED, e a alocação existente antes de repetir. CONFIRMED exige uma nova conferência completa dos dois livros, dos recebimentos reais e dos saldos original e crédito zerados. A tela e o PDF distinguem reversão de lançamento e alocação de crédito dos recibos reais preservados; a entrega não cria dívida por fundos retidos, transferência, devolução ou novo recebimento, nem reescreve faturas, recibos, visitas e folha locais. Equipe, terceiros, cenários mistos, compensações, divergência de VAT e futuros provedores continuam exigindo fluxo específico.

Estado actual — parcelas recebidas pela equipe. O recebimento manual aceita parcelas em dinheiro ou conta de funcionário, inclusive após outra parcela. Em fatura agrupada, o administrador informa o valor recebido por visita; a soma precisa coincidir com o recebimento e cada valor respeita o saldo documental comprovado. Cada parcela conserva visita e recebedor, sem sobrescrever coletas anteriores. O saldo não recebido continua devido. Visita, fatura e deduções de folha são gravados juntos: DRAFT recebe apenas a diferença e folha fechada recebe ajuste futuro por visita. Confirmar dinheiro já previsto não deduz outra vez. A identidade do recebimento permite repetir uma tentativa com os mesmos dados sem criar uma segunda parcela.

Estado actual — reemissão com folha vinculada. Trocar empresa, rota, conta ou recebedor exige motivo e prévia do servidor. Com folha vinculada, a dedução prevista muda por diferença em DRAFT ou por ajuste futuro em folha fechada. Mudanças de lucro fiscal usam as contribuições e percentuais congelados da rodada: beneficiários históricos recebem diferenças em DRAFT ou ajustes futuros, e a reserva acompanha o lucro acumulado da rodada, incluindo todas as visitas de uma fatura agrupada. Sem contribuição histórica comprovada, a alteração de lucro é recusada. A prévia mostra essas diferenças e perde validade se fatura, visitas, folha ou configuração fiscal mudarem. A visita usa a base fiscal da empresa escolhida; o documento anulado mantém valores e número originais. Depósitos, recebimentos já registrados e documentos de correção de preço continuam recusados neste fluxo; exigem conciliação financeira própria. Correções anteriores de custo, remuneração ou reemissão fiscal permitem nova reemissão sem recebimento, desde que o histórico seja comprovado e não haja crédito, suplemento ou outro documento financeiro vinculado. Ajustes anteriores permanecem intactos e entram no cálculo acumulado da rodada e da reserva; novas mudanças de coleta geram somente a diferença. Históricos incompletos são recusados. O recebimento manual com troca de billing também consulta essa prévia antes de reemitir e registrar o total integral: valor fiscal e ajustes de coleta vêm do servidor, e motivo, data ou referência diferentes invalidam a confirmação. A nova fatura retorna com linhas, snapshots e recibo efetivamente gravados.

Estado actual — destino do recebimento. Correções financeiras distingue registro errado de dinheiro que realmente entrou no destino errado. A gestão escolhe uma transação manual positiva identificada e comprovada, informa quem efetivamente recebeu, motivo e referência e confirma a prévia. O registro original, a fatura fiscal e a prova exportada permanecem intactos; o histórico de conciliação mostra o recebedor efetivo. Trocar o detentor registrado atualiza somente a coleta da visita: DRAFT recebe diferenças e folha fechada recebe ajustes futuros; quem não possui folha original entra pela geração normal. Depósitos, devoluções ou coleta histórica sem prova recusam mudanças de detentor em folha. Dinheiro no destino errado registra o destinatário pretendido e o valor de acerto pendente, sem simular transferência, devolução ou novo pagamento do cliente. O saldo pendente não pode desaparecer por simples correção de registro. A gestão pode compensar parcialmente duas obrigações atuais entre os mesmos destinos em sentidos opostos, com motivo, referência e prévia. O valor baixa igualmente nos dois saldos em um registro imutável; confirmação concorrente não excede o saldo nem duplica a compensação. Recibos, faturas e folha ficam intactos, sem transferência ou devolução. Após compensar, os destinos ficam preservados e devoluções da fatura são recusadas enquanto existir compensação ativa. Uma compensação equivocada pode ser desfeita por inteiro, com motivo, referência e prévia: a reversão imutável restaura igualmente os dois saldos, conserva o histórico e não altera recibos, faturas ou folha. Outra compensação ativa mantém o bloqueio; sem ela, voltam a valer as regras normais de correção do recebimento e de devolução comprovada. Substituições de emissor continuam preservando a prova e os destinos. A seleção consulta o histórico do servidor por páginas de 100, não o boot. Esta compensação é operacional, fora dos livros conectados: exportar os ajustes contábeis ainda exige fluxo próprio; o emissor pago usa a substituição vinculada descrita acima.

Estado actual — correções pela fatura. A gestão abre Correções financeiras diretamente na prévia de uma fatura, incluindo pagas e anuladas. O painel consulta a visita no servidor, mesmo fora do boot, e usa o editor financeiro com motivo, prévia e confirmação. Exibe créditos, suplementos, alocações, devoluções e efeitos contábeis vinculados à fatura original, ao suplemento ou às suas visitas; permite as ações existentes de crédito e retry contábil. O resumo consultado no servidor separa dinheiro recebido, devolvido, quitação por crédito e saldo documental; evidência inválida ou pagamento pendente exige conciliação. Os movimentos mostram data e referência. Uma redução já paga oferece crédito ou registro de devolução comprovada. A seleção de destino do crédito ou devolução consulta faturas históricas no servidor, com paginação e limite disponível por fatura; não depende do boot. Faturas de outro cliente ou empresa e pagamentos pendentes não são oferecidos. Para devolução com entrega contábil ativa, o fluxo oferece transferência pela conta bancária da organização original congelada no crédito; conexão trocada exige reconectar a organização original, sem oferecer contas do novo destino; devolução financiada por funcionário mantém a recusa até existir prova da conta de ressarcimento. Recebimentos conservam o emissor original: a substituição do emissor recebido usa o fluxo próprio descrito acima, sem transferência de dinheiro.

Estado actual — cobrança. No Billing Center, as faturas pagas não têm KPI: a aba Pagas é só a lista, com o filtro de período e paginação. O Manual settlement grava o pagamento no servidor a partir da fatura guardada. Trocar o billing nesse diálogo anula a fatura, emite a nova já com número e regista o pagamento nela (só o valor total); dinheiro ou conta de funcionário grava quem recebeu e o bruto (staffCollectedBy, staffCollectedCash). No Editar tarefa, transferência com mais de uma conta da empresa deixa escolher a conta (plannedBankAccountId, null = a principal); a fatura nasce com ela quando as visitas concordam, e uma fatura aberta da visita acompanha. A emissão reserva no servidor o próximo <PREFIX>-<ANO_LONDRES>-<N> sobre todo o histórico, rejeita prefixo repetido, visita já faturada, cliente/entidade divergentes e pagamentos recebidos pela equipe. Cliente, emissor e conta são congelados nas colunas *_snapshot_json; bank_account_id continua sendo apenas o id da conta escolhida. Cartão e débito aparecem quando Stripe/GoCardless estão prontos; Crezco permanece somente como link manual até existir uma integração homologada.

Estado actual — Drafts e Invoice. Drafts reúne tarefas realizadas ainda não faturadas e tarefas de rascunhos persistidos; Invoice reúne documentos emitidos, com filtros de pagamento. Abrir a prévia não grava um documento; emitir prepara o rascunho e reserva a numeração definitiva no servidor. Selecionar parte de um rascunho preserva suas linhas e valores e deixa o restante no original, sem criar vínculos duplicados. A emissão por cliente separa documentos com empresa, VAT, conta, recebedor, método, notas ou prazo diferentes. Falha pode deixar rascunhos preparados ou parte do lote emitida; a lista permite continuar pelas tarefas restantes. Anular uma invoice preserva seu número e histórico e devolve tarefas não pagas a Drafts, inclusive cobranças pela conta do funcionário; recebimentos confirmados permanecem protegidos. Emissão e anulação concluídas com auditoria retornam sucesso, sem falso conflito pela contagem de gravações do D1. Anulações em lote são aguardadas em sequência; pagamentos só são anunciados como aprovados ou revertidos quando o servidor aceita. Lotes com zero confirmações não anunciam sucesso; documentos recusados permanecem selecionados. A reversão simples de uma baixa não altera pagamentos exportados nem depósitos: baixa equivocada exige correção financeira/contábil, e devolução só se registra quando o dinheiro realmente voltou ao cliente.

Estado actual — período e livros. Histórico e Relatórios pedem visitas e faturas por período de Londres (GET /api/atomic/requests|invoices?from&to); isso não mistura no cache operacional do boot. Reembolso é quantidade (fatura permanece PAID, transação negativa). Só o webhook assinado do gateway marca pago. Concluir visita deixa paymentStatus NONE, não DRAFT. VAT absorvido no preço (vatTreatment). O Xero usa uma organização por entidade fiscal; syncInvoiceToXero não lança. As entidades seguem sort_order; a primeira é o padrão em todo lugar. Cada entidade pode ter um nome fantasia (short_name, Settings → a entidade → Nome fantasia): é como ela aparece nas telas da equipe (tarefa, filtros de faturamento, listas, painel, banking), por fiscalEntityLabel, e em branco vale o nome legal. Faturas, PDFs, e-mails, página de pagamento e a contabilidade sempre usam o nome legal; o cliente e a equipe de campo não recebem o nome fantasia no boot.

No Overview, A faturar inclui a taxa de remarcação e desconta o depósito já pago, como a próxima fatura; Aguardando pagamento, idade e devedores usam só o saldo ainda devido. A idade é em dias de calendário de Londres. VAT absorvido também sai dos valores das faturas e dos recebimentos (invoiceRevenue, pela taxa da entidade e pelo acordo do cliente quando a fatura não traz VAT explícito); não se altera a fatura nem o pagamento. Escolher uma empresa sem atividade mantém o seletor disponível para voltar a todas.

O módulo Billing gerencia o faturamento fiscal dos serviços executados, calcula a rentabilidade líquida por limpeza, controla a quitação das faturas dos clientes e sincroniza as faturas com o Xero (uma organização por entidade fiscal).

O envio de fatura por e-mail mantém separação entre diagnóstico e experiência: falhas do Resend ou do Worker são sanitizadas no log interno, enquanto PWA, Android, iOS e desktop recebem somente uma mensagem estável para tentar novamente. O objeto do provedor, stack e possíveis credenciais nunca integram a resposta 500. O composer usa AdaptiveBottomSheet, CFInput, Button e IconBadge; valida e normaliza destinatário, assunto e corpo antes do envio, mantém lock síncrono, bloqueia fechamento durante a entrega e preserva o rascunho em falha. O link de pagamento usa sempre a origem atual ou o fallback oficial app.primecrowncleaning.co.uk. O envio do mesmo documento por WhatsApp captura o PDF montado, usa mutação limitada a 15 segundos e associa um AbortController à fatura visível. Fechar, desmontar ou trocar a fatura cancela a rede; uma conclusão sem ownership não produz háptico ou toast, e falha preserva a prévia para retry.

Persistência atômica de faturas e entidades fiscais segue o mesmo limite: erros inesperados são classificados no log administrativo e retornam o contrato compartilhado de retry, enquanto validações fiscais e permissões continuam específicas.

Void, dispatch e remoção de uma visita usam um owner síncrono por fatura e snapshots atuais do store, sem rede, log ou atualização cruzada dentro de updaters React/Zustand. /api/billing/invoice-operation valida papel, estado e vínculos esperados e grava service_requests, invoices e itens normalizados em um único D1Database.batch, com guards repetidos contra concorrência. Void e remoção publicam estado otimista, mas só anunciam conclusão depois da transação; falha restaura os dois domínios, e teardown descarta resposta/toast tardio em desktop, PWA, Android e iOS. A revalidação do cache também captura a sessão que iniciou a operação: uma resposta financeira antiga jamais faz a conta autenticada depois de logout/login refazer requests ou invoices.

Confirmação de pagamento e recebimento direto observam sempre o snapshot atual de serviços, inclusive quando a agenda mudou sem alterar a lista de faturas. As visitas retornadas pela regra financeira são mescladas por um índice de ID compartilhado, preservando ordem, referências não alteradas e a precedência histórica da primeira atualização duplicada. Isso evita tanto closures antigas quanto buscas quadráticas durante a reconciliação local nas quatro experiências.

O módulo suporta pagamentos parciais nativos (Split Payments): balanceDue é calculado como Math.max(0, grandTotal - paidAmount), links /pay/:invoiceId adaptam o valor ao saldo devedor restante e a alocação bancária unificada (statementAllocation) mantém o saldo das transferências parciais sem marcar a fatura como quitada indevidamente. O conciliador bancário também suporta múltiplos apelidos (client.alias separados por vírgula, barra ou ponto-e-vírgula) para identificar depósitos com identificações alternativas no extrato.


💰 1. Cálculo de Rentabilidade (ProfitLogic)

Section titled “💰 1. Cálculo de Rentabilidade (ProfitLogic)”

Para cada serviço executado, o ProfitLogic apura a margem financeira real:

$$\text{Lucro Líquido} = \text{Valor Pago pelo Cliente} - \text{Custo da Funcionária} - \text{Imposto (VAT)} - \text{Taxa de Material/Logística}$$

  • Margem de Lucro (%): $(\text{Lucro Líquido} / \text{Valor Total}) \times 100$.
  • Alerta de Margem Baixa: Se a margem de lucro de um cliente ficar abaixo de 35%, o sistema gera um alerta visual no painel financeiro para revisão de tarifa.
  • P&L (calculateNetPL): a receita segue a regra única de VAT (vatTreatment.splitVatNetOfRefunds), inclusive para cliente com VAT absorvido. Reembolso parcial subtrai só a parte líquida: devolver metade de um job de £100 + VAT (£60) deixa £50 de receita. Antes subtraía o bruto e mostrava £40.

Lucro gravado na tarefa. Toda escrita em /atomic/requests com preço e custo recalcula financials.profit como receita sem VAT − custo (jobProfit, functions/api/common/jobProfit.ts, sobre splitVat): VAT por cima → preço − custo; VAT absorvido → preço sem o VAT de dentro − custo; entidade sem VAT → preço − custo. Antes era preço − custo − vatAmount, que tirava o VAT de um preço já líquido (o carpet de £88 com payout de £70,40 gravava £0) e deixava a divisão de lucro da folha, que lê esse campo, um quinto menor em toda tarefa com VAT.

📑 2. Ciclo de Vida da Fatura (InvoiceStateLogic)

Section titled “📑 2. Ciclo de Vida da Fatura (InvoiceStateLogic)”
stateDiagram-v2
    [*] --> DRAFT: Escritório prepara o rascunho
    DRAFT --> SENT: Emissão com número definitivo
    SENT --> PENDING_REVIEW: Cliente informa transferência
    SENT --> OVERDUE: Vencimento com saldo em aberto
    SENT --> PAID: Pagamento confirmado cobre o saldo
    PENDING_REVIEW --> PAID: Recebimento confirmado
    OVERDUE --> PAID: Quitação
    SENT --> VOID: Anulação permitida

🇬🇧 3. Integração contábil Xero (2026-09-29)

Section titled “🇬🇧 3. Integração contábil Xero (2026-09-29)”

Em Settings → Entidades fiscais → Accounting, um ADMIN conecta Xero ou QuickBooks por entidade. O painel do QuickBooks oferece a conexão de produção. A emissão usa o gatilho comum queueAccountingSync, e o provedor conectado processa a fila da entidade. Os painéis permitem reenviar falhas em lotes. Veja as regras de pagamentos no QuickBooks no início desta página.

  • Conectar e reconectar: Settings → entidade fiscal → aba Accounting (FiscalXeroPanel), só ADMIN. GET /api/billing/xero?action=auth-url abre o consentimento do Xero; o retorno é /api/billing/xero-callback (state assinado com entidade + admin, 10 min). Só as organizações deste consentimento contam (/connections?authEventId=); consentimento com mais de uma é recusado (?xero=several). O botão Reconectar executa desconexão/revogação prévia automática antes de abrir o Xero para garantir a seleção limpa de organização única e evitar conflitos de sessão ou erro de múltiplas entidades.
  • Um app Xero para todas as entidades: XERO_CLIENT_ID / XERO_CLIENT_SECRET (cofre; XERO_REDIRECT_URI opcional). Escopos granulares (apps criados desde março de 2026): offline_access accounting.invoices accounting.payments accounting.contacts accounting.settings.read. Uso só da própria empresa: até 5 conexões na faixa gratuita, sem certificação.
  • Ao conectar e sob demanda (discoverXeroDefaults): nome da organização; conta de vendas (200 “Sales”, senão a primeira receita ativa); conta bancária dos pagamentos (a do Xero cujo número termina no accountNumber principal da entidade, senão a primeira ativa — o painel mostra qual); se existe a alíquota 20% OUTPUT2. Se a conta bancária não existia no Xero no momento da conexão, o painel oferece o botão de atualização imediata (POST … { action: 'refresh' }) e qualquer sincronização subsequente redescrobre a conta automaticamente sem exigir reconexão.
  • Tokens: access 30 min, renovado 2 min antes e de novo num 401; o refresh token gira a cada uso e expira em 60 dias sem uso (aí o painel pede reconectar). Gravação condicional ao refresh anterior, como era no QuickBooks. Criptografados (tokenCrypto), nunca saem do servidor.
  • Sincronização automática (queueXeroSync, depois da resposta, nunca atrasa nem derruba a ação): emissão, pagamento (webhooks Stripe/GoCardless, carteira, baixa manual, conciliação), anulação e cancelamento. syncInvoiceToXero (nunca lança; todo resultado em xero_invoice_sync):
    • DRAFT → SKIPPED; empresa sem HMRC → EXCLUDED; dinheiro/conta de cleaner → EXCLUDED; fatura que sumiu → registro apagado.
    • Contato por entidade e organização (xero_contacts): pelo e-mail (extraindo o endereço principal caso múltiplos e-mails estejam separados por vírgula), depois por um nome que nenhum outro cliente nosso usa; o Xero quer nome único, então um nome já tomado ganha o id do cliente. Mapeamentos legados que retornem 404 (ex.: Demo Company reiniciada no Xero) são limpos automaticamente, recriando ou reencontrando o contato. A exportação em massa inicial (FiscalXeroClients, opcional e colapsável) avança o cursor mesmo se um contato falhar, identifica o nome com erro, e oferece sincronização contínua com intervalo seguro para rate limit, mantendo chaves de renderização com prefixo exclusivo (xero-clients-, xero-clearing-) para evitar colisão de nós e duplicação visual no DOM durante re-renderizações ou refetches periódicos.
    • Fatura de venda ACCREC AUTHORISED com o nosso número; antes de criar procura pelo número (ignorando anuladas), então resposta perdida vira atualização. Se uma fatura mapeada anteriormente retornar 404 no Xero (ex.: exclusão remota ou reset de sandbox), o id remoto órfão é limpo automaticamente e a fatura é reencontrada ou recriada com sucesso. Paga no Xero não é mais editada.
    • VAT por cima → Exclusive + OUTPUT2; VAT absorvido de entidade registrada → Inclusive + OUTPUT2 (o Xero tira o VAT de dentro); registrada sem VAT → “No VAT” (NONE); não registrada → NoTax. A taxa de pagamento repassada vai como linha “No VAT”.
    • PAID → um pagamento (total + taxa) na conta bancária encontrada, referência do gateway. Pagamentos mapeados anteriormente que não existam mais no Xero ou fiquem órfãos em faturas recriadas (ex.: reset da organização de demonstração) são invalidados e recriados do zero com base nos recibos locais sem travar a sincronização. VOID → anula; se já houver pagamento no Xero, ele é apagado antes (o Xero não anula fatura paga).
  • Fatura reemitida ou anulada (/billing/invoice-reissue): segue a mesma regra do Xero e do HMRC — a numeração nunca é reciclada nem reaproveitada. A fatura original retém permanentemente o seu número com status VOID e sincroniza como VOIDED no Xero/QuickBooks; a nova fatura emitida ou reemitida avança a sequência e recebe o próximo número (nextInvoiceNumber).
  • Tratamento de faturas anuladas (VOID): Uma fatura anulada é estritamente terminal e serve apenas para exibição/consulta histórica. Como as tarefas ligadas já foram libertadas e retornaram ao pool de faturamento e a numeração fiscal foi queimada, a transição de status para faturas VOID é bloqueada (canTransitionInvoice('VOID', ...) retorna false), impossibilitando anular uma fatura já anulada (“sem void do void”). No modal de visualização (InvoicePreviewModal), os botões de cobrança, CheckoutPanel, liquidação manual (finalise) e seleção de contas são ocultados, exibindo apenas o aviso informativo e a prévia/download em PDF. A contagem e valores de faturas anuladas não integram os chips de KPI do BillingToolbar, ficando restritos à aba secundária “Anuladas”. Na aba Anuladas, a exibição é exclusivamente em tabela (o seletor cards/table é ocultado no toolbar), sem caixas de seleção (checkboxes) desnecessárias, com paginação integrada (Pager, 15 itens por página) e seletor de filtro por período na mesma linha do botão Exportar (Todo o período, Este mês, Últimos 30 dias, Últimos 90 dias, Este ano). Listas sem registros utilizam o cartão estilizado padronizado (Card role="status" padding="none" com CFEmptyState). Na janela operacional de boot e recarregamento (operationalInvoiceWhere), faturas VOID recentes (emitidas ou anuladas na janela de 14 dias de Londres) são preservadas para a visualização dos gestores, não sumindo ao atualizar a página (enquanto permanecem rigorosamente ocultadas de clientes).
  • Falhas: o painel mostra o último erro e “N faturas não foram”, além de uma gaveta expansível com a lista detalhada de cada fatura com falha (número, cliente, valor, motivo exato retornado pelo Xero e botão de sincronização pontual). Faturas canceladas, rascunhos ou substituídas por correção são limpas ou marcadas como EXCLUDED para não reter a fila. Enviar de novo (POST /api/billing/xero { action: 'retry' }) manda as falhas mais antigas em lotes de 4 faturas por requisição (para respeitar com folga o limite de 60 chamadas/min do Xero e o timeout de mutação do cliente), atualizando dinamicamente no botão e no painel a contagem de faturas restantes e com falha a cada lote processado.
  • Entrada contábil (Xero → Prime Crown): webhook em /api/webhooks/xero com XERO_WEBHOOK_KEY (HMAC-SHA256 Base64 com x-xero-signature). Responde 401 a assinatura inválida (requisito do Intent to Receive) e confirma 200 somente após persistir notificações de documentos vinculados. Em background observa até duas notificações usando o contrato comum; não liquida faturas/visitas nem fabrica recibos. O histórico e a prévia de conciliação estão descritos no Estado actual — entrada contábil comum.
  • Arquivos: functions/lib/xero/ (oauth, connection, setup, syncInvoice, autoSync), functions/api/billing/xero.ts, xero-callback.ts, functions/api/webhooks/xero.ts, src/features/billing/services/XeroApiService.ts, src/components/settings/forms/fiscal/FiscalXeroPanel.tsx. Tabelas xero_connections, xero_contacts, xero_invoice_sync (migração 0177; as do QuickBooks, 0136, seguem).
  • Paridade QuickBooks Online: Painel FiscalQuickBooksPanel espelha o fluxo do Xero com suporte a sync_mode (migração 0250), reenvio em lote com rate-limit cooldown, gaveta de faturas com falha e sincronização pontual, refresh de contas e descoberta automática de defaults, e webhook de conciliação bidirecional /api/webhooks/quickbooks com assinatura HMAC-SHA256 (intuit-signature). Endpoints: /api/billing/quickbooks, /api/billing/quickbooks-callback, /api/billing/quickbooks-invoices e /api/webhooks/quickbooks. Chaves de cofre documentadas em SECRETS.md: QUICKBOOKS_CLIENT_ID, QUICKBOOKS_CLIENT_SECRET, QUICKBOOKS_WEBHOOK_VERIFIER_TOKEN.
  • Data de corte contábil (Cutoff Date): Ambos os painéis (Xero e QuickBooks Online) permitem configurar opcionalmente uma data de corte (sync_cutoff_date, migração 0251). No QuickBooks, somente faturas ainda sem vínculo emitidas antes dessa data são ignoradas; no Xero, faturas emitidas antes dessa data são ignoradas como EXCLUDED (“Before sync cutoff date”), permitindo integrar novas empresas sem enfileirar ou gerar falhas para faturas legadas/históricas. Quando em branco, todas as faturas são sincronizadas.

🏛️ 4. Ecossistema de Pagamento Open Banking UK (Pay by Bank)

Section titled “🏛️ 4. Ecossistema de Pagamento Open Banking UK (Pay by Bank)”

O Prime Crown dispõe de um ecossistema de pagamento integrado via Faster Payments / Open Banking UK:

  1. Página Pública de Pagamento (/pay/:invoiceId):

    • Acesso público e seguro para clientes sem exigência de login via src/pages/PublicInvoicePay.tsx.
    • Links curtos de pagamento (/pay/<code>): novas faturas utilizam identificador opaco curto de 8 caracteres em Base62 (src/shared/shortCode.ts, ~218 trilhões de combinações, mesmo padrão seguro dos links rápidos /go/<code>), reduzindo o tamanho do link copiado e enviado por WhatsApp/e-mail em ~40% (ex: https://app.primecrowncleaning.co.uk/pay/k7Q2mX9p). Faturas legadas com UUID longo são resolvidas pelo backend tanto pelos 8 caracteres hexadecimais iniciais (publicInvoicePayUrl) quanto pelo identificador original completo, garantindo 100% de compatibilidade com mensagens já enviadas.
    • A conta bancária principal da entidade fiscal é nome do banco + sort code + número da conta (bank_name, sort_code, account_number); PDF, e-mail e cartão das Configurações montam o texto com formatBankAccount (src/shared/bankAccount.ts) e as páginas públicas mostram os mesmos campos, então não há duas versões da conta. Outras contas da empresa ficam em other_bank_accounts_json (otherBankAccounts): aparecem no cartão; “Tornar principal” troca uma delas com a principal. A fatura usa a principal por padrão; na tela da fatura, admin/manager escolhe outra conta em Pay into (invoices.bank_account_id, gravado só por PATCH /api/atomic/invoices, que recusa conta de outra empresa e fatura PAID/VOID). PDF, QR, e-mail e página de pagamento resolvem a conta com invoiceBankAccount; conta removida volta para a principal. O extrato do cliente continua mostrando a principal. Cada conta tem nome do banco (obrigatório) e titular (account_name / accountName): em branco, o titular é o nome da entidade; se a entidade recebe em conta de terceiros (allowsCashAndThirdPartyCollections, ex.: Madrid, cujo nome é fictício), o titular é obrigatório em toda conta. PDF, QR, e-mail, página de pagamento e extrato mostram o titular (“Account name”). A referência HMRC é opcional (a fatura só imprime a linha quando existe). O número de VAT da entidade é editado no mesmo formulário e sai em toda fatura.
    • O formulário da entidade só fecha quando o servidor aceitou o save; se recusar, fica aberto com o que foi digitado e o toast diz o campo recusado. Colunas NULL (ex.: bank_name de entidades sem dados bancários antigos) são aceitas como vazias.
    • Janela da entidade fiscal (2026-09-29): três abas em CFTabs dentro do SettingsEntryModal (tamanho md): Legal & bank (identidade, VAT, contas, transferência/caixa), Payments (Stripe | GoCardless num seletor; só um fica ligado — ligar um desliga o outro, e POST /atomic/fiscalEntities recusa os dois ligados com 422) e Accounting (QuickBooks). A barra antiga de botões (justify-center + overflow-x-auto num sheet sm) deixava abas fora de alcance e não rolava.
    • Pay by card (Stripe Checkout) e Pay by bank (GoCardless Instant Bank Pay) aparecem só quando o gateway da entidade fiscal tem chave de API e segredo de webhook salvos; a taxa repassada é mostrada no botão. No Android e iOS o checkout abre no navegador do sistema e o retorno por App/Universal Link recarrega a mesma URL pública, incluindo a fatura e ?checkout=success|cancelled; no PWA e desktop a navegação permanece no navegador. A página então avisa e se atualiza sozinha por até ~30 s até o webhook marcar a fatura como paga.
    • Dados manuais BACS (Sort Code + Account Number + Referência) com botões de cópia rápida, e o botão I’ve made the transfer, que registra o aviso via /api/payments/transfer-claim (fatura em PENDING_REVIEW, “Payment under review”).
    • Endpoint backend seguro: functions/api/public/invoice.ts.
    • Auditoria de Leitura da Fatura pelo Cliente (viewedAt): Ao carregar a página pública /pay/<code>, o backend audita e grava o timestamp viewedAt dentro de client_snapshot_json (sem necessidade de migração de banco e sem sobrescrever leituras posteriores). O Billing Hub exibe o indicador visual discreto (ícone Eye com data e hora da abertura em tooltip) tanto no InvoiceRowCard quanto na InvoiceTable, permitindo que o gestor saiba exatamente quando o cliente abriu a cobrança.
    • A leitura possui limite de 12 segundos, é cancelada ao sair da tela e diferencia link inexistente de falha de conexão; esta última preserva um botão Try again.
    • Compartilhamento Direto: botão de cópia “Copy Link” na barra de ações da fatura (InvoicePreviewModal.tsx), botão direto “Pay Online Now” no e-mail com a fatura e link direto na legenda do envio por WhatsApp.
  2. Botão e QR Code no PDF Oficial:

    • O componente InvoiceDocument.tsx estampa o botão interativo “Pay by Bank” e o QR Code vetorial gerado por OpenBankingService.ts com qrcode-generator, a partir do link /pay/<id> da fatura. Até 2026-09-11 era um desenho fixo que não escaneava para nada. Desde 2026-10-14 o QR ocupa a altura da barra escura (96 px), com “Or scan the code with your phone’s camera”, e o botão diz “Click here to pay · ”.
    • O aging de recebíveis (BillingAnalyticsLogic.calculateReceivablesAging) conta só faturas emitidas (SENT, PENDING_REVIEW); rascunho não é recebível.
  3. Emissão Automática de Recibos (Payment Receipts):

  4. Cobrança & Lembretes Inteligentes (Smart Dunning):

  5. Remetente de e-mail: todo e-mail do sistema sai de @primecrowncleaning.co.uk, o domínio verificado no Resend. @primecrown.co.uk não tem DKIM/MX do Resend e seis tipos de e-mail (recibo, lembrete, conciliação, confirmação GoCardless, briefing diário, alerta de materiais) eram recusados em silêncio.

  6. Link de Pagamento Manual (Monzo / Crezco / Outros):

    • Na tela de detalhes da fatura (InvoicePreviewModal.tsx), admins e managers podem colar qualquer link de pagamento manual em Manual Payment Link (Monzo / Crezco) (ex.: links criados no app do Monzo ou no portal da Crezco).
    • O link é salvo via PATCH /api/atomic/invoices na coluna invoices.payment_link (rejeitando protocolos inválidos).
    • Quando preenchido, a página pública de pagamento (PublicInvoicePay.tsx) renderiza o card Instant Pay (“Pay directly via Monzo/Crezco”, pelo endereço do link — paymentLinkProvider) e o botão Pay Now direcionando o cliente para o link externo.
    • O QR Code e botão do documento/PDF (InvoiceDocument.tsx e OpenBankingService.ts) passam a apontar diretamente para esse link manual.
    • Disponibilidade contínua de transferência bancária: Mesmo com o link manual ativo, os dados bancários oficiais da empresa (Sort Code, Account Number, Reference e Nome da Conta) continuam sendo exibidos com destaque tanto na página pública quanto no PDF/documento da fatura, permitindo que clientes que não confiam em links de terceiros façam a transferência direta via app do banco com comodidade.
    • Reconciliation Quick Check: O modal exibe em tempo real a conta de destino oficial da empresa para a qual a fatura foi emitida (Razão Social, Titular, Banco, Sort Code e Account Number). O sistema analisa a URL em tempo real para alertar divergências de valor em relação à fatura ou incompatibilidade de banco (ex.: link Monzo.me colado em fatura com conta destino em outro banco). Ao salvar, um modal de confirmação exibe os dados da conta para validação do operador.
    • Imutabilidade e Unicidade da Fatura (Snapshots Legais e Financeiros): o servidor congela cliente, emissor fiscal e conta de recebimento em client_snapshot_json, fiscal_snapshot_json e bank_account_snapshot_json. bank_account_id guarda somente a escolha da conta. Pagamentos em dinheiro ou conta da funcionária não geram fatura: a equipe registra o recebimento na visita.
    • Layout de Duas Colunas Consistente em Todos os Status (InvoicePreviewModal.tsx): Ao abrir uma fatura em qualquer status (DRAFT, SENT, PENDING_REVIEW ou PAID), o comportamento visual é uniforme e espelha a experiência de emissão:
      • Lado esquerdo (Documento): Exibição completa e desobstruída do documento oficial da fatura (InvoiceDocument.tsx), com pílula da entidade fiscal e selo de status reativo no topo. O clique na referência da tarefa (T-YYYY-NNNN) abre a visita sobre a própria fatura via TaskActionRegistry (sem abrir nova janela nem quebrar o PWA no iOS/Android).
      • Lado direito (Opções do Status):
        • DRAFT: DraftPaymentPanel.tsx (instruções de cobrança, contas bancárias, equipe e emissão).
        • SENT: CheckoutPanel.tsx (métodos de pagamento, baixa manual de equipe/escritório, gateways online).
        • PENDING_REVIEW: PendingReviewPanel.tsx (dados do comprovante informado, conta esperada para checagem rápida no extrato, botões de Aprovar Pagamento para quitação imediata, Rejeitar Comprovante e contato com cliente).
        • PAID: PaidStatusPanel.tsx (resumo da quitação com valor, data, método, funcionário coletor, botões para Baixar Recibo em PDF, envio por WhatsApp/E-mail e botão de Desfazer Baixa / Reverter Pagamento com aviso operacional).
      • No celular, o botão de ação principal (mobilePaymentStep) fica posicionado no topo da fatura (logo abaixo dos botões do cabeçalho e antes do documento), permitindo alternar com um toque para o painel de cobrança/recibo sem obstrução visual ou barras flutuantes.

📑 5. Extrato Financeiro Consolidado do Cliente (/statement/:clientId)

Section titled “📑 5. Extrato Financeiro Consolidado do Cliente (/statement/:clientId)”

Para clientes recorrentes ou corporativos que solicitam histórico financeiro consolidado:

  • Página Pública de Extrato (src/pages/PublicClientStatement.tsx):
    • Resumo de faturamento: Total Faturado, Total Pago e Total em Aberto.
    • Tabela completa de faturas emitidas com datas e links individuais de pagamento.
    • Botão “Pay All Outstanding via Open Banking”: Permite a liquidação de todas as pendências em lote com 1 clique no app do banco.
  • Endpoint Backend (functions/api/public/statement.ts): Retorna os dados agregados e status em tempo real.
  • A leitura usa o mesmo transporte público limitado e abortável da fatura; erro de rede nunca é apresentado como extrato inexistente e pode ser tentado novamente.

💳 6. Pagamentos Online, Webhooks e Crédito

Section titled “💳 6. Pagamentos Online, Webhooks e Crédito”

Regra central: pagamento de gateway só é confirmado pelo webhook verificado; crédito interno exige débito atômico no livro. Até 2026-09-11 os hooks de Stripe, GoCardless e crédito marcavam PAID apenas no estado do navegador, com ID de transação inventado e sem chamar gateway algum; o webhook do GoCardless aceitava POST sem assinatura com o número (sequencial) da fatura.

  1. Início (POST /api/payments/checkout) — calcula no servidor o saldo pendente das faturas e a taxa repassada (checkoutRules.gatewaySurcharge, mesma fórmula de calculatePaymentSurcharge), grava uma linha em payment_checkouts (migração 0135) e devolve Stripe Checkout ou GoCardless Instant Bank Pay (ou cobrança no mandato quando o cliente tem gcMandateId). Equipe para qualquer fatura; cliente só as próprias; link /pay só a sua fatura, com rate limit. Várias faturas do mesmo cliente e entidade podem ir juntas (batchInvoiceIds da fatura virtual). No app nativo a página abre no navegador do sistema.
  2. Webhooks — /api/webhooks/stripe?entity=<id> e /api/webhooks/gocardless?entity=<id> conferem assinatura, entidade, checkout, provedor e valor pago. No GoCardless o pagamento é relido na API com a credencial da entidade. settleCheckout grava só o saldo ainda devido como transação, com a taxa uma vez, e liquida faturas/visitas em um batch D1 com token por execução; checkout desatualizado ou fatura alterada não inventa quitação e vai para reconciliação manual. A rota /api/webhooks/crezco ainda aceita apenas o formato legado interno com HMAC e valor explícito igual ao saldo; não é a integração oficial da Crezco nem deve ser registrada em produção. A API atual da Crezco usa assinatura por chave pública e eventos Payable com montante em unidades menores; homologação e teste com credenciais reais continuam pendentes. Até lá, Crezco é link manual.
  3. Crédito (POST /api/payments/wallet) — debita apenas o saldo ainda devido em wallet_transactions (o saldo é sempre recalculado desse livro), somente se o livro cobre o valor e na mesma transação que liquida as faturas. Histórico de transações ilegível bloqueia checkout e crédito, não vira cobrança do valor integral.
  4. Aviso de transferência (POST /api/payments/transfer-claim) — fatura para PENDING_REVIEW com transação PENDING, visitas para PENDING_CONFIRMATION, tudo ou nada; o gerente aprova. Antes o navegador salvava pelos endpoints atômicos (só equipe) e o aviso do cliente recebia 403.
  5. Credenciais por entidade — chave/token e segredo de webhook de cada gateway ficam em payment_configs_json e nunca chegam ao navegador (gatewaySecrets.ts; o boot devolve só …Set, incluindo crezcoWebhookSet). O upsert da entidade mescla em vez de sobrescrever: antes, salvar a entidade depois de digitar a chave apagava a chave. O gateway só é oferecido quando chave e segredo de webhook estão salvos (gatewayReady). Em Settings → Billing cada entidade mostra a URL de webhook para colar no painel do gateway. Cada chave salva tem Remove (com Keep para desfazer antes de salvar): o formulário envia a chave como null, e o upsert apaga só essa. Para parar de oferecer um gateway sem apagar as chaves, basta desligar Enable.
  6. Checkout do app — “Staff Collection” e “Manual Settlement” são só da equipe; “Force Settle” (COMPANY_ACCOUNT) agora registra o pagamento (antes não fazia nada).
  7. Reserva criada pelo cliente — clientBookingFields precifica no servidor e zera campos de pagamento/equipe; o payload do cliente era gravado como veio, inclusive paymentStatus: 'PAID'.

O escritório pode criar um pedido de pagamento no painel Deposit de uma visita aberta, avulsa, com preço e com depósito habilitado no serviço. deposit_percent sugere o percentual. A emissão usa POST /api/billing/deposit com ação ISSUE. A referência DEP- identifica o pedido, que pode ser enviado e pago pelo link. A equipe pode ser alocada enquanto o pagamento está pendente.

A fatura da visita traz o serviço inteiro e aplica o depósito pago como recebimento. Se o depósito exceder o total, a sobra vira crédito do cliente. Para empresas com VAT, a emissão do pedido e a visita precisam estar no mesmo trimestre de VAT. Remarcar para outro trimestre exige refazer o pedido.

Ao cancelar, um pedido em aberto é anulado. Se houver valor retido, a fatura de cancelamento (CAN-) aplica o depósito pago e cobra eventual saldo. Faturas de depósito legadas mantêm o tratamento original, com a linha “Less deposit paid” na fatura final.

  • Lógica de Lucro: src/features/billing/services/ProfitLogic.ts
  • Máquina de Estados da Fatura: src/features/billing/services/InvoiceStateLogic.ts
  • Serviço Open Banking UK: src/features/billing/services/OpenBankingService.ts
  • Página Pública de Pagamento: src/pages/PublicInvoicePay.tsx
  • Página Pública de Extrato Consolidado: src/pages/PublicClientStatement.tsx
  • Serviços da contabilidade: src/features/billing/services/XeroApiService.ts, QuickBooksApiService.ts
  • Endpoints Backend: functions/api/billing/, functions/api/public/invoice.ts, functions/api/public/statement.ts
  • Pagamentos online: functions/api/payments/ (checkout, wallet, transfer-claim), functions/api/webhooks/ (stripe, gocardless, crezco), functions/lib/payments/ (segredos, assinaturas, clientes dos gateways, settleCheckout)
  • Reserva do cliente: functions/api/atomic/clientBooking.ts
  • Painel Financeiro & Hub Contábil: src/pages/BillingHub.tsx / src/pages/AccountingHub.tsx

📊 Relatórios financeiros: o que entra em cada número

Section titled “📊 Relatórios financeiros: o que entra em cada número”

Todos os números financeiros contam o mesmo conjunto de trabalho realizado (isRealisedJob, em ProfitLogic.ts): visita concluída (DONE) ou cancelamento que ficou com taxa. Isso vale para lucro e prejuízo, HMRC, divisão por entidade fiscal e participação de cada serviço na receita. Antes, o lucro e prejuízo contava toda visita não cancelada, e o mês mostrava como receita e lucro as visitas da semana seguinte que ainda nem tinham acontecido.

  • A receber de clientes: todo trabalho realizado que não está PAID/REFUNDED. Uma visita concluída fica NONE até ser faturada; como antes só AWAITING/DRAFT/PENDING_CONFIRMATION contavam, ela aparecia como dinheiro em caixa (“Total Liquidity”).
  • Visão HMRC:
    • declara só visitas pagas (PAID/REFUNDED) por método rastreável (Stripe, GoCardless, transferência, crédito);
    • anular uma fatura deixa o actualPaymentMethod na visita, e por isso filtrar só pelo método declarava dinheiro nunca recebido;
    • a taxa de cancelamento paga entra na receita, sem custo de mão de obra;
    • a taxa de gateway entra quando a fatura está PAID;
    • o saldo mostrado já é o próprio valor declarado.
  • Divisão por entidade fiscal: soma só as taxas das faturas das visitas em tela; antes somava as faturas de todos os tempos. Cancelamentos não levam custo de mão de obra.
  • “Team Liabilities” na visão HMRC: usa o custo das visitas declaradas (declaredCost).
  • Painel de BI:
    • receita e lucro descontam reembolsos;
    • a margem é lucro ÷ receita da janela, e meses sem trabalho não puxam mais a média para baixo;
    • a nota de cada funcionária é a média só das visitas avaliadas.
  • Relatório de margem por cliente: desconta reembolsos e usa a entidade fiscal da própria visita (ou a do cliente, se a visita não tiver).
  • Carga da equipe: mede a semana atual de Londres (segunda a domingo) contra o limite britânico de 48 h semanais; antes somava todo o histórico.
  • Clientes em risco e pontuação de risco: não incluem quem já tem visita marcada, e a mensagem “sentimos sua falta” não é mais sugerida a esses clientes.

📈 Faturamento por empresa contra o limite (Relatórios → Faturamento)

Section titled “📈 Faturamento por empresa contra o limite (Relatórios → Faturamento)”

A aba Faturamento de Relatórios mostra, para cada empresa (pelo nome fantasia, fiscalEntityLabel), quanto ela faturou em cada um dos últimos 12 meses, o acumulado móvel de 12 meses e o limite dela, com aviso a partir de 80% (perto) e ao atingir o limite (acima). Serve para decidir por qual empresa faturar o próximo trabalho.

  • Uma vez por dia: o número não é recalculado a cada abertura. O cron de 5 minutos roda maybeRefreshTurnover (functions/api/common/turnoverSnapshot.ts) uma vez por dia de Londres: recalcula a partir das faturas e regrava fiscal_turnover_months inteira (uma linha por empresa e mês, zeros também, com computed_on). GET /api/billing/turnover só lê essa tabela (calcula uma vez apenas antes da primeira rodada), e a tela diz de que dia são os números. Uma fatura emitida hoje entra no número de amanhã.
  • Na escolha da empresa: o seletor de empresa do New visit (agendar e orçamento, InvoiceThroughPicker) e o do Edit task mostram, sob cada empresa, uma linha com a barra e “12 meses: £x de £limite (%)”, com o aviso de perto/acima (CompanyTurnoverLine, mesma regra e mesma consulta do relatório, useCompanyTurnover).
  • O que conta (só escritório): faturas emitidas (nem DRAFT nem VOID, nem pedido de depósito payment_request), sem VAT (invoiceNet: VAT destacado sai, VAT absorvido sai pela alíquota), no mês de Londres da data de emissão; menos notas de crédito (financial_documents CREDIT, pelo líquido, no mês em que foram emitidas) e reembolsos (transação COMPLETED negativa, pela fração líquida da fatura, no mês do reembolso). O reembolso de uma correção (FINANCIAL_CORRECTION_REFUND) sai da nota de crédito, que já é subtraída — não conta duas vezes. Uma fatura original substituída por outra empresa (fiscal_replaced_by) continua faturamento da empresa original; a nota de crédito da substituição tira o valor dela. É o número que o HMRC usa nos dois limites: faturamento tributável dos últimos 12 meses (registro no VAT) e faturamento sem VAT (Flat Rate Scheme). Lido no Worker, porque o boot só tem a janela operacional; vêm 23 meses para cada um dos 12 pontos ter o acumulado completo.
  • O limite (turnover_limit, 0277): Settings → a empresa → Limite de faturamento. Em branco vale a sugestão pelo tipo (turnoverLimitFor, src/shared/turnoverLimit.ts): £90.000 sem registro no VAT (limite de registro), £150.000 registrada no VAT (Flat Rate Scheme). Uma empresa registrada fora do Flat Rate Scheme pode pôr o valor que quiser acompanhar.
  • O gráfico: dois gráficos por empresa, nunca dois eixos num só — o acumulado de 12 meses contra a linha do limite e a de 80%, e as barras do faturado em cada mês; a tabela mês a mês fica em “Mês a mês”. O aviso diz quanto falta (ou passou), e o topo diz qual empresa tem mais folga.

DELETE /atomic/fiscalEntities responde 409 enquanto houver fatura, visita ou cliente ligado à entidade. O D1 não aplica chaves estrangeiras, e a exclusão deixava faturas órfãs, sem dados bancários na página de pagamento e sem regra de IVA. A tela desfaz a remoção e mostra o motivo que o servidor deu.

  • Os e-mails de fatura, lembrete, recibo e conciliação escapam (escapeHtml) nome do cliente, número da fatura, descrição dos itens e dados bancários. Nada digitado num cadastro vira HTML.
  • send-invoice recusa fatura anulada (409), para não pedir ao cliente dinheiro de uma cobrança cancelada.
  • O recibo leva a data da última transação concluída da fatura, e não o dia em que foi enviado ou reenviado.
  • Quitar uma fatura com crédito menor na conciliação de extrato continua permitido de propósito: o casamento automático só pré-marca valores exatos, e o resto exige um clique deliberado.

✅ Confirmações de dinheiro esperam o salvamento

Section titled “✅ Confirmações de dinheiro esperam o salvamento”
  • Aprovar ou rejeitar pagamento (verifyInvoicePayment), conferir o dinheiro coletado pela equipe (reconcileStaffBatch) e quitar direto esperam o servidor confirmar cada gravação antes de qualquer aviso. Isso inclui o aviso de “pagamento recebido” que vai para o cliente. Se o servidor recusar, a fatura e as visitas voltam ao estado anterior e o motivo aparece na tela.
  • Gerar fatura grava a fatura antes de marcar as visitas como “em rascunho”. Se o número já tiver sido usado por outro aparelho, as visitas não ficam presas a uma fatura inexistente.
  • Código removido: reconcileInvoice, que gravava a referência bancária no campo do ID do QuickBooks, e rejectPaymentConfirmation. Nenhuma tela usava as duas.
  • Correções automáticas da contabilidade: a de “divergência de IVA” usa a mesma regra da auditoria (vatTreatment). Quando a geração de fatura falha, o motivo aparece na tela.

Repreçar uma visita em fatura de rascunho usa BillingLogic.repriceDraftInvoice:

  • a linha da visita é achada pelo requestId. Pela posição, uma linha de taxa de remarcação deslocava as visitas seguintes, e o preço novo caía na linha errada;
  • cliente que absorve IVA não recebe IVA, a mesma regra da geração da fatura.

Forma de pagamento por empresa e baixa pela equipe (2026-09-24)

Section titled “Forma de pagamento por empresa e baixa pela equipe (2026-09-24)”

Cada empresa diz por onde recebe (paymentConfigs): transferência, cartão (Stripe) e débito (GoCardless) — gateway só quando tem chave e webhook — e, com allowsCashAndThirdPartyCollections (Madrid), dinheiro à funcionária e na conta da funcionária. companyPaymentMethods lista as rotas com o padrão primeiro (quem recebe pela equipe começa em dinheiro; as outras em transferência); effectivePaymentMethod escolhe o da visita: plannedPaymentMethod (coluna nova, migração 0158), senão o padrão do cliente se a empresa aceitar, senão o primeiro da empresa. No Editar tarefa o gestor escolhe a empresa e vê as formas dela, uma já marcada (trocar de empresa marca o padrão da nova); com transferência e mais de uma conta, escolhe em qual receber (plannedBankAccountId); o método é gravado na visita; com “Aplicar às próximas visitas” vira o defaultPaymentMethod do cliente e vai para as visitas abertas dele (futurePaymentMethodPatches); a série estendida copia o da última visita. Visitas pagas à equipe geram fatura de controle (migração 0165, functions/api/common/crewInvoice.ts): entram no pool como as outras, inclusive a visita que a equipe já recebeu (PAID em dinheiro/conta da funcionária, fora de fatura ativa), que continua PAID na fatura. A fatura diz ao cliente como pagar — dinheiro à equipe, ou na conta de uma pessoa da equipe (collector_employee_id + collector_snapshot_json: nome e dados bancários do cadastro dela); a página /pay mostra isso e não oferece cartão, débito nem a conta da empresa. É paga quando todas as visitas estiverem recebidas: na emissão, se já estavam, ou na baixa da funcionária (/api/field/collect), com uma transação “Collected by the crew”. Anular a fatura nunca desfaz a baixa. Quem recebe (conta da funcionária) é escolhido só entre a equipe da visita, na criação (fechamento do orçamento), no Editar tarefa (plannedCollectorId, recusado fora da equipe) e no rascunho da fatura (pessoa em todas as visitas dela; a escolha desce para as visitas). Sem escolha vale a líder. A entidade que recebe assim não tem Xero conectado, então essas faturas ficam como “not connected” na sincronização. A aba Admin dos detalhes da tarefa mostra “How it is paid” (empresa, forma, conta de destino, quem recebe) com Edit, que abre o Editar tarefa — só em visita aberta. Na encerrada (DONE/CANCELLED) o Editar tarefa nunca abre (reabriria dia, equipe, horas e preço): sem fatura, depósito nem pagamento, o cartão mostra Change (ClosedVisitBilling), que muda só empresa, forma, conta e quem recebe, com motivo e prévia pelo POST /visits/:id/admin (billing); empresa nova recalcula VAT e lucro sobre o mesmo preço e é recusada com VAT já confirmado (taxBasis) ou visita em holerite. Já faturada, o cartão manda à fatura (Alterar faturamento enquanto não paga, Corrigir depois) e quem recebeu muda pelo seletor “Received by”. Com mais de uma pessoa na visita, o cliente paga o valor cheio a uma delas ou o gestor pode dividir a distribuição em dinheiro entre os membros da equipe: quem recebeu dá baixa na aba Detalhes (CrewCollectionCard) pelo /api/field/collect (ou pelo Finalizar visita no escritório, onde se pode dividir o valor) e fica gravada como quem recebeu (financials.staffCollectedBy e financials.staffAdditionalCollectedBy; sem registro vale a líder, a primeira da equipe — crewCollectorId). Ao dar baixa no pagamento pelo cartão da equipe (CrewCollectionCard) ou no encerramento de turno (ShiftClosureWizard), o campo de valor recebido não vem pré-preenchido: a funcionária deve obrigatoriamente digitar o montante recebido para evitar confirmações automáticas sem conferência física do dinheiro. A interface exibe o valor esperado como referência e valida o montante digitado em tempo real: valor exato confirma a quitação da tarefa; valor menor indica saldo pendente; e valor maior destaca que a quantia excedente ficará como crédito para a próxima tarefa do cliente (o botão de gravação fica desabilitado até a digitação de um valor válido maior que zero). A folha desconta a parte exata de cada recebedora; quem não recebeu nada tem suas horas pagas normalmente. As outras veem “Recebido por ” (ou lista dividida com valores), o painel da tarefa no escritório também, o holerite marca “Cash Kept” para cada recebedora conforme sua parte e a conferência de dinheiro agrupa correspondentemente. Correção pelo gestor: no painel de cobrança da tarefa (AdminBillingControls), o seletor “Received by” troca quem recebeu pelo POST /api/billing/crew-collector (só gerente/admin, visita PAID em dinheiro/conta da funcionária, só alguém da visita, versão conferida e incrementada, log CREW_COLLECTOR_CHANGED). É recusado quando a visita já está num holerite APPROVED ou PAID (a correção vai na folha seguinte); os holerites DRAFT que contêm a visita são recalculados na hora (recalculateDraftEntry, common/payrollSettlementContext.ts) e, se algum falhar, o aviso pede para recalcular. Regras da baixa: só funcionária da visita, visita iniciada ou concluída, não paga, empresa que aceita e método da equipe; grava PAID, actual_payment_method, staffCollectedCash (o bruto, splitVat), staffCollectedBy, sobe a versão e registra CREW_COLLECTION no log. O boot da funcionária traz as empresas só com nome, VAT, ordem e as opções públicas de pagamento — sem dados bancários. O cartão mostra a quem vai receber (e, depois da baixa, a quem recebeu); não mostra quanto é dela nem quanto devolve (desde 2026-11-07: o acerto aparece só no total da semana e no holerite).

Imutabilidade de faturas e trava financeira de tarefas (2026-09-26)

Section titled “Imutabilidade de faturas e trava financeira de tarefas (2026-09-26)”
  • Snapshots Imutáveis no Momento da Geração: cliente, emissor e conta bancária são lidos novamente pelo servidor e gravados em client_snapshot_json, fiscal_snapshot_json e bank_account_snapshot_json. Alterações cadastrais posteriores não reescrevem o documento. bank_account_id nunca contém JSON.
  • Trava Financeira em Tarefas Faturadas: Visitas ou tarefas associadas a qualquer fatura ativa (inclusive DRAFT, SENT, OVERDUE — apenas faturas VOID liberam) têm seus dados financeiros estritamente bloqueados contra alterações (QuickEditTaskModal, ServiceFinancialsCard, useFinancialOperations). Ficam travados: valor do serviço, duração/esforço em horas, taxa horária negociada, empresa faturadora, método de pagamento planejado e conta bancária de destino. A interface exibe aviso claro de valor congelado (taskEdit.priceLocked).
  • Fluxo de Retificação pelo Gestor: Caso seja necessário alterar dados financeiros ou operacionais de uma tarefa faturada, o gestor deve anular a fatura existente via Void & Release Tasks. Essa ação desassocia as tarefas e destrava os campos financeiros para edição livre e subsequente refaturamento com novos cálculos.

Numeração independente por empresa (2026-09-26)

Section titled “Numeração independente por empresa (2026-09-26)”
  • Numeração Sequencial e Independente por Entidade Fiscal: cada entidade guarda um prefixo alfanumérico único (invoicePrefix; DEP é reservado). POST /atomic/invoices ignora o número provisório do navegador, lê toda a série histórica do ano de Londres e reserva <PREFIX>-<ANO>-<SEQUÊNCIA>; a constraint única e a verificação pós-insert fecham corridas entre dispositivos. Faturas históricas mantêm a numeração.

  • Sincronização configurável com o Xero (Apenas envio vs Bidirecional): O painel do Xero em Configurações → Entidades fiscais → Contabilidade permite escolher o comportamento de sincronização de cada empresa:

    • Apenas envio (Prime Crown → Xero, padrão): as faturas emitidas e baixas manuais locais são enviadas ao Xero; baixas feitas diretamente no Xero permanecem como observações para conferência manual, sem alterar dinheiro ou tarefas automaticamente.
    • Bidirecional (baixa automática do Xero): quando ativado, conciliações ou pagamentos registrados no Xero (recebidos via Webhook do Xero ou detectados ao sincronizar a fatura via “Sync now” / retry) são automaticamente validados contra a conta bancária e as visitas concluídas da fatura. Se a prova coincidir, a baixa é replicada na fatura local marcando-a como PAGA (PAID) e quitando as visitas vinculadas, com registro auditado do recebimento e sem duplicidade de recibos. Divergências de conta bancária ou dados incompletos permanecem bloqueados para revisão manual de segurança.
  • Prime Crown como fonte da verdade na emissão: a contabilidade (Xero syncInvoiceToXero ou QuickBooks syncInvoiceToQuickBooks) recebe o que o sistema emitiu — número sequencial, datas, linhas e VAT saem daqui.

  • Separação do Pool de Faturamento por Cliente e Empresa: No Pool de Faturamento (BillingPoolService.groupRequestsByClient), as tarefas pendentes de cobrança são agrupadas por Cliente + Entidade Fiscal. Se um cliente possui tarefas para empresas distintas (ou tarefas liberadas após o cancelamento de uma fatura de empresa incorreta), elas são exibidas em cartões separados com badges coloridos de cada entidade. Isso elimina conflitos de múltipla entidade (hasMultiEntityConflict) e assegura que a automação em lote (runAutomationEngine) gere faturas separadas e juridicamente corretas para cada empresa. O gestor pode auditar/editar uma tarefa devolvida ao pool para ajustar sua entidade fiscal e recalcular o VAT instantaneamente antes da reemissão.

  • Rascunho não é fatura (numeração na emissão): o rascunho guarda DRAFT-<id> em invoice_number e aparece como “Draft”, sem número (src/shared/invoiceNumber.ts). O número da série (<PREFIX>-<ANO_LONDRES>-<N>) é reservado quando a fatura é emitida — sai de DRAFT para qualquer status menos VOID (DISPATCH em /billing/invoice-operation ou a gravação em /atomic/invoices) — na mesma escrita, e a fatura passa a ter data de emissão de hoje, com o mesmo prazo que o rascunho dava (invoiceIssueFor, functions/api/common/invoiceIssue.ts). Rascunho apagado ou anulado não deixa buraco. Enquanto é rascunho: /pay/<id> responde 404, o e-mail é recusado (o app emite antes de enviar), o cliente não o recebe no boot nem no GET /atomic/invoices, e a prévia não mostra link nem QR (“QR on issue”). No rascunho, How the client pays também escolhe a conta de destino da transferência quando a empresa tem mais de uma (como a lista da equipe em conta da funcionária), e o “Pay into” acima do link manual só aparece na fatura emitida. Na tela da fatura o rascunho mostra How the client pays (as formas faturáveis da empresa: transferência, cartão, débito — PATCH /atomic/invoices plannedPaymentMethod, só em DRAFT), a prévia muda na hora, e Issue invoice emite e fecha a tela. Em dinheiro à equipe ou conta da funcionária, a tela da fatura não mostra “Pay into”, o link manual nem o Reconciliation Quick Check (não se aplicam). A forma escolhida no rascunho muda só aquela fatura e as visitas dela; para o cliente e as próximas visitas, use Change billing com o checkbox. Registrar pagamento (Finalise / Manual settlement) só aparece na fatura emitida, e a lista mostra só as rotas que a empresa aceita (Staff Collection só com allowsCashAndThirdPartyCollections). Registrar recebimento abre uma única tela (ManualSettlementModal); somente a mudança de billing usa Continue e o resumo da reemissão com “Also for next visits”: como entrou (transferência, cartão, débito, outro; dinheiro e conta da funcionária só onde a empresa aceita), dia recebido (não futuro), valor (menor que o saldo = pagamento parcial, a fatura continua aberta), referência e motivo (obrigatório, gravado na transação). Quita a fatura e marca as visitas PAID com o método quando o total é coberto (InvoiceStateLogic.prepareManualSettlement). O boot monta a fatura pelas colunas dela (items_json, transactions_json: horas por linha, status real de cada pagamento) e só recorre a invoice_items/invoice_payments quando elas estão vazias (enrichInvoice) — trocar pelas tabelas mostrava uma reivindicação pendente como paga e tirava as horas. O PATCH /atomic/invoices (conta de destino, link manual, forma e quem recebe no rascunho) lê um corpo JSON e o app o chama por CloudClient.patchJson — o CloudClient.patch manda query string sem corpo (é o do lead) e dava 500 aqui. Um recarregamento em segundo plano (volta ao app, rede, polling) não desfaz uma fatura emitida/paga enquanto ele estava em voo (keepInvoicesWrittenDuringRefresh). A página pública /pay (e o extrato /statement) rola dentro de si mesma — o shell do app não rola html/body —, tem fundo claro e um botão Save PDF que baixa o PDF da própria invoice (o InvoiceDocument do app, desenhado fora da tela a partir do payload público e capturado como no escritório — invoicePdf.ts, mesmo nome de arquivo e largura), nunca a página; no navegador ele baixa direto (download em PdfExportService), sem a folha de compartilhar que os PDFs do escritório abrem — no app nativo, sem download, continua compartilhando; na fatura paga o mesmo botão fica no quadro de pagamento confirmado. Sem o endereço do cliente (o payload público não o traz). A /api/public/invoice envia para isso o endereço, o HMRC e a taxa de VAT do emissor (só empresa registrada) e, numa substituição, o número da original (replacement). O cabeçalho da página diz “Invoice” para todas as empresas. A impressão do navegador continua possível (@media print em index.css solta a altura fixa). A fatura mostra horas e valor por hora de cada visita (valor ÷ horas) e não permite tirar uma visita; para mudar o conteúdo, descarte o rascunho. No celular a etapa de pagamento fica numa barra fixa embaixo da fatura (“How the client pays” no rascunho, “Record payment” no escritório, “Pay now” para o cliente), e no rascunho a conta de destino e o link manual ficam nessa etapa, não acima do documento.

  • Empresa sem número HMRC = não registrada (isRegisteredCompany; VAT só com o número HMRC preenchido — o formulário desliga e o POST /atomic/fiscalEntities recusa): o documento não leva identidade legal — no app, no PDF, na página /pay e no e-mail sai como Invoice, sem o nome da empresa no cabeçalho, sem o bloco Legal Issuer e sem rodapé com empresa/HMRC/VAT; o PDF segue o formato comum INVOICE_<n>.pdf. Não vai para o QuickBooks (EXCLUDED, “Not a registered company”) e o que ela recebe fica fora da visão HMRC dos relatórios (FiscalAuditService.calculateHMRCStats).

  • Extrato do cliente (/statement) segue as mesmas regras: só documentos emitidos (sem rascunho nem anulado, que antes aparecia como em aberto com “Pay” e contava no faturado); cada linha diz Invoice, a empresa (só se registrada) e se é pago à equipe (e a quem); “pagar tudo de uma vez” e a conta só aparecem quando todo o valor em aberto vai para a conta de uma mesma empresa (os pagos à equipe ficam fora); nome/VAT no rodapé e no cabeçalho só com uma empresa, registrada.

  • Pago à equipe (Paid to the crew): dinheiro e conta da funcionária são uma opção só, em toda escolha de forma (Editar tarefa, fechamento do orçamento, rascunho da fatura, Change billing, Manual settlement, Finish visit — CrewPaymentChoice): primeiro como — dinheiro ou transferência para a conta de alguém —, depois quem recebe (plannedCollectorId, nas duas rotas). Em transferência, a equipe da visita aparece com quem não tem dados bancários desabilitado, mais a pílula Others, que abre todas as funcionárias ativas com dados bancários no cadastro, mesmo fora da visita (useBankCleaners); escolhida uma delas, o aviso diz que o valor sai do holerite semanal dela (2026-10-06). Quem recebe é configurado na tarefa: numa equipe de uma pessoa, ela; com duas ou mais, ninguém vem marcado e o Edit task só salva depois da escolha (nunca a primeira da equipe por padrão, 2026-11-09), e o escopo “esta e as próximas” leva a escolha às visitas seguintes da série em aberto e não faturadas, como a forma de pagamento (futureCollectorPatches; só nas que têm a pessoa na equipe, ou quando ela é de fora da equipe). A fatura e a página /pay dizem a quem pagar em dinheiro; numa visita já recebida, a fatura nomeia quem recebeu (staffCollectedBy). Gerente também recebe dinheiro (2026-09-29): além da equipe, a lista mostra os gerentes ativos (marcados “Manager”, useCashManagers), só em dinheiro — escolhido um gerente, a transferência fica travada. Vale em toda escolha (Editar tarefa, fechamento do orçamento, rascunho, Change billing, Manual settlement, Finish visit e a correção “Received by”). O servidor aceita alguém fora da equipe só se for gerente ativo em dinheiro ou funcionária ativa (role EMPLOYEE) com dados bancários em transferência para a conta dela (collectorRefusal em src/shared/crewCollector.ts, collectorRefusalFor/collectorStanding em common/crewInvoice.ts: /api/field/collect pelo escritório, /api/billing/crew-collector, atomic/requests, atomic/invoices, manual-settle, invoice-reissue). crewCollectorId passa a valer quem foi registrado, senão quem foi nomeado, mesmo fora da equipe (a gravação já validou; tirar da equipe uma funcionária nomeada limpa o nome), senão a líder. O valor desconta no holerite de quem recebeu, gerente ou funcionária de fora da visita (ver Payroll).

  • Change billing (antes “Wrong company”): também no rascunho (Review & send), antes de emitir: sem número e sem Xero, o rascunho é descartado e refeito na empresa certa. Na fatura emitida, sem pagamento registrado (transações só FAILED), sem visita com depósito ou paga. A janela escolhe a empresa (a da fatura vem marcada; pode ser a mesma, para mudar só a forma, a conta ou quem recebe — uma mudança que não muda nada é recusada), como o cliente paga, em transferência a conta de destino quando a empresa tem mais de uma (plannedBankAccountId, validado na empresa nova) e, em conta da funcionária, quem recebe (equipe de todas as visitas). Toda lista de contas (How the client pays, Change billing, Editar tarefa) mostra o titular (accountName, senão o nome da empresa). Depois de salvar, a tela continua aberta no rascunho novo, pronto para emitir. Um segundo passo confirma, com o checkbox Also for ’s next visits (já marcado): marcado, o cadastro do cliente fica com a empresa e a forma (fiscalEntityId, defaultPaymentMethod) e as próximas visitas abertas dele seguem (futureFiscalPatches + futurePaymentMethodPatches, como no Editar tarefa; quem recebe só nas visitas cuja equipe tem a pessoa); desmarcado, muda só esta fatura. POST /api/billing/invoice-reissue anula a fatura e move as visitas (empresa, forma, quem recebe, VAT recalculado pela empresa nova, lucro por jobProfit, pagamento NONE, versão +1); o app cria o rascunho na empresa nova. A numeração nunca é reciclada (paridade estrita com o Xero e regras fiscais do HMRC): uma vez emitida, a fatura retém permanentemente o seu número com status VOID (não vira VOID-<id>), o registro de entrega fica gravado (delivered_at), o cancelamento sincroniza como VOIDED nos livros fiscais (Xero e QuickBooks) e a nova fatura reemitida sempre consome o próximo número sequencial da empresa (nextInvoiceNumber).

  • Draft all invoices (antes “Smart Batching”): cria um rascunho por cliente + empresa (o Draft invoice, antes “Generate Statement”, cria um só com as visitas marcadas) com todas as visitas da fila no período e na busca mostrados (runAutomationEngine). Pede confirmação com a quantidade de rascunhos e fica desligado com a fila vazia; nada vai ao cliente até ser enviado de Rascunhos.

  • Valores do pool com VAT: cada linha, o total do cartão e o “Selection Total” mostram o que o cliente paga (BillingPoolService.visitGross, sobre splitVat): price é líquido, então o VAT entra por cima (£160 → £192); cliente com VAT absorvido e entidade sem VAT mostram o próprio preço. Antes a tela somava price e mostrava o valor sem VAT, embora a fatura saísse com ele.

  • Card de cobrança no Dashboard (2026-09-28): substitui o cartão de faturamento (trabalho realizado). Tudo sem VAT — o VAT aparece só na Billing (invoiceNet = total − VAT, com o VAT absorvido saindo junto; visitas por splitVatNetOfRefunds). Funil em 4 números, cada um abrindo sua aba: A faturar (o Pool pela regra da Billing, com a visita mais antiga), Rascunhos, Aguardando pagamento (SENT/PENDING_REVIEW/OVERDUE, com o atrasado pela regra do Service History e os comprovantes a aprovar) e Recebido, 7 dias — dinheiro que entrou de verdade, lido no servidor de todos os pagamentos COMPLETED de faturas não anuladas (GET /api/billing/received, 14 dias de Londres por empresa, cada pagamento sem a sua parte de VAT, reembolso subtrai), comparado com a semana anterior. Abaixo: idade do que está em aberto (0–7, 8–14, 15–30, 30+ dias desde a emissão), com a equipe (a regra do Cash check, awaitingCrewCheck, agora também a do número do Dashboard), os 5 maiores devedores, faturas emitidas e nunca entregues (deliveredAt/sentAt vazios) e o agendado dos próximos 7 dias. Seletor por empresa quando há mais de uma. Regra em src/features/billing/services/billingPipeline.ts; sem IA.

  • Barra Unificada de Faturamento e Visualização em Tabela (2026-10-03): O Billing Hub adota a barra canônica HubToolbar unindo em linha os chips de KPI financeiros (CFKpiCard variant="chip" para A Faturar, Rascunhos, Aguardando e Anuladas com totais monetários e contagem, com feedback tátil e alternância de aba), alternância de modo de exibição (Cards vs Tabela InvoiceTable, persistido em ui_preferences via billing_display_mode) e pesquisa compacta unificada de clientes e equipe (VisitPeopleSearchField). O Pool de faturamento agora exibe 100% dos trabalhos concluídos e não faturados sem corte de período artificial, eliminando risco de pendências esquecidas. A aba Aguardando conta com sub-filtros rápidos com contadores (Todas, No Prazo, Vencidas e Em Revisão), e a tabela de faturas oferece seleção múltipla com barra flutuante de ações em massa (cópia de links de pagamento e anulação/descarte em lote com confirmação).

  • Padronização e Auditoria de Cash Check e Integridade (2026-10-03): As abas Cash check e Integrity foram padronizadas com o design system canônico do Billing Hub.

    • Cash check (StaffReconciliationView): Cabeçalho moderno com badge ShieldCheck, chips com valor total retido pela equipe e quantidade de serviços. Filtro de pesquisa instantâneo por nome de profissional ou número da tarefa. Inclusão estrita tanto de pagamentos em dinheiro (CASH) quanto transferências para conta de funcionária (EMPLOYEE_ACCOUNT) pendentes de confirmação (PENDING_CONFIRMATION). Cada serviço traz atalho de inspeção direta (onViewTask abrindo TaskDetailsModal) com badge do método e data formatada no fuso de Londres. Barra flutuante de ações em lote para confirmação rápida com contagem de itens selecionados e somatório financeiro em tempo real.
    • Integrity (IntegrityAlertsView): Cabeçalho unificado com status chip dinâmico (verde “Sem pendências” / âmbar “N discrepâncias”). Tratamento com estados de skeleton loading e erro resiliente. Atalhos diretos de auditoria (onViewTask) em cada alerta com vínculo a visita para inspeção imediata no modal de detalhes da tarefa, mantendo os botões de autocorreção em um toque (useIntegrityRepair).
  • Especialização de Cards e Tabelas por Etapa (2026-10-03): Cada etapa do fluxo financeiro (Pool, Drafts e Awaiting) possui particularidades operacionais e jurídicas refletidas tanto na exibição em cartões quanto em tabela:

    • Pool (BillingPoolGroup e BillingPoolTableView): Nos cartões, a seleção por checkbox foi totalmente desacoplada do clique de expansão/recolhimento do grupo, evitando seleções acidentais. A listagem interna de cada cliente agora estampa o tipo de serviço executado, profissional/equipe alocada e método de pagamento planejado. No modo tabela, o Pool conta com BillingPoolTableView dedicada para auditoria densa de todas as visitas pendentes (data/hora Londres, tarefa, cliente, entidade fiscal, serviço, cleaner, rota de pagamento, duração em horas e bruto com VAT), com barra flutuante de faturamento em lote das visitas selecionadas.
    • Drafts (InvoiceRowCard e InvoiceTable): Visual moderno e neutro em cartão branco elevado, identificando a empresa emissora com badge colorido (FiscalEntity) e o método de pagamento definido. A tabela de rascunhos exibe essas mesmas colunas, omite a coluna redundante de número da fatura (já que rascunhos ainda não possuem numeração oficial antes da emissão) e suprime o botão de cópia de link na barra flutuante, eliminando o risco de links 404 enviados a clientes antes da emissão oficial.
    • Awaiting / Outstanding (InvoiceRowCard e InvoiceTable): Faturas vencidas (OVERDUE) são destacadas com borda e badge de alerta em rose calculando os dias de atraso (ops.overdueDebt.daysOverdue), distinguindo-se das faturas no prazo (SENT). Suporte nativo a pagamentos parciais com destaque para o saldo devedor restante (balanceDue) e total original tachado. Inclusão de atalho direto de cópia rápida do link de pagamento (/pay/:id) tanto no rodapé do card quanto na coluna de ações da tabela, além de indicador de entrega (deliveredAt).
  • Refinamentos Operacionais do Billing Hub (2026-10-03):

    • Deduplicação Visual em Aguardando Revisão (PENDING_REVIEW): No modo cartões, o sub-filtro “Em Revisão” renderiza exclusivamente a seção dedicada de aprovação bancária (PaymentClaimsSection) com os cards de ação (aprovar/rejeitar), eliminando duplicações visuais com os cards comuns de fatura. No modo tabela, a visualização é 100% tabular e exibe as faturas pendentes de revisão diretamente nas linhas da tabela.
    • Exportação CSV com Suporte a Excel: Tanto na tabela do Pool (BillingPoolTableView) quanto na tabela de faturas (InvoiceTable), há botões de exportação CSV com cabeçalhos normalizados e prefixo BOM UTF-8 (\uFEFF) para compatibilidade direta com o Excel no cabeçalho da tabela. A barra flutuante foi mantida focada exclusivamente em ações operacionais de avanço de estágio, cancelamento e link de pagamento.
  • Remoção da Barra Lateral Executiva e Barra de Ações Flutuante Mobile-Safe (2026-10-03): O painel lateral executivo do Pool foi removido em prol de layout unificado em largura total (space-y-8), alinhando-se com as demais abas. A geração de faturas e contagem de itens passam a ser controladas por barra flutuante contextual de lote, que se revela assim que o primeiro checkbox é marcado (selectedIds.size > 0), tanto no modo cartões quanto em tabela. A seleção total de todas as visitas do pool é realizada no cabeçalho do modo tabela. No mobile, todas as barras flutuantes (BillingPoolView, BillingPoolTableView, InvoiceTable e StaffReconciliationView) utilizam elevação dinâmica (bottom-[calc(var(--app-bottomnav-height,5rem)+var(--native-bottom-lift,0px)+1rem)] lg:bottom-6 z-[5001] via classe utilitária .floating-action-bar), garantindo que os botões de ação nunca fiquem escondidos atrás da barra inferior de navegação (BottomNav).

  • Particularidades das Barras Flutuantes e Avanço de Estágio em Lote com 1 Clique (2026-10-03): A barra flutuante adapta suas ações e contexto operacional ao estágio atual do faturamento, permitindo selecionar múltiplos itens e avançá-los para a próxima etapa simultaneamente:

    • Pool (A Faturar): Selecionar múltiplas visitas (mesmo pertencentes a clientes e entidades fiscais diferentes) permite avançar todas para Rascunhos de uma só vez. O botão exibe a contagem de faturas que serão criadas (Criar N rascunhos), agrupando automaticamente as visitas por clientId::fiscalEntityId e gerando as faturas em lote sequencial no servidor sem bloqueios de conflito de entidade.
    • Drafts (Rascunhos): Selecionar múltiplos rascunhos (em cartões ou tabela) exibe o botão primário de avanço de estágio Emitir N faturas. A emissão reserva a numeração oficial no servidor, move o status para SENT e transiciona as tarefas para AWAITING, movendo o gestor automaticamente para a aba Aguardando. Ação secundária inclui descarte de rascunhos em lote (billing.row.discard).
    • Awaiting / Outstanding (Aguardando Pagamento):
      • Para faturas em análise bancária (PENDING_REVIEW): A barra flutuante exibe a ação direta de avanço de estágio Aprovar N comprovantes (verifyInvoicePayment com ação 'APPROVE'), quitando as faturas e tarefas para PAID de uma só vez com confirmação auditada.
    • Cash Check (Conferência de Caixa): Centraliza o controle de todas as tarefas com recebimento em dinheiro (CASH) ou transferências na conta de funcionárias (EMPLOYEE_ACCOUNT). Diferencia visualmente as tarefas com baixa dada pela equipe (PAID / PENDING_CONFIRMATION, retido com a funcionária) daquelas com baixa pendente (AWAITING, aguardando quitação/baixa). Oferece filtros rápidos via StateFilterPills (Todas, Aguardando baixa, Com a equipe), KPIs no cabeçalho e ações pontuais para o gestor: Cobrar (gera lembrete com dados bancários da funcionária e abre WhatsApp), Mudar forma (abre QuickEditTaskModal para alterar o meio de pagamento) e Dar baixa (quitação atômica direta e auditada). Permite também selecionar múltiplos recebimentos e avançá-los em lote (reconcileStaffBatch) na barra flutuante.
  • Padronização de Skeleton Loading e Telas em Branco (Card role="status"): Todas as visões do Billing Hub (Pool de faturamento, Rascunhos, Aguardando pagamento, Anuladas, Conferência de caixa / Cash Check e Integridade) compartilham o mesmo padrão canônico visual de carregamento e listas sem registros:

    • Carregamento: Enquanto os dados estão sendo obtidos (isLoading), exibe-se esqueleto uniforme de 3 linhas via <DataShimmer variant="LIST" count={3} />, eliminando pulsações customizadas ou saltos visuais de layout.
    • Lista Vazia: Quando não há registros a exibir e a busca não está carregando, renderiza-se o cartão estilizado de fundo branco padronizado com bordas arredondadas e sombras canônicas (<Card role="status" padding="none"><CFEmptyState ... /></Card>), mantendo alinhamento estrito com os módulos de Key Custody e Supply Hub.
  • Compartilhamento via WhatsApp, Atalhos e Usabilidade de Pagamento (2026-10-03):

    • WhatsApp Direto (1 Toque): Botão verde com ícone do WhatsApp em InvoiceRowCard e InvoiceTable, abrindo link wa.me com o telefone do cliente normalizado (+44) e mensagem pré-formatada amigável (“Olá [Nome], segue o link da fatura [Número] no valor de [Valor]: [Link]”).
    • Cópia de Mensagens em Lote: Na barra flutuante de ações em lote, o botão WhatsApp copia todas as mensagens formatadas de uma vez para envio rápido.
    • Atalhos de Teclado no Desktop: No Billing Hub, pressionar / foca instantaneamente na barra de busca de clientes/funcionários, e Esc limpa as faturas selecionadas.
    • QR Code e Cópia Completa no /pay/<code>: Clientes que abrem a fatura no computador contam com botão para exibir QR Code escaneável com o celular (para pagar via Apple Pay, Google Pay ou app bancário) e botão de 1 toque para copiar todos os dados bancários (Beneficiário, Sort Code, Conta, Referência e Valor) de uma só vez. Faturas pagas exibem banner de confirmação e o botão Save PDF fica no topo à esquerda (sem duplicação no bloco).
  • Aba de Faturas Pagas (PAID) e Desfazer Baixa Acidental (2026-10-04):

    • O Billing Hub passa a contar com a aba primária Pagas (PAID), posicionada logo após Aguardando, acompanhada do chip de KPI correspondente no BillingToolbar com valor monetário e contagem de faturas quitadas na janela operacional (14 dias ou período civil ativo).
    • Desfazer baixa acidental (Reversão de pagamento): Caso um gestor dê baixa em uma fatura por engano ou marque erroneamente como paga, é possível desfazer a baixa tanto individualmente (no card InvoiceRowCard, na linha da tabela InvoiceTable ou no cabeçalho/banner informativo do InvoicePreviewModal) quanto em lote (barra flutuante de ações com botão Desfazer baixa de N faturas).
    • Integridade da reversão: A reversão transiciona a fatura de PAID de volta para SENT (ou OVERDUE se a data de vencimento já tiver expirado), marca as transações de pagamento associadas como FAILED com nota de auditoria preservando histórico, reverte o paymentStatus das visitas ligadas para PAYMENT_STATUS.AWAITING e limpa actualPaymentMethod, atualizando os registros de forma atômica no banco de dados e registrando PAYMENT_REVERTED no log de atividades financeiras.
    • Regra de transição no backend (canTransitionInvoice): PAID deixa de ser terminal absoluto e pode transicionar para SENT, OVERDUE ou PENDING_REVIEW mediante ação deliberada de reversão, enquanto transições para DRAFT ou VOID continuam estritamente bloqueadas para assegurar a integridade fiscal.
  • Baixa Automática Direta em PAID ao Finalizar Tarefa com Pagamento Confirmado (2026-10-04):

    • Quando uma tarefa tem seu pagamento confirmado ao ser concluída (status === 'DONE' e paymentStatus === 'PAID' — seja por dinheiro à equipe, transferência para conta da funcionária, ou pagamento antecipado), ela ganha automaticamente uma fatura oficial com numeração sequencial definitiva da empresa (nextInvoiceNumber, <PREFIX>-<ANO>-<SEQUÊNCIA>), transação quitada (status = 'PAID'), itens e deduções calculados e sincronização contábil (queueAccountingSync).
    • O processo é totalmente automático e pula as etapas manuais do Pool, Rascunhos e Aguardando Pagamento, inserindo a fatura liquidada diretamente no grupo Pagas (PAID).
    • Caso a tarefa já possuísse um rascunho anterior aberto, este é liquidado diretamente para PAID na mesma transação atômica em vez de duplicar a fatura.
    • No Pool de Faturamento (BillingPoolService.getBillableRequests), qualquer tarefa cujo paymentStatus seja PAID é imediatamente excluída da listagem, evitando que tarefas já pagas à equipe ou recebidas permaneçam na fila de faturamento pendente.
  • Fatura Automática Direta em Aguardando (SENT) para Pagamentos na Conta da Funcionária (EMPLOYEE_ACCOUNT, 2026-10-04):

    • Quando uma tarefa cujo pagamento é previsto para a conta da funcionária (EMPLOYEE_ACCOUNT) é finalizada (status === 'DONE') e ainda não foi quitada (paymentStatus !== 'PAID'), o sistema gera automaticamente a fatura oficial emitida com status SENT (Aguardando Pagamento).
    • A fatura consome o número sequencial definitivo da empresa (nextInvoiceNumber), anexa os dados bancários e nome da funcionária encarregada (collector_employee_id e collector_snapshot_json), define vencimento em 7 dias e popula as linhas de serviço.
    • A visita é atualizada para paymentStatus = 'AWAITING' e actualPaymentMethod = 'EMPLOYEE_ACCOUNT'.
    • Caso a visita já estivesse em um rascunho (DRAFT), este é emitido imediatamente para SENT com a numeração oficial.
    • No rodapé da fatura (InvoiceDocument), página de pagamento (PublicInvoicePay), e-mail e WhatsApp, os dados bancários da funcionária (bank_details em JSON ou texto) são formatados com formatBankDetails (Account name, Sort code, Account), sem vazar JSON bruto, e o título exibe Pay into <Nome>’s account.

Nova fatura com visitas agendadas (pré-faturamento, 2026-10-28)

Section titled “Nova fatura com visitas agendadas (pré-faturamento, 2026-10-28)”

Billing → More → New invoice emite uma fatura numerada para um cliente e uma empresa com todas as visitas até um dia (padrão: o último dia do mês em Londres): as finalizadas ainda não faturadas, as que estão em draft e as que ainda vão acontecer. Tudo vem marcado; o escritório desmarca o que não quer. Só entram visitas pagas por transferência ou gateway — dinheiro e conta da cleaner seguem o fluxo da equipe.

  • O rascunho é criado por POST /atomic/invoices com prebill: true e agrupado por /billing/draft-selection com prebill (cliente, empresa, débitos marcados); a orquestração fica em src/application/issueNewInvoice.ts.
  • Linhas de visitas ainda não feitas levam scheduled: true (src/shared/scheduledLine.ts), um retrato do momento da emissão: aparecem como Scheduled no documento/PDF, na página de pagamento, no e-mail e, como “ (scheduled)“, no Xero/QuickBooks.
  • A fatura emitida não muda. Após concluir ou cancelar a visita, a correção financeira também aceita a linha originalmente marcada Scheduled: usa a base fiscal histórica, contabiliza créditos anteriores e gera documentos separados, preservando a fatura e os recibos. Se a visita cancelar ou sair mais barata, a diferença vira nota de crédito (financial_documents CREDIT, prebilledChargeStatements em visitDraftPropagation); se sair mais cara, vira um débito pendente em invoice_adjustments (migração 0239). A diferença é medida contra o que já foi cobrado da visita (linhas − créditos + débitos).
  • Na próxima New invoice daquele cliente e empresa os débitos e créditos pendentes vêm marcados (podem ser desmarcados); o débito vira linha “Adjustment — serviço (T-…)” e o crédito é aplicado depois da emissão. O pool só mostra o aviso “Pending adjustments”. Um crédito pré-faturado nunca volta para a fatura de origem, e essa fatura não pode ser anulada depois de gerar crédito ou ajuste.
  • A fatura automática (pagamento confirmado, cliente com autoBillingEnabled, taxa de cancelamento) não mexe numa fatura que já contém a visita: não liquida a fatura mensal por uma visita paga nem reenvia avisos.
  • A correção de preço em /visits/:id/financial recusa visita pré-faturada; o preço final vem do Finish visit.
  • Uma série que muda de ritmo não apaga visitas que estão em qualquer fatura viva (conferido também no próprio delete), e o admin não exclui uma visita que está numa fatura.
  • O valor de uma visita pré-faturada é preço + taxa de remarcação: uma taxa nova vira ajuste; a já cobrada nunca vira crédito.
  • Enquanto a fatura mensal está em aberto, a visita não é marcada como paga sozinha: o pagamento é registrado na fatura.
  • O número da nota de crédito (CN-…) é tirado dentro da própria gravação, então dois créditos simultâneos não disputam o mesmo número.
  • Faturas montadas pelo agrupamento de drafts (pool “Issue grouped/individually” e New invoice) recebem um id curto de 8 caracteres, derivado da operação (draftSelectionInvoiceId), então o link /pay/<código> sai curto; faturas antigas com id DSEL-… continuam abrindo pelo id longo.

Integração Xero — Modos de sincronização e reconciliação inbound (2026-10-31)

Section titled “Integração Xero — Modos de sincronização e reconciliação inbound (2026-10-31)”
  • Modo de sincronização configurável por entidade fiscal: O painel fiscal em Configurações permite alternar entre Apenas envio (Prime Crown → Xero) e Bidirecional (baixa automática do Xero). No modo bidirecional, pagamentos registrados ou reconciliados no Xero provocam a baixa automática da fatura correspondente no Prime Crown (com status PAID, transação registrada e visitas quitadas), seja via webhooks em segundo plano ou sob demanda ao sincronizar a fatura.

  • Resiliência e transparência nos eventos inbound (Xero → Prime Crown):

    • O leitor do adaptador de eventos inbound tolera faturas externas sem notas de crédito aplicadas (AmountCredited indefinido/omitido pelo Xero) e vencimento não preenchido, evitando erros prematuros de leitura.
    • Erros operacionais durante a observação do evento (como limitação de taxa Xero 429 ou divergências de dados) preservam a mensagem sanitizada real em vez da mensagem genérica opaca anterior (Unable to verify external accounting data), sendo registrados no log seguro e visíveis no histórico da fatura.
    • Na modal de detalhes de sincronização da fatura (XeroSyncDetailsModal), cada evento inbound com estado FAILED ou PENDING possui seu próprio botão de retentativa rápida (“Retry”), e o botão principal “Sync now” reexecuta automaticamente a leitura de todos os eventos inbound pendentes ou que falharam por limites temporários de requisição.
  • Preservação de histórico na troca de provedor contábil (Xero / QuickBooks): Quando uma entidade fiscal é desconectada de um provedor (por exemplo, Xero) para conectar outro (QuickBooks com data de corte), as faturas históricas que já haviam sido sincronizadas com sucesso no provedor anterior continuam exibindo seu respectivo indicador de sincronização (Xero · Synced) nas listagens e detalhes, assegurando a rastreabilidade fiscal sem substituição indevida por traço ou status não conectado. Na modal de detalhes (XeroSyncDetailsModal), caso o provedor da fatura esteja desconectado, o botão “Sync now” e as retentativas inbound ficam desabilitados, exibindo o selo Disconnected e mantendo apenas a visualização dos últimos dados sincronizados.

  • Proteção por data de corte na sincronização (cutoff date): O botão “Sync now” na modal de detalhes e as rotas de sincronização sob demanda (POST /billing/quickbooks-invoices e POST /billing/xero-invoices) impedem a primeira exportação de faturas emitidas antes da data de corte definida (QuickBooks mantém a conferência e manutenção dos vínculos anteriores) na conexão contábil (sync_cutoff_date). Na interface, o botão fica desabilitado com aviso explicativo da data de corte e, na API, tentativas fora do período configurado são rejeitadas com erro 409.

  • Reconciliação e baixa bidirecional no QuickBooks (inbound): um pagamento pode quitar várias faturas. Cada fatura importa o valor aplicado a ela, desde que a conta GBP esteja confirmada e os vínculos e valores sejam verificáveis. Valores ainda não aplicados permanecem como crédito no QuickBooks. Notas de crédito vinculadas podem reduzir o saldo sem registrar entrada de dinheiro.

  • Granularidade e formatação de faturas no QuickBooks (outbound):

    • Cada tarefa contida na fatura vira uma linha individual no QuickBooks.
    • Qty registra as horas trabalhadas, UnitPrice registra a taxa horária (amount / hours) e Amount reflete a multiplicação de ambos.
    • Description exibe o nome do serviço, data da visita (DD/MM/YYYY) e código da tarefa (Tyy-seq), sem duplicar menções de horas no texto.
    • O endereço de cobrança (BillAddr) usa o snapshot emitido; somente documentos legados sem snapshot consultam o cadastro atual, e o endereço de entrega (ShipAddr) é omitido.
    • O memorando de extrato (PrivateNote / Message on statement) é mantido em branco para evitar redundância com o número oficial da fatura (DocNumber).
  • Corrigir um recibo da equipe (2026-11-09): na lista Money received da visita, cada recibo tem Corrigir (só escritório). O escritório diz o que aconteceu de verdade — valor (0 = não houve), como (dinheiro/conta) e quem — e vê antes de salvar o efeito: quanto muda o desconto de cada folha, quanto o cliente fica devendo e se a invoice volta a aguardar. Só aquele recibo muda: a transação dele na invoice vira FAILED e, se houve dinheiro, entra uma corrigida; os outros pagamentos ficam. A diferença segue a regra de /field/collect (dinheiro a menos: o cliente na próxima visita; na conta: quem recebeu), com a escolha trocável; a folha recebe só a diferença (planCollectionCorrection). Recusa recibo com crédito, divisão, várias visitas ou invoice ligada à contabilidade (esses seguem em Admin → Billing). Motivo: a T26-1009 só podia ser corrigida revertendo o pagamento inteiro, e cada tentativa piorava.