La renta con un agente de IA: hacienda-cli descarga los datos de la AEAT e itera sobre los errores de EDFI hasta que el XML cuadra

En dos frases

Javier de la Torre, cofundador de la empresa geoespacial CARTO, cuenta que hizo su declaración de la renta de 2025 con un agente de IA y que publicó hacienda-cli, una pequeña herramienta de línea de comandos de código abierto que le da al agente las dos cosas que le faltaban: los datos que la Agencia Tributaria ya tiene de él y la validación de la propia AEAT sobre un XML de la declaración. Es un testimonio en primera persona sin cifras auditadas, pero el repositorio publica todo lo necesario para replicar el método (el CLI, los esquemas oficiales, un CLAUDE.md detallado y un skill de Claude) y se detiene a propósito antes de presentar o firmar.

Quién lo hace y por qué importa

La mayoría de los casos de este directorio son empresas que cierran su contabilidad. Este es de un hogar, y el problema es muy español: la AEAT ofrece el borrador ya rellenado en Renta WEB, pero quien tiene brokers extranjeros, fondos, criptomonedas, dividendos con retención en origen o ha vendido un inmueble acaba metiendo a mano decenas de operaciones en un formulario interminable. En su artículo, publicado como docs/index.md dentro del repositorio, de la Torre distingue dos fases: reunir la documentación, donde un agente «ya es una maravilla», y meterlo todo en la web de Hacienda, que describe como un infierno lento, engorroso y propenso a errores, sin forma de saber si tus cifras cuadran con las de Hacienda hasta el final.

Su idea es que la segunda fase no necesita a una persona tecleando. La AEAT ya admite la declaración como fichero XML generado externamente a través de un servicio llamado EDFI, documentado en sus páginas de ayuda técnica para quienes desarrollan software. EDFI recalcula todas las casillas en el servidor y devuelve errores cuando falta algo o algo no cuadra. Si un agente puede escribir ese XML y leer esos errores, puede iterar por su cuenta.

No tiene interés comercial en un producto fiscal: el README advierte de que la herramienta no es oficial, no tiene relación con la AEAT y se ofrece «tal cual». En la publicación de LinkedIn pide opiniones «a mí y a CARTO» a quienes trabajan en herramientas para agentes. Contrastamos el repositorio con esa publicación y sus comentarios, con el Show HN de Hacker News y con la documentación de EDFI de la AEAT.

Herramientas y arquitectura

El principio de diseño está escrito al principio del CLAUDE.md: el CLI es «deliberadamente mínimo» y toda la lógica fiscal es responsabilidad del agente, no del CLI. Tiene cinco comandos:

Comando	Qué hace
hacienda login	Abre un Chromium visible; te autenticas con Cl@ve y el navegador queda abierto
hacienda download 100	Guarda tus datos fiscales en HTML y el borrador actual en PDF
hacienda validate 100 decl.xml	Valida el XML contra el XSD oficial en local con xmllint
hacienda upload 100 decl.xml	Importa el XML en EDFI y muestra errores y avisos
hacienda info 100	Muestra las rutas del esquema, el diccionario de campos y las URL de la AEAT

Por dentro es Node.js y TypeScript con Playwright. Dos restricciones marcan la arquitectura. La primera: la AEAT detecta los navegadores headless, así que la ventana tiene que verse. La segunda: la sesión vive en ese proceso del navegador, de modo que login deja Chromium abierto y download y upload se conectan a él por el protocolo de DevTools de Chrome. El CLI no guarda credenciales.

El repositorio incluye además el esquema oficial del modelo 100 de la campaña 2025 (Renta2025.xsd, con una copia corregida porque las expresiones regulares de la AEAT rompen xmllint) y un diccionario de unos 4.000 campos con su XPath, tipo y etiqueta. Encima va la capa de conocimiento para el agente: un CLAUDE.md con el esqueleto del XML, los tipos de datos, los valores de los enumerados, el orden estricto de las secciones y el mapeo de campos para acciones, fondos, acciones no cotizadas, ventas de inmuebles, criptomonedas, alquileres, planes de pensiones y doble imposición; y un skill, .claude/skills/irpf-declaracion/SKILL.md, que lo convierte en un flujo de seis fases.

Cómo funciona, paso a paso

