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

Este é o mergulho profundo de formato longo. Para uma versão mais rápida e legível, consulte o postagem complementar no blog.

1. Por que construí isso

Todas as pequenas empresas do Reino Unido com volume de negócios tributável acima do limite de registro VAT devem calcular e enviar uma declaração VAT - geralmente trimestralmente - por meio do serviço Making Tax Digital (MTD) da HMRC. Nove caixas numeradas. Saída VAT menos entrada VAT. Pague o valor líquido ou solicite o reembolso. Fácil em teoria; é punitivo na prática quando suas faturas estão em Postgres, seus recibos de despesas são PDFs de vinte fornecedores diferentes, seus extratos bancários são CSV da Wise e Revolut e suas linhas em moeda estrangeira precisam ser reapresentadas em libras à taxa mensal correta.

Por alguns anos, trabalhei com uma planilha gigante, um lembrete de calendário e um pequeno ato de fé. Cada trimestre levava cerca de meio dia, a maior parte do qual era disputa de dados - exportar um CSV do banco de dados de faturas, colar no Excel, classificar manualmente algumas centenas de linhas, verificar novamente as fórmulas, copiar nove números em uma ponte MTD de terceiros e clicar em Enviar. A trilha de auditoria foi “acredite, eu tinha uma planilha”. As mudanças nas taxas no meio do trimestre quebraram isso. Os recibos desapareceram. Uma classificação mal colocada poderia empurrar Box 5 em centenas de libras.

Eu reconstruí o gasoduto este ano como um pequeno Claude Code projeto que se comunica diretamente com meu banco de dados de faturas e despesas, classifica cada linha, calcula Box 1 a Box 9 com um mecanismo Python determinístico, executa o retorno como um relatório Markdown e somente depois que um humano assina o envio para HMRC MTD. O trimestre inteiro agora leva cerca de uma hora, a maior parte da qual é a revisão do teste com meu contador. A trilha de auditoria é um repositório git. A matemática é testada em unidade. O classificador é um arquivo Markdown documentado. A submissão é bloqueada.

Este artigo é a versão longa. Prompts, Python, esquema, fluxo HMRC OAuth, casos extremos. Se você quiser a versão curta primeiro, leia o blog complementar.

2. Primer HMRC MTD (e isenção de responsabilidade)

Making Tax Digital para VAT é um requisito da HMRC para que as empresas registradas na VAT mantenham registros digitais e enviem devoluções por meio de software compatível por meio de um API documentado, em vez de digitar números no formulário da web gov.uk. A API é OAuth2, requer cabeçalhos HTTP de prevenção de fraudes que identificam o dispositivo de origem e está disponível em uma sandbox gratuita antes mesmo de você iniciar a produção ao vivo.

O retorno em si é de nove caixas: Box 1 é VAT devido em vendas e outros resultados; Box 2 é VAT devido em aquisições de bens de estados membros da UE (relevante para empresas da Irlanda do Norte sob o protocolo NI); Box 3 é o total de VAT devido (Box 1 + Box 2); Box 4 é VAT recuperável em compras (insira VAT); Box 5 é o VAT líquido para pagar ou reclamar (Box 3 - Box 4); Box 6 é o total de vendas, excluindo VAT; Box 7 é o total de compras, excluindo VAT; Box 8 é o valor total dos bens fornecidos aos estados membros da UE (novamente apenas NI); Box 9 é o valor total das aquisições de estados membros da UE (somente NI). Existem variantes de regime - regime de taxa fixa, contabilidade de caixa, contabilidade anual - que mudam como você chega aos números, mas não ao formato da caixa.

Isenção de responsabilidade. Sou engenheiro de software, não revisor oficial de contas. Este artigo é não aconselhamento fiscal. As regras exatas para a classificação VAT, a isenção parcial, o regime de taxa fixa, as regras de local de prestação de serviços digitais, o tratamento pós-Brexit de bens e serviços da UE e o protocolo NI mudam ao longo do tempo e dependem das suas circunstâncias específicas. Antes de executar algo assim em uma conta HMRC real, peça a um contador registrado no Reino Unido para revisar sua primeira devolução de ponta a ponta. Para obter a regra oficial sobre qualquer caso extremo específico, consulte HMRC VAT Notice 700 e os avisos relacionados no site gov.uk. O custo de uma hora do tempo do seu contador é muito menor do que o custo de um envio incorreto.

