Een VAT-retoursysteem bouwen met Claude Code vanuit uw facturen- en onkostendatabase

Een korte, vlot leesbare metgezel. Voor de volledige diepgaande duik van ongeveer 5000 woorden met code, aanwijzingen, schema, een HMRC MTD walkthrough en randgevallen leest u het lange artikel.

Kwartaal VAT was het slechtste deel van mijn maand

Elk kwartaal moet een klein bedrijf in het Verenigd Koninkrijk een VAT-aangifte indienen: negen dozen met getallen (verkopen, aankopen, verschuldigde VAT, terug te vorderen VAT, EU-goederen als u zich in Noord-Ierland bevindt, totalen, netto) en deze indienen via HMRC Making Tax Digital (MTD). Jarenlang zag de mijne er zo uit: open de facturentabel in Postgres, exporteer een CSV, plak het in Excel, classificeer een paar honderd rijen met de hand, voer formules uit, kopieer negen getallen naar een MTD-bridge van derden, klik op Verzenden, hoop.

Het werkte, maar het was traag en verlieslatend. De ontvangstbewijzen zijn verdwenen. Rentewijzigingen halverwege het kwartaal braken de formules. Een typefout in één VAT-classificatie kan worden verplaatst Box 5 met honderden ponden. En het audittraject was: "geloof me, ik had een spreadsheet".

Dit jaar heb ik het geheel opnieuw opgebouwd als een klein Claude Code-project dat mijn facturen + onkosten-DB leest, elke regel classificeert, de negen vakken berekent, een pdf droogmaakt en pas daarna indient bij HMRC MTD - met een menselijke goedkeuringspoort. Deze blog is de korte versie. Het lange artikel bevat de aanwijzingen, de Python, de HMRC OAuth-stroom en de valkuilen.

Bekijk de walkthrough

Een korte walkthrough van de VAT-retourpijplijn die end-to-end loopt tegen een echte (geanonimiseerde) database met facturen en onkosten.

De vijfstappenpijplijn

1. Verbinden. Claude Code krijgt een alleen-lezen DB-koppeling met mijn facturen en onkostentabellen. Het heeft nooit schrijftoegang tot de brongegevens. CSV's van Stripe, Wise, Revolut en een paar bankfeeds worden erin geplaatst ./imports/.
2. Normaliseren. Claude genereert en voert een klein Python-script uit dat elk bronschema in één canonieke weergave in kaart brengt: id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key. Vreemde valuta worden omgerekend naar GBP met behulp van het maandtarief HMRC. De hele periode wordt ingetoetst door een idempotent run_key dus opnieuw rennen is veilig.
3. Categoriseren + afstemmen. Claude classificeert elke regel in een VAT-behandeling - standaard 20%, verlaagd 5%, nul, vrijgesteld, buiten bereik, verlegging, EU-goederen, EU-diensten, uitgestelde import VAT - met behulp van een kleine vat-rules.md Ik blijf in de repository. Het vergelijkt ook facturen met betalingen en signaleert afwijkingen (negatieve nettobedragen, ontbrekende VAT-nummers van leveranciers, niet-overeenkomende landcodes, leveranciers die niet VAT-geregistreerd zijn).
4. Berekenen. Een puur functionele Python-module - geen LLM in de wiskunde - leest de geclassificeerde rijen en produceert Box 1 tot en met Box 9, plus een drooglooprapport in Markdown. Het forfaitaire schema, de contante boekhouding en de jaarlijkse boekhoudkundige takken zijn expliciete codepaden en geen snelle instructies.
5. Indienen. Pas nadat ik (of mijn accountant) de proefperiode heb ondertekend, roept de pijplijn de HMRC MTD API aan. OAuth2-token. Kopteksten ter voorkoming van fraude. GET obligations om de open periode te vinden. POST returns met finalised: true. Dan GET liabilities om te bevestigen wat ik verschuldigd ben en wanneer.

Waarom Claude Code in plaats van Xero / QuickBooks / FreeAgent

Eerlijk gezegd is een SaaS-pakket voor accountants voor de meeste kleine bedrijven het juiste antwoord. Ze hebben een HMRC-certificering, ondersteuningsteams en uw accountant kent ze al. Dus waarom deed ik dit?

