Construindo um sistema de devolução VAT com Claude Code a partir de seu banco de dados de faturas e despesas

Um companheiro curto e de fácil leitura. Para obter um mergulho profundo completo de aproximadamente 5.000 palavras com código, prompts, esquema, um passo a passo do HMRC MTD e casos extremos, leia o longo artigo.

O VAT trimestral foi a pior parte do meu mês

A cada trimestre, uma pequena empresa do Reino Unido precisa produzir um retorno VAT: nove caixas de números (vendas, compras, VAT vencidas, VAT recuperáveis, produtos da UE se você estiver na Irlanda do Norte, totais, líquidos) e enviá-los por meio do HMRC Making Tax Digital (MTD). Durante anos, a minha ficou assim: abrir a tabela de faturas no Postgres, exportar um CSV, colá-lo no Excel, classificar manualmente algumas centenas de linhas, executar fórmulas, copiar nove números em uma ponte MTD de terceiros, clicar em Enviar, espero.

Funcionou, mas foi lento e com perdas. Os recibos desapareceram. As mudanças nas taxas no meio do trimestre quebraram as fórmulas. Um erro de digitação em uma classificação VAT pode mudar Box 5 por centenas de libras. E a trilha de auditoria era “acredite, eu tinha uma planilha”.

Este ano reconstruí tudo como um pequeno projeto Claude Code que lê meu banco de dados de faturas + despesas, classifica cada linha, calcula as nove caixas, executa um PDF e só então envia para HMRC MTD - com um portão de aprovação humano. Este blog é a versão curta. O longo artigo contém os prompts, o Python, o fluxo HMRC OAuth e as dicas.

Assista ao passo a passo

Um breve passo a passo do pipeline de retorno VAT executado de ponta a ponta em um banco de dados de faturas + despesas reais (anonimizadas).

O pipeline de cinco etapas

1. Conectar. Claude Code recebe um somente leitura Conexão DB com minhas tabelas de faturas e despesas. Ele nunca tem acesso de gravação aos dados de origem. CSVs de Stripe, Wise, Revolut e alguns feeds de banco são colocados em ./imports/.
2. Normalizar. Claude gera e executa um pequeno script Python que mapeia cada esquema de origem em uma visão canônica: id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key. A moeda estrangeira é convertida para GBP usando a taxa mensal HMRC. Todo o período é chaveado por um idempotente run_key então reexecutar é seguro.
3. Categorizar + reconciliar. Claude classifica cada linha em um tratamento VAT - padrão 20%, reduzido 5%, zero, isento, fora do escopo, autoliquidação, bens da UE, serviços da UE, importação adiada VAT - usando um pequeno vat-rules.md Eu continuo no repositório. Ele também reconcilia faturas com pagamentos e sinaliza anomalias (valores líquidos negativos, números VAT de fornecedor ausentes, incompatibilidades de código de país, fornecedores que não estão registrados em VAT).
4. Calcular. Um módulo Python de função pura - sem LLM na matemática - lê as linhas classificadas e produz Box 1 até Box 9, além de um relatório de simulação em Markdown. O esquema de taxa fixa, a contabilidade de caixa e as filiais de contabilidade anual são caminhos de código explícitos, e não instruções imediatas.
5. Enviar. Somente depois que eu (ou meu contador) tiver aprovado o teste é que o pipeline chama HMRC MTD API. Token OAuth2. Cabeçalhos de prevenção de fraude. GET obligations para encontrar o período aberto. POST returns com finalised: true. Então GET liabilities para confirmar o que devo e quando.

Por que Claude Code em vez de Xero/QuickBooks/FreeAgent

Honestamente, para a maioria das pequenas empresas, um pacote SaaS de contabilidade é a resposta certa. Eles possuem certificação HMRC, equipes de suporte e seu contador já os conhece. Então por que eu fiz isso?

• Eu já uso o Claude Code todos os dias para trabalho de software. O custo marginal de usá-lo também para montar um pipeline VAT é pequeno.
• Meus dados são locais. O banco de dados de faturas nunca sai da minha máquina. O classificador percorre linhas; a matemática é Python local; apenas os nove números finais vão para HMRC. Nenhum inquilino SaaS, nenhum terceiro.
• Eu queria controle total das regras de categorização. Parte do meu mix de fornecedores é estranho (serviços da UE, importação adiada VAT, alguns casos extremos com classificação zero). Codificando essas regras em vat-rules.md + um módulo Python é mais rápido para mim do que configurar um SaaS.
• A trilha de auditoria é minha. Cada prompt do Claude e cada comparação são confirmados em um log somente anexado junto com o instantâneo do período assinado. Se o HMRC perguntar, posso produzir o cálculo exato em segundos.

Se você ainda não usa Claude Code ou não gosta de ler Python à meia-noite, use Xero/QuickBooks/FreeAgent. Esta não é uma recomendação para instalar seu próprio sistema VAT. É uma história do que é possível quando você faz isso.

Onde o LLM está e não está

Esta é a parte sobre a qual quero falar alto. Claude não está na aritmética VAT. Claude classifica linhas, sugere reconciliações e gera e edita os módulos determinísticos do Python que fazem as contas. O cálculo real de Box 1 até Box 9 é uma função pura com testes de unidade. O envio do HMRC requer uma porta de aprovação humana. O relatório de simulação é a fonte da verdade para aprovação. Se não consigo explicar por que um número é o que é olhando o código e as linhas classificadas, não submeto.

Esta é uma regra rígida porque as finanças são regulamentadas e “a IA fez isso” não é uma defesa sob o MTD. O artigo longo entra em mais detalhes sobre como traçar essa linha em sua própria implementação.

Quanto me custou construir e quanto me custou administrar

O tempo de construção durou cerca de uma semana de noites focadas - principalmente gastas na normalização do esquema, nas regras do classificador e na escrita de testes para o mecanismo. A dança HMRC MTD OAuth foi a parte mais lenta; correr primeiro contra a caixa de areia valeu cada minuto.

Para funcionar, cada trimestre me custa aproximadamente: minha assinatura Claude Code (já paga por outro trabalho) mais alguns centavos em uso de token para o classificador. O próprio HMRC API é gratuito. O mecanismo VAT e o log de auditoria são executados localmente no meu Mac.

Isenção de responsabilidade importante

Sou engenheiro, não revisor oficial de contas. Este artigo não é um conselho fiscal. Antes de executar algo assim em sua conta HMRC real, peça a um contador registrado no Reino Unido para revisar sua primeira devolução de ponta a ponta. Use o HMRC MTD caixa de areia até que você e seu contador estejam felizes. O custo de um envio VAT incorreto é muito maior do que o custo de uma hora de trabalho de um contador.

Leia a versão longa

Se você quiser a imagem completa - o esquema CREATE TABLE exato, os prompts Claude Code, o mecanismo Python determinístico com testes de unidade, o fluxo OAuth HMRC MTD, cabeçalhos de prevenção de fraude e uma seção completa sobre casos extremos (protocolo Brexit / NI, cobrança reversa, isenção parcial, esquema de taxa fixa, alterações de taxa no meio do trimestre, faturas em várias moedas, notas de crédito, depósitos) - leia o artigo longo. É a versão que eu gostaria de ler antes de começar.

Assista o Passo a passo do YouTube, inscreva-se para tutoriais de acompanhamento (importação automática de feeds bancários, OCR para recibos, cron programado + aprovação do Slack) e lembre-se: não é necessário aconselhamento fiscal, é necessária a aprovação do contador.