Read AEAT notifications and other live data¶

This page covers the live read-only AEAT surfaces: official notifications, declaration history, filed returns, NIF verification, the portal catalogue, the borrador, and your IVA compensation balance. All commands in this section download data and save it locally. None of them file anything or change your AEAT records.

How a live read works¶

Every live read works the same way. It uses your configured authentication, reads from the AEAT sede read-only, and saves an encrypted local copy in your profile. It applies nothing automatically: a pull saves a local copy, and applying a downloaded fact updates only your local profile or records, and only after you review it. Nothing is ever sent back to AEAT. You remain the only one who files. To understand that boundary, see Recording a filing and the boundary.

Two live surfaces have their own guides: censo facts are covered in Link Modelo 036 census information, and filing receipts (justificantes) in Pull and store the justificante.

Before contacting AEAT, every live read runs an authentication preflight. If no provider is configured, the read refuses at that preflight; the refusal text mentions a Cl@ve identity check (La identidad de Cl@ve Móvil no coincide...), but the underlying cause is that authentication is not configured. Configure a provider first. See Authenticate with AEAT.

Before you start¶

You need:

an active profile. Create one at a terminal so you can choose its passphrase:
1Create the taxpayer profile interactively so the passphrase is chosen at the terminal.
aeat config profile create me
aeat config profile create me
2Confirm the selected profile is active before configuring AEAT authentication.
aeat --format json config profile list
aeat --format json config profile list
```
{
  "active_profile": "docs-sequence-sandbox",
  "command": "config.profile.list",
  "notices": [],
  "result": {
    "active_profile": "docs-sequence-sandbox",
    "profiles": [
      {
        "active": true,
        "bucket_id": "<bucket-id>",
        "name": "docs-sequence-sandbox"
      }
    ]
  },
  "schema_version": "2",
  "status": "success"
}
```
Confirm profile creation prompts for the passphrase at a terminal and leaves a selected profile active.
the taxpayer’s fiscal ID (generalized as NIF, CIF, DNI, NIE, or NII) saved in that profile
the profile passphrase that unwraps this profile’s independent encryption key; the tool prompts for it.
AEAT live-read authentication configured; see Authenticate with AEAT

1. Official AEAT notifications (DEHu)¶

DEHu is the official AEAT electronic inbox for notifications (comunicaciones and notificaciones). The card shows the notification reads: pull downloads and saves them locally, list shows your current DEHu notifications, view opens a saved download by its reference number, and latest shows the most recent snapshot in the active profile.

1Download your notifications and save them locally.

aeat app live notifications pull

aeat app live notifications pull

2Download your current DEHu notifications.

aeat app live notifications list

aeat app live notifications list

3View a specific saved download by its reference number.

aeat app live notifications view <snapshot-id>

aeat app live notifications view <snapshot-id>

4Show the most recent snapshot in the active profile.

aeat app live notifications latest

aeat app live notifications latest

2. Read documents from notifications you already opened¶

Read a notification document only after you have personally opened that notification in the AEAT sede. Opening an unread electronic notification is a legally consequential act: it serves the notification and starts its appeal and payment periods. The tool therefore refuses to pull a document unless AEAT already reports its notification as read. Open an unread notification yourself when you decide that those periods should begin.

Pull one eligible document into encrypted local custody, view a stored document without contacting AEAT, or list the figures reported by each parsed document:

1Pull one already-opened notification document into encrypted custody.

aeat app live notifications document pull <certificado-id>

aeat app live notifications document pull <certificado-id>

2View one notification document already held in encrypted custody.

aeat app live notifications document view <certificado-id>

aeat app live notifications document view <certificado-id>

3List the reported figures from stored notification documents.

aeat app live notifications document history

aeat app live notifications document history

Treat history as a document record, not as a balance. It does not total the figures, state what is currently payable, or replace the recaudación register reported by AEAT’s debts consulta. A document alone does not establish whether its amount was paid, appealed, reduced, or superseded.

3. Declaration history (expedientes)¶

Expedientes are the official AEAT record of your past declarations: each filed return for each modelo and year, with its status and filing date.

The card shows the expedientes reads: pull downloads the history for one form and year, pull with a year range covers several years at once (leave out --modelo to download history for all your registered forms), list shows saved downloads, view opens one download’s details (individual declarations, status, dates, and links to justificantes), and latest shows the most recent snapshot.

1Download the declaration history for a specific form and year.

aeat app live expedientes pull --modelo 100 --year 2026

aeat app live expedientes pull --modelo 100 --year 2026

2Download history for a range of years.

aeat app live expedientes pull --from-year 2020 --to-year 2026 --modelo 303

aeat app live expedientes pull --from-year 2020 --to-year 2026 --modelo 303

3List saved downloads.

aeat app live expedientes list

aeat app live expedientes list

4View a specific download's details.

aeat app live expedientes view <snapshot-id>

aeat app live expedientes view <snapshot-id>

5Show the most recent expedientes snapshot.

aeat app live expedientes latest

aeat app live expedientes latest

4. Filed declaration detail¶

Download the box-by-box values from a return you have already filed with AEAT.