1. Entrar. Ejecutas hacienda login y completas tú el acceso con Cl@ve. El README dice que el flujo documentado solo admite Cl@ve (el README antiguo de npm mencionaba también el certificado digital).
2. Descargar lo que sabe Hacienda. hacienda download 100 genera datos-fiscales-100-2025.html y borrador-100-2025.pdf. Una pull request de la comunidad añadió un aviso claro para la primera visita de cada campaña, cuando Renta WEB pide decisiones personales (estado civil, hijos, datos trasladables) que no se pueden automatizar.
3. Analizar y preguntar. El skill pide al agente que resuma del HTML los rendimientos del trabajo, intereses y dividendos, ventas, reembolsos de fondos, inmuebles, donativos e hipotecas, y que pregunte por lo que la AEAT no suele tener: brokers extranjeros (DEGIRO, Interactive Brokers, eToro, Trading 212, XTB, Revolut), exchanges de criptomonedas, alquileres, inversiones en startups, trabajo en el extranjero y aportaciones a planes de pensiones.
4. Completar los datos. Para cada operación, el agente reúne fechas y valores de adquisición y transmisión a partir de los informes anuales de los brokers, los CSV de los exchanges (FIFO), las escrituras o los certificados de los planes.
5. Escribir el XML. El agente genera un fichero conforme al XSD: codificación ISO-8859-1, secciones en orden estricto dentro de TomaDatosAmpliada, lógicos como 0/1, fechas dd/mm/aaaa y trampas como que FECHA1NA es la fecha de transmisión en las acciones no cotizadas pero la de adquisición en los inmuebles.
6. Validar en local y subir con resultados mínimos. La primera subida lleva los Resultados a cero a propósito.
7. Iterar sobre los errores ERES. EDFI recalcula todas las casillas y responde con mensajes ERES que indican el valor que ha calculado. El agente copia esos valores en Resultados y vuelve a subir hasta que se acepta. Los errores que no son ERES (codificación, datos del cónyuge, fechas) figuran en el skill con su solución.
8. Revisar y decidir. EDFI muestra el resultado individual y el conjunto, y cuál es más favorable. Lo revisas en el navegador y, si todo cuadra, lo presentas tú a mano.

Cópialo y adáptalo

Todo lo que sigue se reproduce de github.com/jatorre/hacienda-cli en el commit 3536716 (17 de junio de 2026), © 2026 Javier de la Torre y colaboradores. Sobre la licencia: el archivo LICENSE es MIT, mientras que el README, package.json y las publicaciones del autor dicen AGPL-3.0-or-later. Las dos permiten reproducirlo citando al autor; si redistribuyes código modificado, aplica las condiciones más estrictas de la AGPL hasta que el autor lo aclare. El código es idéntico en las versiones inglesa y española de esta página: los comentarios del autor están en español y los de nuestras plantillas, en inglés. Hemos quitado los importes de ejemplo del CLAUDE.md y usamos cifras redondas propias, marcadas como datos de ejemplo.

Requisitos previos

• Una identidad fiscal española con acceso a Cl@ve y conocimientos suficientes para revisar tú cada casilla.
• Node.js 20 o superior, Git y xmllint (en Debian o Ubuntu, el paquete libxml2-utils; en macOS viene con el sistema).
• Una sesión de escritorio: el navegador tiene que verse, así que no funciona en un servidor sin pantalla.
• Un agente de IA de programación que lea CLAUDE.md y los skills de .claude/skills/ (el repositorio está organizado para Claude Code). Decide antes si quieres enviar tus datos fiscales a ese proveedor: el README avisa de que esa decisión y su riesgo de privacidad son tuyos.

Instalación (del README)

git clone https://github.com/jatorre/hacienda-cli.git
cd hacienda-cli
npm install
npm run build
npm link

npm install descarga también el Chromium de Playwright (postinstall).

El flujo recomendado (del README)

1. hacienda login
2. hacienda download 100
3. Tu agente o tú analizáis:
   - datos-fiscales-100-2025.html
   - borrador-100-2025.pdf
   - documentación externa: bancos, brokers, exchanges, etc.
4. Generáis un XML conforme al XSD oficial
5. hacienda validate 100 decl.xml
6. hacienda upload 100 decl.xml
7. Revisas el resultado en el navegador
8. Si todo cuadra, decides tú si presentarlo manualmente en la AEAT

El skill: fases 4 y 5 (extracto de SKILL.md)

El skill completo está en .claude/skills/irpf-declaracion/SKILL.md y está escrito en inglés. Su cabecera es la línea más importante: no presentar, firmar ni enviar nunca la declaración, solo prepararla y validarla. En el extracto: la fase 4 fija las reglas del XML (codificación, orden, tipos, cónyuge, subtotales, fechas invertidas y resultados mínimos) y la fase 5 describe el ciclo ERES y los errores habituales que no son ERES.

