Construire un système de retour VAT avec Claude Code à partir de votre base de données de factures et de dépenses

Un compagnon court et lisible. Pour une analyse approfondie d'environ 5 000 mots avec le code, les invites, le schéma, une procédure pas à pas HMRC MTD et les cas extrêmes, lisez le long article.

Le VAT trimestriel a été la pire période de mon mois

Chaque trimestre, une petite entreprise britannique doit produire une déclaration VAT : neuf cases de chiffres (ventes, achats, VAT dus, VAT récupérables, marchandises de l'UE si vous êtes en Irlande du Nord, totaux, nets) et les soumettre via HMRC Making Tax Digital (MTD). Pendant des années, le mien ressemblait à ceci : ouvrez le tableau des factures dans Postgres, exportez un CSV, collez-le dans Excel, classez manuellement quelques centaines de lignes, exécutez des formules, copiez neuf nombres dans un pont MTD tiers, cliquez sur Soumettre, j'espère.

Cela a fonctionné, mais c'était lent et avec perte. Les reçus ont disparu. Les changements de taux au milieu du trimestre ont brisé les formules. Une faute de frappe dans une classification VAT pourrait bouger Box 5 par centaines de livres. Et la piste d'audit était "croyez-moi, j'avais une feuille de calcul".

Cette année, j'ai reconstruit le tout comme un petit projet Claude Code qui lit ma base de données de factures et de dépenses, classe chaque ligne, calcule les neuf cases, exécute un PDF à sec, et le soumet ensuite seulement à HMRC MTD - avec une porte d'approbation humaine. Ce blog est la version courte. Le long article contient les invites, Python, le flux HMRC OAuth et les pièges.

Regardez la procédure pas à pas

Une brève présentation du pipeline de retour VAT fonctionnant de bout en bout avec une base de données réelle (anonymisée) de factures + dépenses.

Le pipeline en cinq étapes

1. Connecter. Claude Code obtient un en lecture seule Connexion DB à mes factures et tableaux de dépenses. Il n'a jamais accès en écriture aux données source. Les CSV de Stripe, Wise, Revolut et quelques flux bancaires sont déposés dans ./imports/.
2. Normaliser. Claude génère et exécute un petit script Python qui mappe chaque schéma source en une seule vue canonique : id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key. La devise étrangère est convertie en GBP en utilisant le taux mensuel HMRC. Toute la période est marquée par un idempotent run_key donc la réexécution est sûre.
3. Catégoriser + réconcilier. Claude classe chaque ligne dans un traitement VAT - standard 20 %, réduit 5 %, zéro, exonéré, hors champ d'application, autoliquidation, biens de l'UE, services de l'UE, importation différée VAT - en utilisant un petit vat-rules.md Je garde dans le repo. Il rapproche également les factures avec les paiements et signale les anomalies (montants nets négatifs, numéros VAT de fournisseur manquants, incompatibilités de codes de pays, fournisseurs non enregistrés VAT).
4. Calculer. Un module Python purement fonctionnel - pas de LLM en maths - lit les lignes classifiées et produit Box 1 à Box 9, ainsi qu'un rapport d'essai à sec dans Markdown. Le régime forfaitaire, la comptabilité de caisse et les succursales de comptabilité annuelle sont des chemins de code explicites et non des instructions rapides.
5. Soumettre. Ce n'est qu'après que moi (ou mon comptable) ayez signé l'essai à sec que le pipeline appelle le HMRC MTD API. Jeton OAuth2. En-têtes de prévention de la fraude. GET obligations pour trouver la période ouverte. POST returns avec finalised: true. Alors GET liabilities pour confirmer ce que je dois et quand.

Pourquoi Claude Code au lieu de Xero / QuickBooks / FreeAgent

Honnêtement, pour la plupart des petites entreprises, un package SaaS pour comptable est la bonne réponse. Ils ont la certification HMRC, des équipes d'assistance et votre comptable les connaît déjà. Alors pourquoi ai-je fait ça ?

• J'utilise déjà Claude Code tous les jours pour le travail logiciel. Le coût marginal de son utilisation également pour assembler un pipeline VAT est faible.
• Mes données sont locales. La base de données des factures ne quitte jamais ma machine. Le classificateur s'exécute sur les lignes ; les calculs sont en Python local ; seuls les neuf derniers numéros vont à HMRC. Pas de locataire SaaS, pas de tiers.
• Je voulais un contrôle total sur les règles de catégorisation. Certains de mes fournisseurs sont délicats (services de l'UE, importation VAT reportée, quelques cas extrêmes détaxés). Encoder ces règles dans vat-rules.md + un module Python est pour moi plus rapide que de configurer un SaaS.
• La piste d'audit m'appartient. Chaque invite Claude et chaque différence sont enregistrées dans un journal en ajout uniquement aux côtés de l'instantané de période signé. Si HMRC me le demande, je peux produire le calcul exact en quelques secondes.

Si vous n'utilisez pas déjà Claude Code ou si vous n'aimez pas lire Python à minuit, veuillez utiliser Xero / QuickBooks / FreeAgent. Ce n'est pas une recommandation de déployer votre propre système VAT. C'est une histoire de ce qui est possible lorsque vous le faites.

Où se trouve et n'est pas le LLM

C’est la partie sur laquelle je veux parler fort. Claude n'est pas dans l'arithmétique VAT. Claude classe les lignes, suggère des rapprochements, génère et édite les modules Python déterministes qui font les calculs. Le calcul réel de Box 1 à Box 9 est une fonction pure avec des tests unitaires. La soumission HMRC nécessite une porte d'approbation humaine. Le rapport d’essais à sec est la source de vérité pour l’approbation. Si je ne peux pas expliquer pourquoi un nombre est ce qu'il est en regardant le code et les lignes classées, je ne le soumets pas.

Il s’agit d’une règle stricte car la finance est réglementée et « l’IA l’a fait » n’est pas une défense sous MTD. Le long article explique plus en détail comment tracer cette ligne dans votre propre implémentation.

Ce qu'il m'a coûté de construire et ce qu'il m'a coûté de fonctionner

Le temps de construction était d'environ une semaine de soirées ciblées - principalement consacrées à la normalisation du schéma, aux règles du classificateur et à l'écriture de tests pour le moteur. La danse HMRC MTD OAuth était la partie la plus lente ; Courir d’abord contre le bac à sable valait chaque minute.

Pour fonctionner, chaque trimestre me coûte environ : mon abonnement Claude Code (déjà payé pour d'autres travaux) plus quelques centimes d'utilisation de jetons pour le classificateur. Le HMRC API lui-même est gratuit. Le moteur VAT et le journal d'audit s'exécutent localement sur mon Mac.

Avertissement important

Je suis ingénieur, pas expert-comptable. Cet article ne constitue pas un conseil fiscal. Avant d'exécuter quoi que ce soit de ce genre sur votre véritable compte HMRC, demandez à un comptable enregistré au Royaume-Uni d'examiner votre première déclaration de bout en bout. Utilisez le HMRC MTD bac à sable jusqu'à ce que vous et votre comptable soyez tous les deux heureux. Le coût d’une mauvaise soumission VAT est bien plus élevé que le coût d’une heure de travail d’un comptable.

Lire la version longue

Si vous voulez une image complète - le schéma CREATE TABLE exact, les invites Claude Code, le moteur Python déterministe avec tests unitaires, le flux HMRC MTD OAuth, les en-têtes de prévention de la fraude et une section approfondie sur les cas extrêmes (protocole Brexit / NI, autoliquidation, exemption partielle, régime forfaitaire, modifications de taux en cours de trimestre, factures multidevises, notes de crédit, dépôts) - lisez le long article. C'est la version que j'aurais voulu lire avant de commencer.

Regardez le Procédure pas à pas YouTube, abonnez-vous aux didacticiels de suivi (flux bancaires d'importation automatique, OCR pour les reçus, cron programmé + approbation Slack) et rappelez-vous : pas de conseils fiscaux, approbation du comptable requise.