The card shows the filed-detail reads. filed list lists the filed returns AEAT holds without saving their box values (it still reads from AEAT live, so it needs configured authentication like any other live command). filed pull downloads and saves the full box values from one return or across a year range, and filed pull-sources downloads the source declarations a target filing depends on (for example, the Modelo 303 returns a Modelo 390 annual summary needs).

1List the filed returns AEAT holds, without saving their box values.

aeat app live filed list --modelo 303 --from-year 2020 --to-year 2026

aeat app live filed list --modelo 303 --from-year 2020 --to-year 2026

2Download and save the full box values from a specific filed return.

aeat app live filed pull --modelo 303 --year 2026 --period 1T

aeat app live filed pull --modelo 303 --year 2026 --period 1T

3Download all filed returns across a year range.

aeat app live filed pull --from-year 2020 --to-year 2026

aeat app live filed pull --from-year 2020 --to-year 2026

4Download the source declarations that a target filing depends on.

aeat app live filed pull-sources --modelo 303 --year 2026 --period 1T

aeat app live filed pull-sources --modelo 303 --year 2026 --period 1T

5. NIF and EU VAT verification¶

Verify whether a NIF is registered for intra-EU VAT purposes (the VIES register), or check a Spanish NIF in the Spanish ROI register.

The card shows the verification reads. verify nif-iva checks whether a foreign EU VAT number is valid, and verify tgvi checks whether a Spanish NIF or NIE appears in the Spanish ROI register (add --expected valid|invalid|unknown to compare against an expected result). verify list shows past verifications, verify view opens one by its observation id, and verify latest shows the latest observation for a NIF.

1Check whether a foreign EU VAT number is valid.

aeat app live verify nif-iva ESB12345674

aeat app live verify nif-iva ESB12345674

2Check whether a Spanish NIF or NIE appears in the Spanish ROI register.

aeat app live verify tgvi 12345678A

aeat app live verify tgvi 12345678A

3List past verifications you have run.

aeat app live verify list --surface tgvi

aeat app live verify list --surface tgvi

4View details of a specific verification.

aeat app live verify view <observation-id>

aeat app live verify view <observation-id>

5Show the latest verification observation for a NIF.

aeat app live verify latest --surface nif_iva --nif ESB12345674

aeat app live verify latest --surface nif_iva --nif ESB12345674

6. Official AEAT portal catalogue¶

The card shows the portal-catalogue reads. portals list shows the official AEAT online portals the tool knows about and their authentication requirements; narrow it to one form with --modelo or to one category with --category (the accepted categories are auth, filing, censo, consultation, borrador, payment, and calendar_reference). Use --modelo or --category, not both: they are mutually exclusive. portals view opens one portal’s details.

1View the official AEAT online portals and their authentication requirements.

aeat app live portals list

aeat app live portals list

2Narrow the list to the portals for one form.

aeat app live portals list --modelo 303

aeat app live portals list --modelo 303

3Narrow the list to one category.

aeat app live portals list --category filing

aeat app live portals list --category filing

4View one portal's details.

aeat app live portals view <portal-id>

aeat app live portals view <portal-id>

7. Borrador (draft Modelo 100)¶

The borrador is the pre-calculated Modelo 100 IRPF draft that AEAT makes available to wage earners. The card shows the borrador reads: list shows the snapshots, view opens one borrador’s box values, and latest shows the latest active draft for a filing year.

1Download and list the active borrador snapshots.

aeat app live borrador 100 list --state active

aeat app live borrador 100 list --state active

2View a specific borrador's box values.

aeat app live borrador 100 view <snapshot-id>

aeat app live borrador 100 view <snapshot-id>

3Show the latest active draft for a filing year.

aeat app live borrador 100 latest --filing-year 2026

aeat app live borrador 100 latest --filing-year 2026

8. IVA compensation balance¶

Your IVA compensation balance (saldo a compensar) is the amount of overpaid IVA from prior quarters that can be deducted from future Modelo 303 filings. The card shows the IVA-wallet reads. pull downloads and tracks your current balance, pull-history reconstructs past compensation decisions from prior Modelo 303 filings, pull-evidence captures past returns and the current IVA evidence in a single read-only run, and history lists the persisted balances and decisions held locally.

1Download and track your current IVA compensation balance.

aeat app live iva-wallet pull --year 2026 --period 4T

aeat app live iva-wallet pull --year 2026 --period 4T

2Reconstruct the history of past compensation decisions.

aeat app live iva-wallet pull-history --from-year 2020 --to-year 2026

aeat app live iva-wallet pull-history --from-year 2020 --to-year 2026

3Capture past returns and the current IVA evidence in one read-only run.

aeat app live iva-wallet pull-evidence --from-year 2020 --to-year 2026 --target-year \
  2026 --target-period 4T

aeat app live iva-wallet pull-evidence --from-year 2020 --to-year 2026 --target-year `
  2026 --target-period 4T

4List the persisted compensation balances and decisions.

aeat app live iva-wallet history --as-of-year 2026

aeat app live iva-wallet history --as-of-year 2026