### Phase 4: Generate XML

Read `CLAUDE.md` in the repo root for the complete XSD field mapping and technical reference.

Key rules:
- File encoding: **ISO-8859-1** (convert with `iconv -f UTF-8 -t ISO-8859-1`)
- Element order within TomaDatosAmpliada is strict (xs:sequence) — see CLAUDE.md for order
- `tipo_logico` = `"0"` or `"1"` (NOT "S"/"N")
- `tipo_SINO_Exclusivo` = `"SI"` or `"NO"`
- Dates: `dd/mm/yyyy`
- If married (ECIVIL=2), include `<Conyuge>` in DatosIdentificativos AND a second `<TomaDatosAmpliada titular="3">` with codigoCA
- B11/B13 elements need `valor="total"` attribute
- GPAcciones: G2B_DE = entity name (NOT ISIN), G2B_B = acquisition, G2B_C = gain
- GPOtrosElementos: FECHA1NA = transmission, FECHA2NA = acquisition (reversed!)
- Start with minimal Resultados (BLGGRAV=0, CDIF=0, RESULTADO=0) — EDFI will calculate the correct values

### Phase 5: Upload and Iterate (ERES Cycle)

Convert to ISO-8859-1 and upload:
    iconv -f UTF-8 -t ISO-8859-1 declaracion.xml > declaracion-latin1.xml
    node scripts/edfi-upload.mjs declaracion-latin1.xml

The ERES cycle:
1. First upload with zeroed Resultados → EDFI returns ERES errors with calculated values
2. Parse ERES values: `ERES[FIELD_NAME] ... calculado el valor X`
3. Map ERES fields to the correct Resultados XML elements (see CLAUDE.md for mapping)
4. Update the Resultados section with calculated values
5. Re-upload → if more ERES appear, repeat; if accepted, done

Common non-ERES errors:
- **ENC**: File not ISO-8859-1. Convert with iconv.
- **EXML004**: Missing cónyuge data (NIF, birthdate, sex, CA required if married)
- **100R235**: FECHA1NA must be in 2025 (in GPOtrosElementos, FECHA1NA = transmission date)
- **100R545**: Don't set REGIMEN=1 in RendimientoTrabajo (it triggers pension plan validation)
- **E254**: Data value mismatch — the error shows expected vs declared values
- **100S040**: Missing catastral revision mark (C_REV field)

(En el original, los dos comandos de la fase 5 van en un bloque de código anidado; los hemos sangrado para que este bloque se copie limpio).

El esqueleto del XML y los resultados mínimos (extracto de CLAUDE.md)

Del CLAUDE.md. Los ... son del autor; codigoCA="12" es Madrid (el 05 es Canarias).

<?xml version="1.0" encoding="ISO-8859-1"?>
<Declaracion modelo="100" ejercicio="2025" periodo="0A" versionxsd="1.02">
  <Aux>
    <Idioma>E</Idioma>
    <VERSION>1.02</VERSION>
  </Aux>
  <DatosIdentificativos>
    <Declarante>...</Declarante>
    <Conyuge>...</Conyuge>           <!-- si casado -->
    <Hijos PH18="SI">...</Hijos>    <!-- si tiene hijos menores -->
  </DatosIdentificativos>
  <AsignacionTributaria>             <!-- opcional -->
    <FINESSOCIALES>SI</FINESSOCIALES>
  </AsignacionTributaria>
  <DatosEconomicos codigoCADeclaracion="12" TIPOTRIBUTACION="1">
    <TomaDatosAmpliada titular="2" nif="..." codigoCA="12">
      <RdtoTrabajo>...</RdtoTrabajo>
      <RdtoCapitalMobiliario>...</RdtoCapitalMobiliario>
      <Inmuebles>...</Inmuebles>
      <GPFondos>...</GPFondos>
      <GPAcciones>...</GPAcciones>
      <GPOtrosInmuebles>...</GPOtrosInmuebles>      <!-- ANTES de GPOtrosElementos -->
      <GPOtrosElementos>...</GPOtrosElementos>
      <CalculoImpuesto>...</CalculoImpuesto>         <!-- doble imposición -->
      <AnexoA>...</AnexoA>                           <!-- donativos -->
    </TomaDatosAmpliada>
    <TomaDatosAmpliada titular="3" nif="..." codigoCA="12">
      <!-- cónyuge: vacío si tributación individual -->
    </TomaDatosAmpliada>
    <Resultados>...</Resultados>
  </DatosEconomicos>
</Declaracion>