• Ik gebruik Claude Code al elke dag voor softwarewerk. De marginale kosten om het ook te gebruiken om een ​​VAT-pijpleiding samen te stellen, zijn klein.
• Mijn gegevens zijn lokaal. De facturen DB verlaten nooit mijn machine. De classificator loopt over rijen; de wiskunde is lokale Python; alleen de laatste negen cijfers gaan naar HMRC. Geen SaaS-tenant, geen derde partij.
• Ik wilde volledige controle over de categorisatieregels. Een deel van mijn leveranciersmix is ​​lastig (EU-diensten, uitgestelde import VAT, een paar randgevallen met nulbeoordeling). Codeer deze regels in vat-rules.md + een Python-module is voor mij sneller dan het configureren van een SaaS.
• Het audittraject is van mij. Elke Claude-prompt en elke diff wordt vastgelegd in een logboek dat alleen kan worden toegevoegd, naast de ondertekende momentopname. Als HMRC er ooit om vraagt, kan ik binnen enkele seconden de exacte berekening maken.

Als u Claude Code nog niet gebruikt of als u het niet leuk vindt om Python om middernacht te lezen, gebruik dan Xero / QuickBooks / FreeAgent. Dit is geen aanbeveling om uw eigen VAT-systeem te gebruiken. Het is een verhaal over wat er mogelijk is als je dat doet.

Waar de LLM is en niet is

Dit is het deel waar ik luid over wil zijn. Claude zit niet in de VAT-rekenkunde. Claude classificeert lijnen, stelt afstemmingen voor en genereert en bewerkt de deterministische Python-modules die de wiskunde doen. De daadwerkelijke berekening van Box 1 tot en met Box 9 is een pure functie met eenheidstests. De HMRC-inzending vereist een menselijke goedkeuringspoort. Het proefrapport is de bron van waarheid voor ondertekening. Als ik niet kan uitleggen waarom een ​​getal is wat het is door naar de code en de geclassificeerde rijen te kijken, dien ik niet in.

Dit is een harde regel omdat financiën gereguleerd zijn, en "de AI heeft het gedaan" is geen verdediging onder MTD. De lang artikel gaat dieper in op hoe u deze lijn in uw eigen implementatie kunt trekken.

Wat het mij heeft gekost om te bouwen, en wat het mij kost om te runnen

De bouwtijd besloeg ongeveer een week van gerichte avonden - meestal besteed aan schemanormalisatie, de classificatieregels en het schrijven van tests voor de engine. De HMRC MTD OAuth-dans was het langzaamste deel; als eerste tegen de zandbak rennen was elke minuut waard.

Om het uit te voeren, kost elk kwartaal me ongeveer: mijn Claude Code-abonnement (al betaald voor ander werk) plus een paar centen aan tokengebruik voor de classifier. De HMRC API zelf is gratis. De VAT-engine en het auditlogboek draaien lokaal op mijn Mac.

Belangrijke disclaimer

Ik ben een ingenieur, geen registeraccountant. Dit artikel is geen belastingadvies. Voordat u zoiets op uw echte HMRC-account uitvoert, moet u een in het Verenigd Koninkrijk geregistreerde accountant vragen uw eerste aangifte van begin tot eind te beoordelen. Gebruik de HMRC MTD zandbak totdat jij en je accountant allebei tevreden zijn. De kosten van een slechte VAT-inzending zijn veel hoger dan de kosten van een uur accountantstijd.

Lees de lange versie

Als u het volledige beeld wilt hebben - het exacte CREATE TABLE-schema, de Claude Code-prompts, de deterministische Python-engine met unit-tests, de HMRC MTD OAuth-stroom, headers ter preventie van fraude en een grondige sectie over randgevallen (Brexit/NI-protocol, verlegging, gedeeltelijke vrijstelling, forfaitaire regeling, tariefwijzigingen halverwege het kwartaal, facturen in meerdere valuta's, creditnota's, deposito's) - lees dan het lang artikel. Het is de versie die ik graag had willen lezen voordat ik begon.

Bekijk de YouTube-walkthrough, abonneer u op vervolgtutorials (bankfeeds automatisch importeren, OCR voor bonnen, geplande cron + Slack-goedkeuring) en onthoud: geen belastingadvies, aftekening door accountant vereist.