Creación de un sistema de devolución VAT con Claude Code a partir de su base de datos de facturas y gastos

Un compañero breve y de lectura rápida. Para obtener una inmersión completa de aproximadamente 5000 palabras con código, indicaciones, esquema, un tutorial de HMRC MTD y casos extremos, lea el artículo largo.

VAT trimestral fue la peor parte de mi mes

Cada trimestre, una pequeña empresa del Reino Unido debe presentar una declaración VAT: nueve cajas de números (ventas, compras, VAT vencido, VAT recuperable, productos de la UE si se encuentra en Irlanda del Norte, totales, neto) y enviarlos a través de HMRC Making Tax Digital (MTD). Durante años, la mía se veía así: abrir la tabla de facturas en Postgres, exportar un CSV, pegarlo en Excel, clasificar manualmente unos cientos de filas, ejecutar fórmulas, copiar nueve números en un puente MTD de terceros, hacer clic en Enviar, espero.

Funcionó, pero fue lento y con pérdidas. Los recibos desaparecieron. Los cambios de tipos a mitad del trimestre rompieron las fórmulas. Un error tipográfico en una clasificación VAT podría moverse Box 5 por cientos de libras. Y la pista de auditoría fue "créanme, tenía una hoja de cálculo".

Este año reconstruí todo como un pequeño proyecto Claude Code que lee mis facturas + base de datos de gastos, clasifica cada línea, calcula los nueve cuadros, ejecuta en seco un PDF y solo luego lo envía a HMRC MTD, con una puerta de aprobación humana. Este blog es la versión corta. El artículo extenso tiene las indicaciones, Python, el flujo HMRC OAuth y las trampas.

Mira el tutorial

Un breve recorrido por el proceso de devolución de VAT que se ejecuta de un extremo a otro con una base de datos de facturas y gastos reales (anonimizada).

El proceso de cinco pasos

1. Conectar. Claude Code obtiene un solo lectura Conexión DB a mis facturas y tablas de gastos. Nunca tiene acceso de escritura a los datos de origen. Los CSV de Stripe, Wise, Revolut y un par de fuentes bancarias se incluyen en ./imports/.
2. Normalizar. Claude genera y ejecuta un pequeño script de Python que asigna cada esquema fuente a una vista canónica: id, date, supplier_or_customer, gross, net, vat_amount, vat_rate, vat_treatment, country_code, currency, source, run_key. La moneda extranjera se convierte a GBP utilizando la tasa mensual HMRC. Todo el período está marcado por un idempotente. run_key por lo que volver a ejecutarlo es seguro.
3. Categorizar + conciliar. Claude clasifica cada línea en un tratamiento VAT (estándar 20%, reducido 5%, cero, exento, fuera del alcance, inversión del sujeto pasivo, bienes de la UE, servicios de la UE, importación aplazada VAT) utilizando un pequeño vat-rules.md Lo mantengo en el repositorio. También concilia facturas con pagos y señala anomalías (montos netos negativos, números VAT de proveedores faltantes, discrepancias en códigos de países, proveedores que no están registrados en VAT).
4. Calcular. Un módulo Python de función pura: no hay LLM en las matemáticas - lee las filas clasificadas y produce Box 1 a Box 9, además de un informe de prueba en Markdown. El esquema de tarifa plana, la contabilidad de caja y las ramas de contabilidad anual son rutas de código explícitas, no instrucciones rápidas.
5. Entregar. Solo después de que yo (o mi contador) hayamos aprobado el ensayo, la canalización llama al HMRC MTD API. Ficha OAuth2. Encabezados de prevención de fraude. GET obligations para encontrar el período abierto. POST returns con finalised: true. Entonces GET liabilities para confirmar lo que debo y cuando.

Por qué Claude Code en lugar de Xero/QuickBooks/FreeAgent

Honestamente, para la mayoría de las pequeñas empresas, un paquete SaaS para contadores es la respuesta correcta. Tienen certificación HMRC, equipos de soporte y su contador ya los conoce. Entonces, ¿por qué hice esto?

