Informes fiscales

Un informe fiscal es una declaración calculada a partir de tus propios datos de facturación para un periodo y materializada en un fichero. Factuarea cubre los tres modelos españoles que una empresa emisora de facturas presenta por sí misma, produce cada uno en tres formatos y guarda todas las generaciones en un histórico que puedes listar, auditar y volver a descargar.

Todos los endpoints viven bajo https://api.factuarea.com/v1. Generar usa tax_reports:write; previsualizar, listar y descargar usan tax_reports:read.

Los tres modelos

Modelo	Qué declara	Periodo	Endpoint
Modelo 303	IVA trimestral: IVA devengado, recargo de equivalencia, adquisiciones intracomunitarias, inversión del sujeto pasivo, IVA soportado deducible y el resultado de la liquidación.	Año + trimestre	`POST /v1/tax_reports/303`
Modelo 347	Operaciones anuales con terceros por encima de 3.005,06 € por contraparte y ejercicio, desglosadas en los cuatro trimestres.	Solo año	`POST /v1/tax_reports/347`
Modelo 130	Pago fraccionado trimestral de IRPF del autónomo en estimación directa. El cálculo es acumulado desde el 1 de enero hasta el fin del trimestre.	Año + trimestre	`POST /v1/tax_reports/130`

year y format son obligatorios en los tres. quarter lo exigen el 303 y el 130, y el 347 lo ignora: el 347 es anual y no existe un 347 trimestral. Los ejercicios soportados empiezan en 2024.

curl -X POST https://api.factuarea.com/v1/tax_reports/303 \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2026, "quarter": 1, "format": "txt_aeat" }'

El Modelo 131 (estimación objetiva, el régimen de módulos) queda fuera de alcance. Una empresa en ese régimen que pida un 130 recibe un 422 cuyo mensaje remite al 131, en lugar de un fichero que no podría presentar.

Tres formatos, un solo cálculo

Los tres modelos producen las mismas tres salidas, y las tres se construyen a partir del mismo cálculo de dominio. Se diferencian en para qué sirven, no en lo que dicen.

`format`	Qué es	¿Se puede presentar?
`txt_aeat`	El fichero posicional oficial, conforme al diseño de registro de la AEAT que fija la orden ministerial del modelo.	Sí: este es el que se presenta.
`pdf`	Una versión legible de la declaración, para archivarla y para enviarla a un cliente o a un asesor.	No.
`excel`	Un libro de trabajo (`.xlsx`) para revisar y cuadrar las cifras antes de presentar.	No.

Ante la AEAT solo se presenta el txt_aeat. El PDF y la hoja de cálculo son material de revisión: no se suben a la Sede Electrónica ni sustituyen al fichero oficial en ningún trámite.

Dicho eso —y esta es la otra mitad de la regla— las cifras del PDF y del libro son fiables. No se recalculan para la capa de presentación: salen exactamente del mismo cálculo que produce el fichero oficial, así que cuadrar contra ellas es cuadrar contra lo que vas a presentar. Que un importe difiriera entre dos formatos de la misma declaración es imposible por construcción.

El libro de Excel

El libro tiene exactamente dos hojas —Resumen y Detalle— y ambas se abren con el mismo rótulo de contexto: modelo, periodo fiscal y empresa declarante con su NIF. Una hoja se copia a otro libro o se imprime suelta, y entonces nada del contexto de la aplicación viaja con ella.

Las primeras filas de Resumen, antes de cualquier dato, llevan el aviso:

AVISO: este libro es material de trabajo y NO es presentable ante la AEAT.
La presentación se realiza con el fichero oficial en formato TXT que genera
la propia aplicación.

La advertencia vive dentro del fichero a propósito. El libro se descarga, se adjunta a un correo y se abre en otro ordenador, que es justo donde alguien podría intentar presentarlo. Un aviso que solo existiera en la pantalla que originó la descarga no estaría allí en ese momento.

Qué pone cada modelo en cada hoja:

