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

Esta es la inmersión profunda en formato largo. Para obtener una versión más rápida y de lectura rápida, consulte el publicación de blog complementaria.

1. Por qué construí esto

Cada pequeña empresa del Reino Unido con un volumen de negocios imponible superior al umbral de registro VAT tiene que calcular y presentar una declaración VAT, generalmente trimestralmente, a través del servicio Making Tax Digital (MTD) de HMRC. Nueve cajas numeradas. Salida VAT menos entrada VAT. Paga el importe neto o reclama el reembolso. Fácil en teoría; En la práctica, es un castigo cuando sus facturas se encuentran en Postgres, sus recibos de gastos son archivos PDF de veinte proveedores diferentes, sus extractos bancarios son CSV de Wise y Revolut y sus líneas en moneda extranjera deben expresarse en libras a la tasa mensual correcta.

Durante algunos años salí adelante con una hoja de cálculo gigante, un recordatorio de calendario y un pequeño acto de fe. Cada trimestre tomó aproximadamente medio día, la mayor parte del cual fue manipulación de datos: exportar un CSV desde la base de datos de facturas, pegarlo en Excel, clasificar manualmente unos cientos de filas, verificar fórmulas, copiar nueve números en un puente MTD de terceros, hacer clic en Enviar. La pista de auditoría fue "créanme, tenía una hoja de cálculo". Los cambios de tasas a mitad del trimestre lo rompieron. Los recibos desaparecieron. Una clasificación fuera de lugar podría impulsar Box 5 de descuento en cientos de libras.

Reconstruí el oleoducto este año como un pequeño Claude Code proyecto que se comunica directamente con mi base de datos de facturas y gastos, clasifica cada línea, calcula Box 1 a Box 9 con un motor Python determinista, ejecuta en seco la devolución como un informe Markdown y, solo después de que un humano aprueba, la envía a HMRC MTD. Ahora me lleva alrededor de una hora todo el trimestre, la mayor parte de la cual estoy revisando el simulacro con mi contador. La pista de auditoría es un repositorio de git. Las matemáticas se prueban por unidad. El clasificador es un archivo Markdown documentado. La presentación está cerrada.

Este artículo es la versión larga. Avisos, Python, esquema, el flujo HMRC OAuth, los casos extremos. Si primero quieres la versión corta, lee el blog complementario.

2. Introducción HMRC MTD (y descargo de responsabilidad)

Making Tax Digital para VAT es el requisito de HMRC de que las empresas registradas en VAT mantengan registros digitales y presenten declaraciones a través de software compatible a través de un API documentado en lugar de escribir números en el formulario web gov.uk. El API es OAuth2, requiere encabezados HTTP de prevención de fraude que identifiquen el dispositivo de origen y está disponible en una zona de pruebas gratuita antes de tocar la producción en vivo.

La devolución en sí es de nueve cajas: Box 1 es VAT debido a las ventas y otros productos; Box 2 es VAT debido a adquisiciones de bienes de los estados miembros de la UE (relevante para las empresas de Irlanda del Norte según el protocolo NI); Box 3 es el VAT total adeudado (Box 1 + Box 2); Box 4 es VAT recuperable en compras (ingrese VAT); Box 5 es el VAT neto para pagar o reclamar (Box 3 - Box 4); Box 6 son las ventas totales excluyendo VAT; Box 7 son compras totales excluyendo VAT; Box 8 es el valor total de los bienes suministrados a los estados miembros de la UE (nuevamente, solo NI); Box 9 es el valor total de las adquisiciones de los estados miembros de la UE (solo NI). Existen variantes del sistema (régimen a tanto alzado, contabilidad de caja, contabilidad anual) que cambian cómo llegas a los números pero no a la forma de la caja.

Descargo de responsabilidad. Soy ingeniero de software, no contador público. Este artículo es no asesoramiento fiscal. Las reglas exactas para la clasificación VAT, la exención parcial, el esquema de tarifa plana, las reglas de lugar de suministro para los servicios digitales, el tratamiento posterior al Brexit de los bienes y servicios de la UE y el protocolo NI cambian con el tiempo y dependen de sus circunstancias específicas. Antes de ejecutar algo como esto en una cuenta HMRC real, solicite que un contador registrado en el Reino Unido revise su primera declaración de principio a fin. Para conocer la norma autorizada sobre cualquier caso límite específico, consulte el Aviso 700 HMRC VAT y los avisos relacionados en el sitio web gov.uk. El costo de una hora de tiempo de su contador es mucho menor que el costo de una mala presentación.