<Resultados>
  <BaseLiquidableRes><BLGGRAV>0.00</BLGGRAV></BaseLiquidableRes>
  <CalculoImpuestoRes>
    <CuotaDiferencialRes><CDIF>0.00</CDIF></CuotaDiferencialRes>
    <RESULTADO>0.00</RESULTADO>
  </CalculoImpuestoRes>
</Resultados>

Ejemplo: la venta de unas acciones cotizadas (datos de ejemplo de Agents Finance, mapeo del CLAUDE.md)

Una venta con un valor de transmisión de 12.000,00 € y un valor de adquisición de 9.000,00 €, es decir, una ganancia de 3.000,00 €. Los nombres de los elementos y su significado vienen del mapeo del autor; las cifras son nuestras. Los comentarios en inglés dicen: nombre de la entidad (no el ISIN), valor total de transmisión, valor de adquisición, adquisición total, ganancia (0 si hay pérdida) y ganancia reducida.

<EntidadAccion>
  <G2B_DE>EXAMPLE CORP</G2B_DE>          <!-- entity name, not the ISIN -->
  <G2B_A valor="12000.00">               <!-- valor = total transmission value -->
    <ENTIDAD>EXAMPLE CORP</ENTIDAD>
    <TRANSACCION>
      <IT>12000.00</IT>                  <!-- transmission value -->
      <IA>9000.00</IA>                   <!-- acquisition value -->
    </TRANSACCION>
  </G2B_A>
  <G2B_B>9000.00</G2B_B>                 <!-- total acquisition -->
  <G2B_C>3000.00</G2B_C>                 <!-- gain (0 if loss) -->
  <G2B_D>3000.00</G2B_D>                 <!-- reduced gain -->
</EntidadAccion>

Plantilla de Agents Finance basada en el repositorio: un comando por iteración

El README y el skill describen validar, convertir y subir como comandos separados. Este script, escrito por nosotros y sin probar contra la AEAT, los encadena para que cada vuelta del ciclo sea una sola llamada. Da por hecho que hacienda login sigue abierto y que estás dentro del repositorio clonado. Por orden: valida contra el esquema corregido, convierte a ISO-8859-1, importa en EDFI guardando la salida en un log y lista los mensajes ERES.

#!/usr/bin/env bash
# edfi-iteracion.sh: Agents Finance template based on jatorre/hacienda-cli (untested)
# Usage: ./edfi-iteracion.sh declaracion.xml   (UTF-8 XML written by your agent)
set -euo pipefail
src="${1:?Usage: $0 declaracion.xml}"
latin1="${src%.xml}-latin1.xml"
log="edfi-$(date +%Y%m%d-%H%M%S).log"

# 1) Offline check against the corrected official schema
xmllint --schema data/Renta2025-fixed.xsd "$src" --noout

# 2) EDFI requires ISO-8859-1 (the XML declaration must already say so)
iconv -f UTF-8 -t ISO-8859-1 "$src" > "$latin1"

# 3) Import into EDFI through the open browser session and keep the output
node scripts/edfi-upload.mjs "$latin1" | tee "$log"

# 4) List the values EDFI calculated, for the agent and for you to review
grep -E "ERES" "$log" || echo "No ERES messages in this upload."

Plantilla de Agents Finance: el encargo inicial al agente

También es nuestro, y lo dejamos en inglés para que sea idéntico en las dos versiones; puedes traducirlo, porque el agente trabaja igual en español. Pégalo en tu agente desde la raíz del repositorio clonado, con tus documentos en una carpeta privada mis-datos/ fuera del control de versiones. En resumen, le pide: leer primero CLAUDE.md y el skill; entregar una tabla de conciliación entre los datos de la AEAT y tus documentos antes de escribir el XML y esperar tus respuestas; no usar nunca valores sintéticos; documentar en notas-casillas.md de qué documento sale cada cifra; iterar con el script anterior explicando cada cambio en Resultados, y no presentar, firmar ni tocar nada en Renta WEB.

You are helping me prepare, NOT file, my Spanish IRPF return (Modelo 100, campaign {{YEAR}}).
Read CLAUDE.md and .claude/skills/irpf-declaracion/SKILL.md first and follow them.

Inputs in ./mis-datos/:
- datos-fiscales-100-{{YEAR}}.html and borrador-100-{{YEAR}}.pdf (downloaded with hacienda download 100)
- {{LIST OF BROKER, BANK, EXCHANGE AND PENSION DOCUMENTS}}