• Ya uso Claude Code todos los días para trabajos de software. El costo marginal de usarlo también para ensamblar un oleoducto VAT es pequeño.
• Mis datos son locales. La base de datos de facturas nunca sale de mi máquina. El clasificador recorre filas; las matemáticas son Python local; sólo los últimos nueve números van a HMRC. Sin inquilinos de SaaS, sin terceros.
• Quería control total de las reglas de categorización. Parte de mi combinación de proveedores es incómoda (servicios de la UE, importación pospuesta de VAT, un par de casos extremos con tasa cero). Codificar esas reglas en vat-rules.md + un módulo de Python es más rápido para mí que configurar un SaaS.
• La pista de auditoría es mía. Cada mensaje de Claude y cada diferencia se guarda en un registro de solo anexo junto con la instantánea del período firmado. Si HMRC alguna vez me lo pide, puedo realizar el cálculo exacto en segundos.

Si aún no usa Claude Code o no le gustaría leer Python a medianoche, use Xero/QuickBooks/FreeAgent. Esta no es una recomendación para implementar su propio sistema VAT. Es una historia de lo que es posible cuando lo haces.

Dónde está y dónde no está el LLM

Esta es la parte sobre la que quiero hablar en voz alta. Claude no está en la aritmética VAT. Claude clasifica líneas, sugiere conciliaciones y genera y edita los módulos deterministas de Python que hacen los cálculos. El cálculo real de Box 1 a Box 9 es una función pura con pruebas unitarias. El envío de HMRC requiere una puerta de aprobación humana. El informe de prueba es la fuente de verdad para la aprobación. Si no puedo explicar por qué un número es lo que es al observar el código y las filas clasificadas, no lo envío.

Esta es una regla estricta porque las finanzas están reguladas y "la IA lo hizo" no es una defensa según MTD. El artículo largo entra en más detalles sobre cómo trazar esta línea en su propia implementación.

Lo que me costó construir y lo que me cuesta ejecutar

El tiempo de construcción fue aproximadamente una semana de tardes concentradas, dedicadas principalmente a la normalización de esquemas, las reglas del clasificador y la redacción de pruebas para el motor. El baile HMRC MTD OAuth fue la parte más lenta; Correr primero contra la caja de arena valió la pena cada minuto.

Para ejecutarlo, cada trimestre me cuesta aproximadamente: mi suscripción Claude Code (ya pagada por otro trabajo) más unos pocos centavos en uso de tokens para el clasificador. El HMRC API en sí es gratuito. El motor VAT y el registro de auditoría se ejecutan localmente en mi Mac.

Descargo de responsabilidad importante

Soy ingeniero, no contador público. Este artículo no es asesoramiento fiscal. Antes de ejecutar algo como esto en su cuenta HMRC real, consiga que un contador registrado en el Reino Unido revise su primera declaración de principio a fin. Utilice el HMRC MTD salvadera hasta que usted y su contador estén contentos. El costo de un mal envío de VAT es mucho mayor que el costo de una hora de tiempo de un contador.

Lea la versión larga

Si desea obtener una imagen completa: el esquema CREATE TABLE exacto, los mensajes Claude Code, el motor Python determinista con pruebas unitarias, el flujo OAuth HMRC MTD, encabezados de prevención de fraude y una sección detallada sobre casos extremos (protocolo Brexit/NI, inversión de cargo, exención parcial, esquema de tarifa plana, cambios de tarifas a mitad de trimestre, facturas multidivisa, notas de crédito, depósitos), lea el artículo largo. Es la versión que hubiera querido leer antes de empezar.

Mira el Tutorial de YouTube, suscríbase para recibir tutoriales de seguimiento (importación automática de fuentes bancarias, OCR para recibos, cron programado + aprobación de Slack) y recuerde: no se ofrece asesoramiento fiscal, se requiere la aprobación del contable.