3. El modelo de datos

Todo lo posterior depende de la forma de dos tablas: facturas emitidas (ventas) y gastos registrados (compras). Mantengo el mío en Postgres pero la misma forma funciona en MySQL o SQLite. El 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()
);

Las columnas no obvias son vat_treatment, fx_rate_to_gbpy los códigos de país. El tratamiento es una pequeña enumeración utilizada tanto por el clasificador como por el motor; el código de país impulsa la lógica de inversión impositiva y de adquisición en la UE; El tipo de cambio le permite mantener las facturas en moneda extranjera en su moneda original y aún volver a expresarlas en GBP para los totales de la caja.

Rellenar esas columnas en una tabla de facturas heredadas es la parte más lenta del proyecto. Claude Code puede generar la migración; aún necesita clasificar manualmente los casos extremos incómodos.

4. Por qué Claude Code (y no Xero/QuickBooks/FreeAgent)

Para la mayoría de las pequeñas empresas del Reino Unido, la respuesta es, genuinamente, utilizar software empaquetado. Xero, QuickBooks, FreeAgent y Sage tienen envío MTD certificado por HMRC, interfaces de usuario decentes y contadores que ya los conocen. No debe utilizar su propio sistema VAT a menos que tenga una razón clara.

Mis razones eran estrechas pero reales. Ya uso Claude Code todos los días para trabajar con software, por lo que el esfuerzo marginal para usarlo también para VAT fue pequeño. Mi base de datos de facturas vive en mi propia máquina; Prefiero que no se refleje en un inquilino de SaaS. Mi combinación de proveedores es incómoda (servicios de la UE con cargo invertido, importación pospuesta VAT, casos extremos ocasionales con tasa cero) y codificar las reglas en un único archivo Markdown más un módulo Python resultó ser más rápido que configurar un SaaS para manejarlas. Y la pista de auditoría que obtengo de un repositorio de git (cada indicador del clasificador, cada diferencia, cada instantánea del período firmado) es exactamente la pista de auditoría que quiero.

Claude Code se adapta bien a esto por tres razones. En primer lugar, funciona directamente con un proyecto en disco: puede leer mi esquema, los informes de prueba del trimestre anterior, el archivo de reglas y el motor Python, y proponer ediciones en contexto. En segundo lugar, es bueno en los aburridos andamios: scripts de migración, importadores de CSV, informes de conciliación, accesorios de pytest. En tercer lugar, cuando clasifica una línea, explica su razonamiento en un lenguaje sencillo, que es exactamente lo que quiero revisar antes de firmar la declaración. La matriz de decisiones en la parte inferior del diagrama de flujo de trabajo a continuación es la versión honesta de esta compensación.

5. Arquitectura y flujo de trabajo

El oleoducto tiene cinco carriles para nadar. Fuente es acceso de solo lectura a las tablas de facturas y gastos, además de una carpeta desplegable para CSV de Stripe, Wise y fuentes bancarias. Ingerir + Normalizar es un pequeño script de Python generado por Claude que asigna cada esquema fuente a una vista canónica, convierte moneda extranjera a GBP a la tasa mensual HMRC, aplica un filtro de rango de fechas y estampa cada fila con un idempotente. run_key por lo que las repeticiones son seguras. Categorizar + Conciliar es el clasificador Claude Code: recorre cada fila canónica, elige un vat_treatment de la enumeración documentada usando reglas en vat-rules.md, concilia facturas con pagos y señala anomalías (neto negativo, número VAT de proveedor faltante, discrepancia en el código de país, proveedores que deberían estar registrados en VAT pero no lo están). motor VAT es un módulo Python puro que lee las filas clasificadas y calcula Box 1 a Box 9 de forma determinista; las sucursales de tarifa plana, efectivo y anual son rutas de código explícitas. Enviar + Auditoría es la llamada HMRC MTD API (OAuth2, encabezados de prevención de fraude, zona de pruebas primero), cerrada detrás de un paso de aprobación humana, con la instantánea del período firmado y el registro de clasificador completo escrito en una carpeta de auditoría de solo anexo retenida durante seis años.