Modelo	`Resumen`	`Detalle`
347	Clientes y proveedores declarados, importe total declarado y cuántas contrapartes superan el umbral de 3.005,06 €.	Una fila por contraparte: tipo, NIF, nombre, provincia, país, base anual y los cuatro trimestres. Primero los clientes y después los proveedores, en el mismo orden que los registros del fichero oficial.
303	Base y cuota devengadas, recargo, intracomunitarias, inversión del sujeto pasivo, rectificativas, IVA soportado deducible, compensación de periodos anteriores y resultado de la liquidación.	IVA devengado y recargo abiertos por tipo impositivo, más once bloques fijos que se emiten siempre, ceros incluidos.
130	Las casillas derivadas: la cadena que termina en el importe a ingresar.	Las casillas de partida que las alimentan, para que el resultado sea trazable sin rehacer la cuenta.

Dos propiedades en las que puedes confiar:

Los importes son números, no texto formateado. Una columna de importes se suma en la propia hoja sin conversión previa, y un cero se escribe como 0 en vez de dejarse en blanco: en un informe económico una celda vacía se lee como «sin dato», no como «cero».
En cada fila del 347, los cuatro trimestres suman la base anual. La columna Tipo es lo que distingue una compra de una venta en cuanto reordenas la hoja.

Un ejercicio sin ninguna contraparte por encima del umbral genera libro igualmente: la hoja de detalle sale vacía y el resumen lo dice citando el umbral. Es el caso normal de una empresa pequeña, no un error: no deberías tener que adivinar si el cálculo llegó a ejecutarse.

Generar, descargar, conservar el histórico

Una generación es un recurso persistido. Los tres endpoints de modelo devuelven 201 con el informe y su id; el fichero se obtiene aparte, tantas veces como haga falta.

# 1. Generar — devuelve 201 con el id del informe
curl -X POST https://api.factuarea.com/v1/tax_reports/347 \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 2025, "format": "excel" }'

# 2. Descargar el fichero que produjo
curl -G https://api.factuarea.com/v1/tax_reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b/download \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  --output modelo-347-2025.xlsx

GET /v1/tax_reports/{tax_report}/download transmite el fichero con el tipo de contenido del formato con el que se generó —texto posicional, PDF u hoja de cálculo— y añade una cabecera X-Tax-Report-Hash con la que verificar que los bytes que archivaste son los que se generaron.

El resto del dominio lee ese mismo histórico:

Endpoint	Qué te da
`GET /v1/tax_reports/history`	Todas las generaciones de la empresa, de la más reciente a la más antigua, filtrables por `type` y `year`, con paginación por cursor.
`POST /v1/tax_reports/find-by-period`	La generación más reciente de un `type` + `year` (+ `quarter`), o `404` si ese periodo no se ha generado nunca.
`GET /v1/tax_reports/stats`	KPIs agregados: totales por modelo y por formato, tamaño acumulado y periodo fiscal en curso.
`GET /v1/tax_reports/{tax_report}/activities`	La cronología de actividad de una generación: cuándo se generó y quién la generó.

Para ver las cifras antes de comprometerte con un fichero, usa POST /v1/tax_reports/preview con type, year y quarter: calcula el mismo desglose, no persiste nada y no escribe ningún fichero. Es la llamada que va detrás de una pantalla de «revisar antes de presentar».

Errores que debes prever

Estado	`code`	Cuándo
`422`	`invalid_period`	Año fuera del rango soportado, o trimestre ausente o inválido en un modelo que lo necesita.
`422`	`insufficient_data_for_report`	El periodo no tiene nada que declarar, o una factura del periodo carece de un campo que el modelo exige.
`422`	`unsupported_format`	El modelo no produce ese formato para ese ejercicio.
`422`	`report_format_invalid`	`format` fuera de `txt_aeat`, `pdf`, `excel`.
`422`	`tax_report_type_invalid`	`type` fuera de `modelo_303`, `modelo_347`, `modelo_130`.
`404`	`tax_report_not_found`	El id no corresponde a ningún informe de tu empresa.

Referencia completa en Todos los error codes.

Desde un agente

Las mismas nueve operaciones están expuestas como MCP tools: generate_tax_report_303, generate_tax_report_347 y generate_tax_report_130 bajo tax_reports:write, y previsualización, búsqueda por periodo, histórico, estadísticas, actividad y descarga bajo tax_reports:read. Consulta el catálogo de tools.

Siguientes pasos

Recetario fiscal

recetas de principio a fin para las declaraciones españolas.

Impuestos territoriales

los regímenes que condicionan lo que declaran estos modelos.

Referencia de la API

esquemas de petición y respuesta.