Una declaración de impuestos (taxDeclaration) es un modelo de impuestos que el usuario ha generado y guardado en FacturaDirecta desde la sección Impuestos: un 303 trimestral, un 347 anual, un 130… Es la misma información que ve el usuario en la web: el número de modelo, el periodo, el resultado, las casillas que se escriben en el fichero de presentación de la AEAT y, en las declaraciones informativas, los terceros declarados.

El recurso es de solo lectura. La API no genera, rellena ni presenta modelos: el usuario los genera en la web y los presenta en la Sede de la AEAT. Lo que sí hace la API es dejar descargar el PDF y el fichero de presentación de un modelo ya guardado, los mismos que descargan los botones de la web.

No confundas este recurso con el catálogo de impuestos de la empresa (los tipos de IVA, IRPF o IGIC que se aplican a las líneas de los documentos), que está en /settings/taxes/* y se describe en la guía del catálogo de impuestos.

Cada declaración tiene dos partes con compromisos de estabilidad distintos:

Los valores de form, kind, status, origin y result.declarationType son enums abiertos: tu integración debe tolerar valores que no conozca.

El ejemplo está recortado: un 303 real trae unas sesenta casillas, y en el listado solo aparecen con related=boxes.

Son los del diseño de registro de la AEAT y solo existen en las autoliquidaciones que lo llevan (303, 130…): I ingreso, U domiciliación del ingreso, G cuenta corriente tributaria (ingreso), C solicitud de compensación, D devolución, V cuenta corriente tributaria (devolución) y N sin actividad o resultado cero.

boxes son las casillas tal como se escriben en el fichero de presentación de la AEAT, en el orden del diseño de registro, también las que valen cero. Cada una lleva:

No se publican el relleno técnico del fichero (constantes, longitudes, sello), la identidad de la empresa (NIF y razón social, que ya da GET /settings/company) ni los registros por tercero, que van en records. Para interpretar una casilla concreta, usa las instrucciones del modelo de la AEAT para la formVersion indicada.

Las declaraciones informativas no liquidan nada: declaran con quién se ha operado, y su fichero lleva un registro por cada tercero. records los devuelve con dos listas: fields, los campos de cada registro (key y title, en el orden del diseño), e items, un objeto por tercero con el valor de cada campo bajo su key.

Los campos exactos de cada modelo son los de su formVersion. Los registros llevan datos personales de terceros (NIF y nombre), los mismos que ya puedes leer con contacts:read y bills:read: trátalos con el mismo cuidado.

formVersion identifica el diseño de registro de la AEAT con el que se generó el modelo y, por tanto, qué casillas tiene. Se elige por la fecha del modelo (el último día de su periodo) y se queda fijo en el documento guardado. Los valores actuales, del más reciente al más antiguo:

GET /{companyId}/taxDeclarations devuelve los modelos guardados de la empresa con paginación por offset (patrón A de la guía de paginación). Los modelos eliminados no salen. Sin ordenación explícita, van del más reciente al más antiguo por la fecha del modelo.

Respuesta: { pagination, items: TaxDeclarationResponse[] }. Cada elemento lleva content (la declaración, sin boxes salvo que los pidas), tags, creationDate, modificationDate, webUrl (la página del modelo en la web) y, con related=journal, related.journal.

Parámetros de consulta:

Parámetros globales aceptados:

Ver la guía de paginación y Autenticación para el detalle.

Modelos de IVA de 2026 con sus casillas:

Declaraciones informativas de 2025:

GET /{companyId}/taxDeclarations/{id} devuelve un modelo con sus casillas completas.

Parámetros de consulta:

Parámetros globales aceptados: el header accept-version.

Respuesta: { content: TaxDeclaration, tags, creationDate, modificationDate, webUrl, related? }.

Un modelo eliminado responde 404.

Un 347 con sus declarados:

<id-empresa> es un placeholder. Las casillas y los campos de los registros están recortados.

PUT /{companyId}/taxDeclarations/{id}/pdf genera el PDF resumen del modelo, con sus casillas y valores, el mismo que imprime la web, y devuelve una URL temporal desde la que descargarlo. Funciona igual que el PDF de las facturas: el cuerpo lleva mode (attachment, inline o print) y la respuesta url, filename (modelo_303_2026_3T.pdf), availableUntil y, en modo print, urlPdf.

El PDF se genera solo si aún no existe o si el modelo ha cambiado desde la última generación; si no, se reutiliza el ya generado, como el PDF de las facturas. No calcula ni modifica el modelo, y cada generación (no cada descarga) deja en la actividad del documento la misma traza file (formato pdf) que la web. No admite la cabecera Idempotency-Key: repetir la llamada devuelve el mismo fichero.

PUT /{companyId}/taxDeclarations/{id}/aeatFile devuelve el fichero de presentación de la AEAT (el diseño de registro BOE) de un modelo ya guardado, el mismo que descarga el botón «Descargar fichero AEAT» de la web, como { url, filename }. filename es el que indica aeatFile.filename en la declaración (modelo_303.303).

El fichero se compone solo si aún no existe o si el modelo ha cambiado desde la última generación; si no, se devuelve el ya generado, que normalmente es el que la web generó al crear el modelo. Funciona como el Facturae de las facturas. Se construye a partir de las casillas guardadas: no calcula ni modifica nada, y cada generación (no cada descarga) deja en la actividad la misma traza file (formato boefile) que la web. Presentarlo sigue siendo cosa del usuario, en la Sede de la AEAT. No admite la cabecera Idempotency-Key: repetir la llamada devuelve el mismo fichero.

El 390 no tiene fichero (se rellena en la Sede) y responde 404; compruébalo antes con aeatFile.available.

GET /{companyId}/taxDeclarations/{id}/attachments devuelve { items: Attachment[] } con los ficheros que el usuario adjuntó al modelo desde la web, por ejemplo el justificante de presentación. La API no interpreta su contenido. Cada adjunto lleva name, url, creationTime y, cuando se conoce, size.

Añadir o borrar adjuntos por la API no está disponible en este recurso.

Ver Errores y validaciones para el formato general.

Esta página cubre los matices funcionales y los casos típicos. Para el contrato completo, consulta el Swagger UI o el openapi crudo.