6. Compilación paso a paso con Claude Code

Este es el flujo de trabajo que realmente utilicé. Cinco indicaciones. Los limpié para este artículo; Los originales son más desordenados.

Mensaje 1: normalizador. "Mira el invoices y expenses mesas en schema.sql. Generar un módulo de Python normalise.py que lee ambas tablas usando psycopg (rol de solo lectura vat_reader), se restringe al rango de fechas 2026-01-01 a 2026-03-31y emite una lista de dictados canónicos con claves: id, source, date, party, gross, net, vat_amount, vat_rate, vat_treatment, country, currency, fx_rate, run_key. Usar Decimal, no flotar. Incluya una cadena de documentación y un __main__ bloque que imprime un resumen."

Claude devolvió un módulo limpio con Decimal, SQL parametrizado, un build_run_key() que codifica (period_start, period_end, esquema, esquema_versión) en una cadena hexadecimal estable y una CLI basada en clics. Edité dos nombres de campos y acepté el resto.

Mensaje 2: clasificador. "Leer vat-rules.md y escribe classify.py. Para cada fila canónica de normalise.py, colocar vat_treatment a uno de: estándar, reducido, cero, eximir, fuera del alcance, carga inversa, bienes-de-la-ue, servicios-ue, importación pospuesta. Si la fila ya tiene un no vacío vat_treatment, déjalo así y grábalo como en conserva. De lo contrario, decida a partir del código de país, el número VAT del proveedor, la categoría y el monto, y escriba una oración. reason en cada fila. Las anomalías (neto negativo, falta de proveedor VAT para un proveedor del Reino Unido por encima del umbral de registro, falta de coincidencia de países) van a un informe separado. anomalies.json para revisión humana. No mute la base de datos de origen."

El clasificador en sí es una función pequeña, principalmente basada en reglas, con una rama respaldada por LLM para categorías de gastos ambiguas. Fundamentalmente, nunca escribe en la base de datos de origen: emite un archivo JSON clasificado que lee el motor. Si no estoy de acuerdo con una clasificación, edito el JSON; el siguiente ensayo lo retoma.

Mensaje 3: motor. "Escribir engine.py como función pura: def compute_boxes(rows: list[Row], scheme: Scheme) -> BoxTotals. Sin E/S. Sin LLM. BoxTotals es una clase de datos congelada con Box 1 a Box 9 como Decimal valores a 2 dp. Agregar ramas explícitas para standard, flat_rate, cash, y annual esquemas. El esquema estándar es de acumulación: las ventas de VAT contribuyen a Box 1, las compras de VAT a Box 4. Las facturas de cargo revertido se suman tanto a Box 1 como a Box 4. La importación pospuesta VAT se suma tanto a Box 1 como a Box 4. Las adquisiciones en la UE para los negocios NI se incluyen en Box 2 y Box 9. Redondear por los totales de la caja, nunca por fila. Escribe un documento que vincule cada rama con su regla."

Mensaje 4: informe de ensayo. "Escribir dryrun.py que llama compute_boxes() y emite un informe Markdown: encabezado con período y esquema, una tabla de Box 1 a Box 9 con las etiquetas canónicas, una sección por grupo clasificador que enumera las 10 filas principales por valor bruto, una sección de anomalías y un pie de página con el run_key y un SHA-256 del JSON clasificado. Guardar en ./audit/<period>/dryrun.md."

Mensaje 5: remitente. "Escribir submit.py contra el HMRC MTD VAT API v1.0. Utilice el flujo de código de autorización OAuth2 con PKCE. Leer el token de acceso de ~/.vat/token.json; actualizar si ha caducado. Encabezados de prevención de fraude requeridos según lo documentado por HMRC; sacarlos de fraud_headers.py. Predeterminado en la zona de pruebas https://test-api.service.hmrc.gov.uk. Pasos: GET /organisations/vat/{vrn}/obligations?status=O, encuentre el período coincidente, solicite al operador que confirme mostrando el resumen del ensayo y luego POST /organisations/vat/{vrn}/returns con finalised: true. Imprime el receiptId. Nunca llame en vivo a menos que HMRC_ENV=live está configurado y los tipos de operador ENTREGAR."