3. O modelo de dados

Tudo a jusante depende da forma de duas tabelas: faturas emitidas (vendas) e despesas registadas (compras). Eu mantenho o meu no Postgres, mas o mesmo formato funciona no MySQL ou SQLite. O esquema mínimo útil:

CREATE TABLE invoices (
  id              BIGSERIAL PRIMARY KEY,
  invoice_number  TEXT NOT NULL UNIQUE,
  issued_at       DATE NOT NULL,
  customer_name   TEXT NOT NULL,
  customer_vat_no TEXT,
  customer_country CHAR(2) NOT NULL,
  net_amount      NUMERIC(14,2) NOT NULL,
  vat_amount      NUMERIC(14,2) NOT NULL,
  gross_amount    NUMERIC(14,2) NOT NULL,
  currency        CHAR(3) NOT NULL DEFAULT 'GBP',
  fx_rate_to_gbp  NUMERIC(18,8) NOT NULL DEFAULT 1,
  vat_rate        NUMERIC(5,2) NOT NULL,
  vat_treatment   TEXT NOT NULL,
  status          TEXT NOT NULL,
  paid_at         DATE,
  notes           TEXT,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE expenses (
  id              BIGSERIAL PRIMARY KEY,
  supplier_name   TEXT NOT NULL,
  supplier_vat_no TEXT,
  supplier_country CHAR(2) NOT NULL,
  incurred_at     DATE NOT NULL,
  net_amount      NUMERIC(14,2) NOT NULL,
  vat_amount      NUMERIC(14,2) NOT NULL,
  gross_amount    NUMERIC(14,2) NOT NULL,
  currency        CHAR(3) NOT NULL DEFAULT 'GBP',
  fx_rate_to_gbp  NUMERIC(18,8) NOT NULL DEFAULT 1,
  vat_rate        NUMERIC(5,2) NOT NULL,
  vat_treatment   TEXT NOT NULL,
  category        TEXT NOT NULL,
  receipt_url     TEXT,
  notes           TEXT,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

As colunas não óbvias são vat_treatment, fx_rate_to_gbpe os códigos do país. O tratamento é uma pequena enumeração usada tanto pelo classificador quanto pelo mecanismo; o código do país impulsiona a lógica de autoliquidação e de aquisição da UE; A taxa de câmbio permite que você mantenha as faturas em moeda estrangeira em sua moeda original e ainda reafirme em GBP os totais da caixa.

Preencher essas colunas em uma tabela de faturas herdada é a parte mais lenta do projeto. Claude Code pode gerar a migração; você ainda precisa classificar manualmente os casos extremos estranhos.

4. Por que Claude Code (e não Xero/QuickBooks/FreeAgent)

Para a maioria das pequenas empresas do Reino Unido, a resposta é - genuinamente - usar software empacotado. Xero, QuickBooks, FreeAgent, Sage têm envio MTD com certificação HMRC, interfaces de usuário decentes e contadores que já os conhecem. Você não deve instalar seu próprio sistema VAT, a menos que tenha um motivo claro.

Minhas razões eram limitadas, mas reais. Eu já uso o Claude Code todos os dias para trabalhar com software, então o esforço marginal para usá-lo também no VAT foi pequeno. Meu banco de dados de faturas reside em minha própria máquina; Prefiro que não seja espelhado em um locatário SaaS. Meu mix de fornecedores é estranho (serviços da UE com cobrança reversa, importação adiada VAT, casos extremos ocasionais com classificação zero) e codificar as regras em um único arquivo Markdown mais um módulo Python acabou sendo mais rápido do que configurar um SaaS para lidar com eles. E a trilha de auditoria que obtenho de um repositório git - cada prompt do classificador, cada comparação, cada instantâneo de período assinado - é exatamente a trilha de auditoria que desejo.

O Claude Code é adequado para isso por três motivos. Primeiro, ele funciona diretamente em um projeto no disco: ele pode ler meu esquema, os relatórios de simulação do trimestre anterior, o arquivo de regras e o mecanismo Python, e propor edições no contexto. Em segundo lugar, é bom em andaimes enfadonhos - scripts de migração, importadores de CSV, relatórios de reconciliação, acessórios de pytest. Terceiro, quando classifica uma linha, explica o seu raciocínio em linguagem simples, que é exactamente o que quero rever antes de assinar a declaração. A matriz de decisão na parte inferior do diagrama de fluxo de trabalho abaixo é a versão honesta dessa compensação.

5. Arquitetura e fluxo de trabalho

O gasoduto possui cinco raias. Fonte é acesso somente leitura às tabelas de faturas e despesas, além de uma pasta suspensa para CSV do Stripe, Wise e feeds bancários. Ingerir + Normalizar é um pequeno script Python gerado por Claude que mapeia cada esquema de origem em uma visualização canônica, converte moeda estrangeira em GBP à taxa mensal HMRC, aplica um filtro de intervalo de datas e carimba cada linha com um idempotente run_key então as repetições são seguras. Categorizar + Reconciliar é o classificador Claude Code: ele percorre cada linha canônica, escolhe um vat_treatment do enum documentado usando regras em vat-rules.md, reconcilia faturas com pagamentos e sinaliza anomalias (líquido negativo, número VAT de fornecedor ausente, incompatibilidade de código de país, fornecedores que deveriam estar registrados em VAT, mas não estão). Motor VAT é um módulo Python puro que lê as linhas classificadas e calcula Box 1 a Box 9 de forma determinística; as filiais do esquema de taxa fixa, em dinheiro e anual são caminhos de código explícitos. Enviar + Auditoria é a chamada HMRC MTD API (OAuth2, cabeçalhos de prevenção de fraudes, sandbox first), protegida por uma etapa de aprovação humana, com o instantâneo do período assinado e o log completo do classificador gravados em uma pasta de auditoria somente anexada retida por seis anos.

6. Construção passo a passo com Claude Code

Este é o fluxo de trabalho que realmente usei. Cinco instruções. Eu os limpei para este artigo; os originais são mais confusos.

Prompt 1 - normalizador. "Olha o invoices e expenses tabelas em schema.sql. Gere um módulo Python normalise.py que lê ambas as tabelas usando psycopg (função somente leitura vat_reader), restringe-se ao intervalo de datas 2026-01-01 para 2026-03-31e emite uma lista de ditados canônicos com chaves: id, source, date, party, gross, net, vat_amount, vat_rate, vat_treatment, country, currency, fx_rate, run_key. Usar Decimal, não flutuar. Inclua um docstring e um __main__ bloco que imprime um resumo."

Claude devolveu um módulo limpo com Decimal, SQL parametrizado, um build_run_key() que faz o hash (início_período, fim_período, esquema, versão_esquema) em uma string hexadecimal estável e uma CLI baseada em clique. Editei dois nomes de campos e aceitei o restante.

Prompt 2 - classificador. "Ler vat-rules.md e escrever classify.py. Para cada linha canônica de normalise.py, definir vat_treatment para um dos: padrão, reduzido, zero, isentar, fora do escopo, cobrança reversa, bens da ue, serviços da ue, importação adiada. Se a linha já tiver um valor não vazio vat_treatment, deixe-o como está e grave-o como preservado. Caso contrário, decida o código do país, o número VAT do fornecedor, a categoria e o valor e escreva uma frase reason em cada linha. Anomalias (líquido negativo, fornecedor ausente VAT para um fornecedor do Reino Unido acima do limite de registro, incompatibilidade de país) vão para um departamento separado anomalies.json para revisão humana. Não altere o banco de dados de origem."

O classificador em si é uma função pequena, baseada principalmente em regras, com uma ramificação apoiada por LLM para categorias de despesas ambíguas. Criticamente, ele nunca grava no banco de dados de origem - ele emite um arquivo JSON classificado que o mecanismo lê. Se discordo de uma classificação, edito o JSON; o próximo ensaio o pega.

Alerta 3 - motor. "Escrever engine.py como uma função pura: def compute_boxes(rows: list[Row], scheme: Scheme) -> BoxTotals. Sem E/S. Sem LLM. BoxTotals é uma classe de dados congelada com Box 1 a Box 9 como Decimal valores para 2 dp. Adicione ramificações explícitas para standard, flat_rate, cash, e annual esquemas. O esquema padrão é o acúmulo: as vendas de VAT contribuem para Box 1, as compras de VAT para Box 4. As faturas de cobrança reversa são adicionadas ao Box 1 e ao Box 4. A importação adiada do VAT é adicionada ao Box 1 e ao Box 4. As aquisições na UE para empresas NI vão em Box 2 e Box 9. Arredonde nos totais das caixas, nunca por linha. Escreva uma doutrina ligando cada ramo à sua regra."

Prompt 4 - relatório de simulação. "Escrever dryrun.py que chama compute_boxes() e emite um relatório Markdown: cabeçalho com período e esquema, uma tabela de Box 1 a Box 9 com os rótulos canônicos, uma seção por bucket do classificador listando as 10 principais linhas por bruto, uma seção de anomalias e um rodapé com o run_key e um SHA-256 do JSON classificado. Salvar em ./audit/<period>/dryrun.md."

Prompt 5 - remetente. "Escrever submit.py contra o HMRC MTD VAT API v1.0. Use o fluxo de código_de_autorização OAuth2 com PKCE. Leia o token de acesso de ~/.vat/token.json; atualizar se expirar. Cabeçalhos de prevenção de fraudes exigidos, conforme documentado por HMRC; puxe-os de fraud_headers.py. Padrão para a sandbox https://test-api.service.hmrc.gov.uk. Passos: GET /organisations/vat/{vrn}/obligations?status=O, encontre o período correspondente, solicite ao operador que confirme exibindo o resumo do teste e, em seguida, POST /organisations/vat/{vrn}/returns com finalised: true. Imprima o receiptId. Nunca ligue ao vivo, a menos que HMRC_ENV=live está definido e o operador digita ENVIAR."

Cinco prompts, quatro arquivos e um pequeno documento de regras de Markdown. O tempo total de construção foi talvez uma semana de noites focadas, a maior parte das quais foram as regras do classificador e a dança HMRC OAuth.

7. O motor VAT

O motor é a parte deliberadamente chata. É uma função pura com testes unitários e sem IA. Esta é a forma real:

from dataclasses import dataclass
from decimal import Decimal, ROUND_HALF_UP

D2 = Decimal("0.01")

@dataclass(frozen=True)
class BoxTotals:
    box1: Decimal
    box2: Decimal
    box3: Decimal
    box4: Decimal
    box5: Decimal
    box6: Decimal
    box7: Decimal
    box8: Decimal
    box9: Decimal

def _q(x: Decimal) -> Decimal:
    return x.quantize(D2, rounding=ROUND_HALF_UP)

def compute_boxes(rows, scheme="standard", is_ni_business=False) -> BoxTotals:
    box1 = box2 = box4 = Decimal(0)
    box6 = box7 = box8 = box9 = Decimal(0)

    for r in rows:
        gbp_net = r.net * r.fx_rate
        gbp_vat = r.vat_amount * r.fx_rate

        if r.source == "invoice":
            box6 += gbp_net
            if r.vat_treatment in ("standard", "reduced"):
                box1 += gbp_vat
            elif r.vat_treatment == "eu-goods" and is_ni_business:
                box8 += gbp_net
        else:
            box7 += gbp_net
            if r.vat_treatment in ("standard", "reduced"):
                box4 += gbp_vat
            elif r.vat_treatment == "reverse-charge":
                notional = gbp_net * (r.vat_rate / Decimal(100))
                box1 += notional
                box4 += notional
            elif r.vat_treatment == "postponed-import":
                notional = gbp_net * (r.vat_rate / Decimal(100))
                box1 += notional
                box4 += notional
            elif r.vat_treatment == "eu-goods" and is_ni_business:
                notional = gbp_net * (r.vat_rate / Decimal(100))
                box2 += notional
                box4 += notional
                box9 += gbp_net

    box3 = box1 + box2
    box5 = box3 - box4
    return BoxTotals(
        _q(box1), _q(box2), _q(box3), _q(box4), _q(box5),
        _q(box6), _q(box7), _q(box8), _q(box9),
    )

Duas coisas a serem observadas. Primeiro, cada total de caixas é quantizado uma vez no final. O arredondamento por linha vaza centavos e o HMRC é implacável com totais que não se reconciliam. Em segundo lugar, o mecanismo é totalmente determinístico: sempre a mesma entrada, a mesma saída. Essa é a propriedade que me permite testar a unidade e confiar no teste.

def test_simple_quarter():
    rows = [
        Row("invoice", net=Decimal("24500.00"), vat_amount=Decimal("4900.00"),
            vat_rate=Decimal("20"), vat_treatment="standard", fx_rate=Decimal(1), source="invoice"),
        Row("expense", net=Decimal("3000.00"), vat_amount=Decimal("600.00"),
            vat_rate=Decimal("20"), vat_treatment="standard", fx_rate=Decimal(1), source="expense"),
    ]
    t = compute_boxes(rows)
    assert t.box1 == Decimal("4900.00")
    assert t.box4 == Decimal("600.00")
    assert t.box5 == Decimal("4300.00")
    assert t.box6 == Decimal("24500.00")
    assert t.box7 == Decimal("3000.00")

Com isso implementado, cada regressão é capturada no CI antes mesmo de chegar ao relatório de simulação. Claude pode me ajudar a escrever mais testes; não pode mudar o motor sem passar nos testes.

8. Vídeo de demonstração

Abaixo está um breve passo a passo do pipeline executado de ponta a ponta em um banco de dados de faturas e despesas reais (anonimizado) de um trimestre: normalização, classificação, simulação e, em seguida, um envio de sandbox MTD. O ciclo completo dura alguns minutos.

9. Envio HMRC MTD

Esta é a parte que a maioria dos artigos encobre. O MTD VAT API em si é bem documentado e gratuito, mas há três coisas que você precisa acertar antes de ligar POST returns.

OAuth2 e tokens. Registre um aplicativo no hub do desenvolvedor HMRC; você obtém um ID do cliente, um segredo do cliente e um URI de redirecionamento. O fluxo é authorisation_code com PKCE: abra o navegador na página de consentimento do HMRC, o usuário efetua login com suas credenciais do Government Gateway e autoriza seu aplicativo com base no número de registro VAT (VRN), o HMRC redireciona de volta com um código de autorização, você o troca por um token de acesso + token de atualização. Armazene-os em cache com permissões sensatas no disco. O token de acesso tem vida curta; o token de atualização é muito mais longo.

Cabeçalhos de prevenção de fraude. HMRC exige um conjunto documentado de cabeçalhos HTTP que identificam o dispositivo de origem em cada chamada API: fuso horário, geometria da tela, IDs de usuário, IP público, endereços MAC, método de conexão do cliente, etc. A lista e o formato exatos estão na documentação do desenvolvedor HMRC (consulte o Aviso 700 do HMRC VAT e as especificações de prevenção de fraude relacionadas para a regra oficial). Entenda-os errado e você terá um 403 com um erro vago. Acerte-os e a chamada será completada. Eu os mantenho fraud_headers.py e afirmar sua presença em testes.

Caixa de areia primeiro. HMRC fornece um sandbox gratuito em test-api.service.hmrc.gov.uk com VRNs stub e obrigações stub. Execute todo o pipeline de ponta a ponta no sandbox até enviar uma devolução falsa, receber um ID de recibo falso e confirmar a mudança de suas obrigações. Só então você vira HMRC_ENV=live. Meu remetente se recusa a ligar ao vivo, a menos que a variável de ambiente esteja definida e o operador digite SUBMIT no prompt. Não há caminho de execução automático para viver. O custo de um único envio incorreto ao vivo é muito maior do que o custo de mais uma iteração de sandbox.

A chamada do caminho feliz real é curta: GET obligations com status=O para encontrar o período aberto, exibir o relatório de simulação, solicitar que o operador confirme e, em seguida, POST returns com os nove números das caixas, o periodKey da obrigação, e finalised: true. Salve a resposta, escreva o ID do recibo na pasta de auditoria e pronto.

10. Segurança, auditoria e conformidade

Três regras que não vou seguir em frente. Primeiro, Claude não está na aritmética. O classificador sugere tratamentos e o LLM pode editar Python e regras, mas os totais da caixa são produzidos por uma função pura com testes unitários. “A IA fez isso” não é uma defesa no MTD. Segundo, cada envio é controlado por um humano. O relatório de simulação é a fonte da verdade para aprovação. Se não consigo explicar um número das linhas classificadas e do código do motor, não submeto. Terceiro, a trilha de auditoria é apenas anexada. Cada JSON classificado, cada relatório de simulação, cada prompt, cada diferença e o ID de recibo HMRC final do período são gravados em ./audit/<period>/ e comprometido com um repositório git privado. HMRC requer seis anos de registros; os meus são instantâneos assinados.

Mais duas práticas que eu recomendaria, mesmo que você não adote o resto. Execute a conexão do banco de dados de origem como uma função somente leitura com privilégio mínimo: não UPDATE, não DELETE, não DROP. Mantenha o segredo do cliente HMRC e os tokens de acesso fora do repositório usando um gerenciador de segredos ou um arquivo 0600 em seu diretório inicial. A questão é tornar os acidentes impossíveis através da construção, e não apenas através de políticas.

11. Casos extremos

VAT é um imposto regulamentado que foi editado por todos os governos do Reino Unido desde 1973, com uma sobreposição pós-Brexit e um protocolo da Irlanda do Norte no topo. Os casos extremos são reais. Uma lista não exaustiva daqueles que meu mecanismo controla:

• Brexit e Irlanda do Norte. As empresas da Grã-Bretanha não preenchem mais Box 8 ou Box 9. As empresas NI ainda fazem isso para bens (não serviços) sob o protocolo NI. O motor leva is_ni_business como parâmetro e ramifica de acordo. Consulte HMRC VAT Aviso 700 para obter a regra oficial.
• Carga reversa. Os serviços adquiridos de um fornecedor fora do Reino Unido (e certos serviços domésticos da indústria de construção) são contabilizados sob autoliquidação: você adiciona uma produção nocional VAT a Box 1 e recupera o mesmo valor em Box 4. O efeito líquido sobre o caixa é zero; O efeito líquido no retorno é de duas caixas que se movem juntas.
• Importação adiada VAT. Para mercadorias importadas de fora do Reino Unido, você adia a importação VAT para sua próxima devolução, em vez de pagá-la na fronteira. O tratamento é semelhante à cobrança reversa na devolução.
• Isenção parcial. Se você fizer fornecimentos tributáveis ​​e isentos, só poderá recuperar o insumo VAT na medida em que estiver relacionado a fornecimentos tributáveis. Existem métodos padrão e especiais; esse é o canto que mais precisa de um contador. Não tente codificar regras de isenção parcial em um arquivo Markdown.
• Esquema de taxa fixa. Você cobra VAT à taxa padrão, mas paga a HMRC uma porcentagem fixa do faturamento bruto e geralmente não pode recuperar o VAT de entrada. O mecanismo possui uma ramificação separada para isso e ignora a maior parte da classificação por linha.
• Faturas em várias moedas. Converta cada linha em GBP à taxa em vigor na data relevante. HMRC publica taxas médias mensais; você também pode usar a taxa à vista. Seja consistente. O fx_rate_to_gbp coluna armazena a taxa real aplicada por linha.
• Notas de crédito. Uma nota de crédito é uma fatura negativa. Reduz Box 1 e Box 6 (ou Box 4 e Box 7 se for um crédito de compra). Certifique-se de que seu net_amount e vat_amount podem ficar negativos e que o mecanismo os soma corretamente.
• Depósitos e pagamentos parcelados. O ponto fiscal pode ser quando o depósito é recebido, e não quando a fatura final é emitida. A contabilidade de caixa pode simplificar isso.
• Mudanças nas taxas no meio do trimestre. Historicamente raro, mas possível. Armazene a taxa por linha, não como uma constante global.

12. Custo

Números honestos. Tempo de construção foi cerca de uma semana de noites concentradas - considere 25 a 30 horas. A maior parte disso foi a normalização do esquema, as regras do classificador e a escrita dos testes do mecanismo; a dança HMRC OAuth foi a segunda maior parte. Custo operacional por trimestre é pequeno: minha assinatura Claude Code existente (já paga por outro trabalho de software), alguns centavos no uso do token classificador e zero libras para o HMRC API. O mecanismo e o log de auditoria são executados localmente no meu Mac. Tempo do revisor por trimestre é cerca de uma hora, a maior parte gasta lendo o ensaio com meu contador. Compare isso com cerca de meio dia de discussão de planilhas no fluxo de trabalho antigo e o tempo economizado compensa o custo de construção no primeiro ano.

Se você avaliasse isso como um projeto que estava pagando a outra pessoa para construir, estaria na casa dos quatro dígitos em taxas de consultoria - e é por isso que um pacote SaaS de vinte a cinquenta libras por mês é quase sempre a resposta certa para a maioria das empresas. A questão interessante não é “isso é mais barato que o Xero?” - geralmente não é - mas "é mais preciso, mais auditável e mais fácil de raciocinar?". Para mim a resposta é sim.

13. O que vem a seguir e conclusão

As próximas peças que quero adicionar são: importação automática de feed de banco (Open Banking AISP), OCR para PDFs de fornecedores para que o URL do recibo se torne uma linha digitalizada real, um fluxo de aprovação agendado cron + Slack para que eu não precise me lembrar dos prazos, e uma extensão de autofaturamento para vendedores do marketplace. Nada disso altera a forma central do pipeline. São todas decorações no mesmo diagrama de cinco pistas.

A maior lição, pelo menos para mim, é como um pequeno projeto Claude Code lida bem com a metade chata de um fluxo de trabalho regulamentado. A parte chata é a maior parte do trabalho: normalização de esquema, importadores de CSV, relatórios de reconciliação, acessórios, regras de casos extremos, registro de auditoria. Claude é excelente em tudo isso. A metade determinística - a matemática real, o envio real - permanece em Python simples com testes unitários e uma porta de aprovação humana, exatamente onde ela pertence.

Isenção de responsabilidade, novamente. Este artigo não é um conselho fiscal. Antes de apontar algo assim para uma conta HMRC real, peça a um contador registrado no Reino Unido para revisar sua primeira devolução de ponta a ponta. Execute o sandbox HMRC MTD até que você e seu contador estejam confiantes. Para obter a regra oficial sobre qualquer tratamento específico do VAT, consulte o Aviso 700 do HMRC VAT e os avisos relacionados no site gov.uk. Se você quiser a versão resumida de tudo isso, o postagem complementar no blog é uma leitura de cinco minutos; caso contrário, inscreva-se e continuarei escrevendo à medida que a pilha amadurece.

Instantâneo de SEO para este artigo

• Título SEO: Crie um sistema de devolução VAT com Claude Code
• Meta descrição: Use o Claude Code para ler seu banco de dados de faturas e despesas, classificar VAT, calcular HMRC Box 1 até 9, executar simulação e, em seguida, enviar para MTD - mecanismo determinístico, aprovação humana.
• Palavras-chave primárias: código claude, IVA, hmrc, mtd, contabilidade, automação, python, agente de IA, finops, pequenas empresas
• Twitter / X (menos de 280 caracteres): Reconstruí meu retorno VAT no Reino Unido como um projeto Claude Code: faturas Postgres + banco de dados de despesas para HMRC Box 1 para 9, mecanismo Python determinístico, envio MTD primeiro em sandbox, portão de aprovação humana. Artigo completo + fluxo de trabalho SVG + vídeo de demonstração. Não é aconselhamento fiscal. #ClaudeCode #VAT #HMRC #MTD
• Postagem no LinkedIn: Reconstruí meu retorno trimestral do VAT no Reino Unido como um pequeno projeto Claude Code este ano. Ele lê meu banco de dados de faturas e despesas como somente leitura, classifica cada linha por tratamento VAT usando um arquivo de regras documentado, calcula HMRC Box 1 até 9 com um mecanismo Python determinístico (sem LLM na aritmética) e somente depois que eu aprovo o teste ele é enviado por meio do HMRC MTD API - sandbox primeiro, cabeçalhos de prevenção de fraudes, o fluxo OAuth2 completo. O trimestre inteiro agora leva cerca de uma hora. O artigo completo com prompts, esquema, código do mecanismo, casos extremos e a história de custo honesta está no Workstation. Não é aconselhamento fiscal; peça a um contador para revisar seu primeiro retorno.