Rules:
1. Before writing any XML, give me a reconciliation table: every item in the AEAT data, every item
   in my documents, and the differences between them. Wait for my answers on each difference.
2. Never use synthetic acquisition or transmission values. If a value is missing, stop and ask me.
3. Keep a file notas-casillas.md that says, for each XML element you fill, which document and page
   the figure comes from.
4. Write declaracion.xml in UTF-8 with the ISO-8859-1 declaration, run ./edfi-iteracion.sh and
   iterate on ERES messages. After each upload, list which Resultados values you changed and why.
5. Never click "Presentar", never sign, and never change anything in Renta WEB. When EDFI accepts
   the file, summarise the individual and joint results and stop.

Sustituye {{YEAR}} y la lista de documentos. La segunda regla es un cambio deliberado respecto al skill, que explicamos en los riesgos.

Resultados que declara el autor

Lo que afirma de la Torre es cualitativo: el proceso que antes le costaba una tarde entera de copiar cifras y verificar casillas pasó a ser uno en el que el agente hacía el trabajo pesado y él revisaba y aprobaba. No publica su declaración, el número de iteraciones con EDFI, cuánto tardó el agente ni si la AEAT le pidió algo después. La prueba más sólida es el propio repositorio: un CLI que otras personas han usado y corregido (tres pull requests fusionadas de otros dos colaboradores, una de ellas sobre las pantallas iniciales de cada campaña). Bajo la publicación de lanzamiento, un lector confirmó que el login y la descarga hacían lo prometido, pero explicó que su verdadero obstáculo era generar un primer XML a partir de unas 1.300 operaciones que tenía en una hoja de cálculo, porque la AEAT no permite exportar el borrador en XML.

Limitaciones y riesgos

• No es una API. El CLI automatiza páginas web de la AEAT; un cambio de URL, de selector o de campaña (las rutas incluyen RW25) puede romperlo, y el esquema incluido es el de la campaña 2025.
• Un XML aceptado no es una declaración correcta. El README lo dice claramente: que EDFI lo acepte solo significa que superó la importación y sus cálculos, no que lo declarado sea completo ni correcto.
• El ciclo ERES puede tapar errores. Copiar en Resultados lo que calcula el servidor hace el fichero coherente, no verdadero. Con datos de entrada erróneos también sale una declaración «aceptada».
• Valores sintéticos. Cuando solo se conoce la ganancia o pérdida neta, el skill sugiere inventar los valores de adquisición y transmisión (IA = abs(G/P) + 1000). El neto se mantiene, pero los valores declarados no son los reales; lo hemos quitado de nuestra plantilla y recomendamos pedir las cifras reales.
• Un mapeo que falta. El skill remite al CLAUDE.md para relacionar los campos ERES con los elementos de Resultados, pero el archivo que leímos solo documenta el bloque mínimo de resultados y el formato del mensaje, así que el agente tiene que deducir esa correspondencia.
• Privacidad. El HTML y el PDF descargados contienen toda tu situación fiscal. Enviarlos a un modelo en la nube es decisión tuya, como advierte el README.
• Fuera de alcance. El propio skill dice que las declaraciones de autónomos, con sus modelos trimestrales de IVA e IRPF, superan la ayuda básica, y la parte del impuesto sobre el patrimonio (modelo 714) sigue en desarrollo.

Errores comunes

• Guardar el XML en UTF-8 y recibir un error ENC: conviértelo con iconv.
• Poner GPOtrosInmuebles después de GPOtrosElementos, o cualquier sección fuera de orden: el esquema es una secuencia estricta.
• Cambiar las fechas: FECHA1NA es la fecha de venta en las acciones no cotizadas, pero la de adquisición en los inmuebles.
• Usar S/N en lugar de 0/1 en los campos lógicos, u olvidar el subtotal valor en intereses y dividendos.
• En matrimonios, omitir el bloque del cónyuge, que la AEAT exige aunque se tribute de forma individual.
• Cerrar la ventana de Chromium entre comandos: la sesión se pierde y hay que volver a entrar.

Conclusiones

hacienda-cli es un buen ejemplo de un patrón que se repite en finanzas: el agente es bueno con la conciliación desordenada, pero necesita un comprobador determinista al que llamar y del que aprender; aquí, el validador de la propia AEAT. El autor deja a la persona al mando en los dos extremos (entrar y presentar), y los archivos son públicos, así que un contribuyente con perfil técnico puede replicar el ciclo esta campaña. Trata lo que acepte EDFI como un borrador bien formado, comprueba cada cifra con tus documentos y cuenta con un asesor fiscal si tu situación es compleja.