Cinco indicaciones, cuatro archivos y un pequeño documento de reglas de Markdown. El tiempo total de construcción fue tal vez una semana de veladas centradas, la mayor parte de las cuales fueron las reglas del clasificador y el baile HMRC OAuth.

7. El motor VAT

El motor es la parte deliberadamente aburrida. Es una función pura con pruebas unitarias y sin IA. Esta es la 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),
    )

Dos cosas a tener en cuenta. En primer lugar, el total de cada caja se cuantifica una vez al final. El redondeo por fila pierde centavos y HMRC no perdona los totales que no se concilian. En segundo lugar, el motor es totalmente determinista: la misma entrada, la misma salida, siempre. Esa es la propiedad que me permite realizar pruebas unitarias y confiar en el ensayo.

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")

Con esto implementado, cada regresión queda atrapada en CI antes de que llegue al informe de simulacro. Claude puede ayudarme a escribir más pruebas; no puede cambiar el motor sin pasar esas pruebas.

8. Vídeo de demostración

A continuación se muestra un breve recorrido por el proceso de principio a fin con una base de datos de gastos y facturas reales (anónimas) durante un trimestre: normalización, clasificación, ejecución en seco y luego un envío MTD de zona de pruebas. Todo el bucle dura un par de minutos.

9. Envío HMRC MTD

Esta es la parte que la mayoría de los artículos pasan por alto. El MTD VAT API en sí está bien documentado y es gratuito, pero hay tres cosas que debes hacer bien antes de llamar POST returns.

OAuth2 y tokens. Registre una aplicación en el centro de desarrolladores HMRC; obtienes un ID de cliente, un secreto de cliente y un URI de redireccionamiento. El flujo es código_autorización con PKCE: abra el navegador en la página de consentimiento de HMRC, el usuario inicia sesión con sus credenciales de Government Gateway y autoriza su aplicación con su número de registro VAT (VRN), HMRC redirige nuevamente con un código de autorización, lo cambia por un token de acceso + token de actualización. Almacénelos en caché con permisos razonables en el disco. El token de acceso es de corta duración; el token de actualización es mucho más largo.

Encabezados de prevención de fraude. HMRC requiere un conjunto documentado de encabezados HTTP que identifiquen el dispositivo de origen en cada llamada API: zona horaria, geometría de pantalla, ID de usuario, IP pública, direcciones MAC, método de conexión del cliente, etc. La lista y el formato exactos se encuentran en la documentación del desarrollador de HMRC (consulte el Aviso 700 de HMRC VAT y las especificaciones de prevención de fraude relacionadas para la regla autorizada). Hazlos mal y obtendrás un 403 con un vago error. Hágalo bien y la llamada se realizará. los guardo en fraud_headers.py y hacer valer su presencia en las pruebas.

Primero la zona de pruebas. HMRC proporciona una zona de pruebas gratuita en test-api.service.hmrc.gov.uk con stub VRN y obligaciones stub. Ejecute todo su proceso de principio a fin en la zona de pruebas hasta que haya enviado una declaración falsa, haya recibido una identificación de recibo falsa y haya confirmado el cambio de sus obligaciones. Sólo entonces das la vuelta HMRC_ENV=live. Mi remitente se niega a llamar en vivo a menos que la variable de entorno esté configurada y el operador escriba SUBMIT en el aviso. No existe una ruta de ejecución automática para vivir. El costo de un único envío en vivo incorrecto es mucho mayor que el costo de una iteración más del sandbox.

La llamada real al camino feliz es breve: GET obligations con status=O Para encontrar el período abierto, muestre el informe de prueba, solicite al operador que confirme y luego POST returns con los nueve números de casilla, el periodKey de la obligación, y finalised: true. Guarde la respuesta, escriba el ID del recibo en la carpeta de auditoría y listo.

10. Seguridad, auditoría y cumplimiento

