aeat.adapters.outbound.aeat.sede._declarations module

Read-only walker over AEAT’s Consultar declaraciones presentadas surface.

The expediente-tree walker (_walker.walk_expedientes_tree) walks Mis Expedientes (/wlpl/TEWV-CORE/ResumenVlt) which is a procedures surface — sanciones, recursos, gestión recaudación — not the canonical filings register. To read the operator’s actual filing history across supported periodic, annual, retention, and informative declarations, we drive the Consultar declaraciones presentadas form at /wlpl/SCEJ-MANT/CONSUL/index.zul.

The form is built on the ZK framework. Input ids are generated by the server and are not stable selectors; automation binds on label text and visible row structure. The submit action is a real Buscar button issuing a ZK AJAX RPC; URL parameters alone do not drive results.

Parsed filings are grounded against the registry: each declaration is resolved to its ModeloRevision and a RegistrySnapshot (loaded through ValidatedRegistryAuthority), and reported casilla values are surfaced as CasillaObservation rows carrying their legal and source references.

shared_playwright(session)[source]

Yield a long-lived Playwright instance for bulk register sweeps.

walk_declarations_register and capture_declaration each spin up their own Playwright + BrowserSession when called standalone, which is fine for one-shot use. Bulk callers (e.g. aeat sede capture-corpus) pay ~1s per iteration on Playwright startup; wrapping repeated reads in this helper amortises that cost across the entire run.

Usage:

async with shared_playwright(session) as pw:
    for modelo in modelos:
        rows = await walk_declarations_register(
            session, modelo=modelo, ejercicio=ejercicio,
            playwright=pw,
        )
        for declaration in rows:
            capture = await capture_declaration(
                session, declaration, playwright=pw,
            )
Parameters:

session (AeatSession) – Authenticated AEAT session. Validated upfront so bulk reads fail fast rather than per-iteration.

Yields:

A live Playwright instance. Cleaned up automatically on exit.

Return type:

AsyncIterator[TypeAliasType]

class DeclaracionesRegisterSession(session, page, context)[source]

Bases: object

Reusable read-only session for AEAT’s filed-declarations register.

Parameters:

  • session (AeatSession)

  • page (Page)

  • context (BrowserContext)

async walk(*, modelo, ejercicio)[source]

Return Declaracion rows for one (modelo, ejercicio) query.

Return type:

tuple[Declaracion, ...]

Parameters:

  • modelo (str)

  • ejercicio (int)

async capture_observation(declaration, *, registry_snapshot=None, artefact_sink=None)[source]

Capture a normalized FiledDeclaracionObservation using the active page.

Parameters:

  • declaration (Declaracion) – The Declaracion row to observe.

  • registry_snapshot (RegistrySnapshot | None) – Optional pre-built RegistrySnapshot. When omitted, the snapshot is resolved from the declaration coordinates.

  • artefact_sink (TypeAliasType | None) – Optional callable storing each captured artefact.

Return type:

FiledDeclaracionObservation

open_declarations_register(session, *, settings=None, playwright=None)[source]

Open a DeclaracionesRegisterSession for repeated filed-declaration register reads.

Return type:

AsyncIterator[DeclaracionesRegisterSession]

Parameters:
async walk_declarations_register(session, *, modelo, ejercicio, settings=None, playwright=None)[source]

Drive the Consultar declaraciones presentadas form for one query.

Parameters:

  • session (AeatSession) – Authenticated AEAT session whose storage_state_path carries valid cookies.

  • modelo (str) – Modelo code to query. The form’s modelo combobox is matched on the leading "<modelo> -" text.

  • ejercicio (int) – Tax year to query (2024).

  • settings (Settings | None) – Optional Settings override.

  • playwright (TypeAliasType | None) – Optional pre-started Playwright instance (typically from shared_playwright()). Reused across the call to amortise the ~1s startup cost in bulk sweeps. When None, a fresh instance is started and torn down per call.

Return type:

tuple[Declaracion, ...]

Returns:

Tuple of Declaracion records, one per filing row. Empty when AEAT returns “No se han encontrado resultados”.

async capture_declaration(session, declaration, *, settings=None, playwright=None)[source]

Fetch the raw justificante PDF behind a Declaracion.

Drives the declaraciones register the same way walk_declarations_register() does, locates the row whose expediente_id matches declaration.expediente_id, clicks that row’s Obtención de Justificante button, captures the CSV from the resulting cotejo URL, and downloads the PDF via APIRequestContext (so Chrome’s PDF viewer never intercepts the response).

Parameters:
Return type:

SedeCapture

Returns:

A SedeCapture whose ref carries the resolved CSV / cotejo URL / PDF URL and whose pdf_bytes carries the raw response body.

Raises:
async capture_filed_declaration_observation(session, declaration, *, registry_snapshot=None, settings=None, playwright=None, artefact_sink=None)[source]

Capture a FiledDeclaracionObservation with read-only evidence for one filed declaration.

The observation begins with the register row and then captures every AEAT-served artefact this backend knows how to read from the row: the justificante/declaration PDF and, when exposed by AEAT, the submitted file download. Submitted files are parsed through the registry export layout selected for the declaration snapshot.

Parameters:

  • session (AeatSession) – Authenticated AEAT session.

  • declaration (Declaracion) – The Declaracion row to observe.

  • registry_snapshot (RegistrySnapshot | None) – Optional pre-built RegistrySnapshot. When omitted, the snapshot is resolved from the declaration’s modelo, ejercicio, and period via the bundled registry authority.

  • settings (Settings | None) – Optional Settings override.

  • playwright (TypeAliasType | None) – Optional pre-started Playwright instance.

  • artefact_sink (TypeAliasType | None) – Optional callable that stores each captured artefact and returns the (possibly updated) artefact record.

Return type:

FiledDeclaracionObservation

async capture_previous_filing_observations(session, revision, *, filing_year, period, settings=None, playwright=None, artefact_sink=None)[source]

Capture FiledDeclaracionObservation records required by registry previous-filing bindings.

Parameters:

  • session (AeatSession) – Authenticated AEAT session.

  • revision (ModeloRevision) – The ModeloRevision whose previous-filing binding requirements determine which declarations are fetched.

  • filing_year (int) – Tax year of the current filing.

  • period (Period) – Period code of the current filing.

  • settings (Settings | None) – Optional Settings override.

  • playwright (TypeAliasType | None) – Optional pre-started Playwright instance.

  • artefact_sink (TypeAliasType | None) – Optional callable storing each captured artefact.

Return type:

tuple[FiledDeclaracionObservation, ...]

async capture_relation_source_observations(session, revision, *, filing_year, period, settings=None, playwright=None, artefact_sink=None)[source]

Capture FiledDeclaracionObservation records required by registry cross-model relations.

Parameters:

  • session (AeatSession) – Authenticated AEAT session.

  • revision (ModeloRevision) – The ModeloRevision whose cross-model relation requirements determine which source declarations are fetched.

  • filing_year (int) – Tax year of the current filing.

  • period (Period) – Period code of the current filing.

  • settings (Settings | None) – Optional Settings override.

  • playwright (TypeAliasType | None) – Optional pre-started Playwright instance.

  • artefact_sink (TypeAliasType | None) – Optional callable storing each captured artefact.

Return type:

tuple[FiledDeclaracionObservation, ...]