Tres reglas que no seguiré. Primero, Claude no está en la aritmética.. El clasificador sugiere tratamientos y el LLM puede editar Python y reglas, pero los totales del cuadro se producen mediante una función pura con pruebas unitarias. "La IA lo hizo" no es una defensa según MTD. Segundo, Cada presentación está controlada por un humano.. El informe de prueba es la fuente de verdad para la aprobación. Si no puedo explicar un número de las filas clasificadas y el código del motor, no lo envío. Tercero, la pista de auditoría es sólo para anexar. Cada JSON clasificado, cada informe de prueba, cada mensaje, cada diferencia y el ID del recibo HMRC final para el período se escriben en ./audit/<period>/ y comprometido con un repositorio privado de git. HMRC requiere seis años de registros; las mías son instantáneas firmadas.

Dos prácticas más que recomendaría incluso si no adoptas el resto. Ejecute la conexión de base de datos de origen como función de solo lectura con privilegios mínimos: no UPDATE, No DELETE, No DROP. Mantenga el cliente HMRC en secreto y los tokens de acceso fuera del repositorio utilizando un administrador secreto o un archivo 0600 en su directorio de inicio. La cuestión es hacer que los accidentes sean imposibles mediante la construcción, no sólo mediante políticas.

11. Casos extremos

VAT es un impuesto regulado que ha sido editado por todos los gobiernos del Reino Unido desde 1973, con una superposición posterior al Brexit y un protocolo de Irlanda del Norte encima. Los casos extremos son reales. Una lista no exhaustiva de los que maneja mi motor:

• Brexit e Irlanda del Norte. Las empresas de Gran Bretaña ya no completan Box 8 o Box 9. Las empresas NI todavía lo hacen para bienes (no servicios) bajo el protocolo NI. el motor toma is_ni_business como parámetro y se ramifica en consecuencia. Consulte el Aviso 700 de HMRC VAT para conocer la regla autorizada.
• Carga inversa. Los servicios comprados a un proveedor fuera del Reino Unido (y ciertos servicios nacionales de la industria de la construcción) se contabilizan bajo el método de inversión del sujeto pasivo: se suma una producción nocional VAT a Box 1 y se reclama la misma cantidad en Box 4. El efecto neto sobre el efectivo es cero; El efecto neto sobre el rendimiento es que dos cajas se mueven juntas.
• Importación pospuesta VAT. Para productos importados desde fuera del Reino Unido, difiere el VAT de importación hasta su próxima devolución en lugar de pagarlo en la frontera. El tratamiento es similar a la inversión del cargo en la devolución.
• Exención parcial. Si realiza suministros tanto sujetos a impuestos como exentos, solo puede reclamar el insumo VAT en la medida en que se relacione con suministros sujetos a impuestos. Existen métodos estándar y especiales; este es el rincón que más a menudo necesita un contador. No intente codificar reglas de exención parcial en un archivo Markdown.
• Régimen de tarifa plana. Usted cobra VAT a la tarifa estándar pero paga a HMRC un porcentaje fijo de la facturación bruta y, por lo general, no puede reclamar el VAT de entrada. El motor tiene una rama separada para esto e ignora la mayor parte de la clasificación por fila.
• Facturas multidivisa. Convierta cada fila a GBP al tipo de cambio vigente en la fecha correspondiente. HMRC publica tarifas promedio mensuales; También puede utilizar la tasa al contado. Sea consistente. El fx_rate_to_gbp La columna almacena la tasa real aplicada por fila.
• Notas de crédito. Una nota de crédito es una factura negativa. Reduce Box 1 y Box 6 (o Box 4 y Box 7 si es un crédito de compra). Asegúrate de que tu net_amount y vat_amount pueden salir negativos y que el motor los suma correctamente.
• Depósitos y pagos fraccionados. El punto impositivo puede ser cuando se recibe el depósito, no cuando se emite la factura final. La contabilidad de caja puede simplificar esto.
• Cambios de tasas a mitad de trimestre. Históricamente raro, pero posible. Almacene la tasa por fila, no como una constante global.

12. Costo

Números honestos. tiempo de construcción Fue aproximadamente una semana de tardes concentradas; llámelo de 25 a 30 horas. La mayor parte fue la normalización del esquema, las reglas del clasificador y la redacción de las pruebas del motor; el baile HMRC OAuth fue el segundo fragmento más grande. Costo de funcionamiento por trimestre es pequeño: mi suscripción Claude Code existente (ya pagada por otro trabajo de software), unos pocos centavos en el uso del token clasificador y cero libras por el HMRC API. El motor y el registro de auditoría se ejecutan localmente en mi Mac. Tiempo del revisor por trimestre Es aproximadamente una hora, y la dedico principalmente a leer el ensayo con mi contador. Compare eso con aproximadamente medio día de manipulación de hojas de cálculo con el flujo de trabajo anterior y el tiempo ahorrado amortiza el costo de construcción dentro del primer año.

Si valorara esto como un proyecto por el cual le pagaría a otra persona para que lo construyera, estaría en el estadio de cuatro cifras en tarifas de consultoría, razón por la cual un paquete SaaS de veinte a cincuenta libras al mes es casi siempre la respuesta correcta para la mayoría de las empresas. La pregunta interesante no es "¿es más barato que Xero?" - normalmente no lo es - pero "¿es más preciso, más auditable y más fácil de razonar para mí?". Para mí la respuesta es sí.

13. ¿Qué sigue y conclusión?

Las siguientes piezas que quiero agregar son: importación automática de fuentes bancarias (Open Banking AISP), OCR para archivos PDF de proveedores para que la URL del recibo se convierta en una línea escaneada real, un cron programado + flujo de aprobación de Slack para no tener que recordar las fechas límite, y una extensión de autofacturación para vendedores del mercado. Ninguno de ellos cambia la forma central del oleoducto. Todas son decoraciones en el mismo diagrama de cinco carriles.

La lección más importante, al menos para mí, es qué tan bien un pequeño proyecto Claude Code maneja la aburrida mitad de un flujo de trabajo regulado. La mitad aburrida es la mayor parte del trabajo: normalización de esquemas, importadores de CSV, informes de conciliación, accesorios, reglas de casos extremos, registro de auditoría. Claude es excelente en todo eso. La mitad determinista (las matemáticas reales, la presentación real) permanece en Python simple con pruebas unitarias y una puerta de aprobación humana, exactamente donde pertenece.

Descargo de responsabilidad, de nuevo. Este artículo no es asesoramiento fiscal. Antes de apuntar algo como esto a una cuenta HMRC real, solicite que un contador registrado en el Reino Unido revise su primera declaración de principio a fin. Ejecute contra el entorno limitado HMRC MTD hasta que usted y su contador estén seguros. Para conocer la norma autorizada sobre cualquier tratamiento VAT específico, consulte el Aviso 700 de HMRC VAT y los avisos relacionados en el sitio web gov.uk. Si desea la versión corta de todo esto, el publicación de blog complementaria es una lectura de cinco minutos; de lo contrario, suscríbete y seguiré escribiendo a medida que la pila madure.

Instantánea de SEO para este artículo

• Título SEO: Construya un sistema de retorno VAT con Claude Code
• Meta descripción: Utilice Claude Code para leer su base de datos de facturas y gastos, clasificar VAT, calcular HMRC Box 1 a 9, realizar un ensayo y luego enviarlo a MTD: motor determinista, aprobación humana.
• Palabras clave principales: código claude, iva, hmrc, mtd, contabilidad, automatización, pitón, ai-agent, finops, pequeña empresa
• Twitter / X (menos de 280 caracteres): Reconstruí mi declaración VAT del Reino Unido como un proyecto Claude Code: facturas Postgres + gastos DB a HMRC Box 1 a 9, motor Python determinista, envío MTD primero en sandbox, puerta de aprobación humana. Redacción completa + flujo de trabajo SVG + vídeo de demostración. No asesoramiento fiscal. #ClaudeCode #VAT #HMRC #MTD
• Publicación de LinkedIn: Este año reconstruí mi declaración trimestral de VAT en el Reino Unido como un pequeño proyecto Claude Code. Lee mi base de datos de facturas y gastos de solo lectura, clasifica cada línea según el tratamiento VAT usando un archivo de reglas documentadas, calcula HMRC Box 1 a 9 con un motor Python determinista (sin LLM en la aritmética) y solo después de cerrar el simulacro se envía a través de HMRC MTD API: primero la zona de pruebas, encabezados de prevención de fraude, el flujo completo de OAuth2. Ahora el trimestre completo dura aproximadamente una hora. El artículo completo con indicaciones, esquema, código del motor, casos extremos y una historia honesta de costos está en Workstation. No asesoramiento fiscal; Consiga que un contador revise su primera declaración.