aeat.application.live package

Application facade for explicit read-only AEAT live workflows.

Every remote navigation path enters through the live-read access gate before it authenticates or opens an AEAT sede surface. Most surfaces use _session.active_verified_session(); IVA remote-state acquisition enforces the same read gate before coordinating its filed-history and wallet reads. The package has no live-submit surface: captured notifications, expedientes, filed declarations, justificantes, IVA wallet rows, Borrador 100 snapshots, and verification checks are local evidence objects, not remote filing mutations.

Live capture services persist encrypted active-bucket evidence through adapters.persistence.storage.SecureObjectRepository or the snapshot repositories re-exported by this facade. Parsed filed-declaration observations are typed as domain.calculations.registry.CasillaObservation rows and routed through domain.calculations.registry.ValidatedRegistryAuthority to bind them to the correct revision. Justificante capture may stamp the matching current domain.modelos.ModeloRecord with domain.modelos.ExternalEvidence only after the local filing record already exists.

Snapshot payloads that depend on an authenticated taxpayer carry a normalised authenticated_identity when the upstream AEAT session exposes it. The notifications snapshot id includes that identity so captures from different taxpayers do not collapse to the same local row; expedientes and notifications calendar projection compares the snapshot identity and row-level taxpayer ids against the expected active-profile tax id before surfacing observed events. Persisted capture/enrolment orchestration emits bucket events with sanitized summary payloads; non-persisting read/list surfaces remain event-free.

IVA remote-state helpers separate stored-evidence reads from live acquisition. load_iva_remote_state() returns the local IvaRemoteStateStoredEvidenceReport without contacting AEAT, while capture_iva_remote_state() returns an IvaRemoteStateAcquisitionReport, persists a redacted IvaRemoteStateAcquisitionManifest, and reports each remote surface independently so partial failures remain explicit.

See also

enroll_filed_justificante_evidence()

Filed-history path that persists justificante metadata and stamps current filing records with live-capture evidence.

SecureSnapshotRepository

Bucket-scoped encrypted snapshot repository base used by live snapshot services.

application.overview

Local-only summary surface that reads captured live evidence without contacting AEAT and filters calendar events by active-profile identity.

class JustificanteCaptureOutcome(snapshot, justificante, filing_record)[source]

Bases: object

Outcome of one live justificante pull and local filing-evidence enrolment.

The JustificanteCaptureSnapshot is always the persisted live evidence. justificante is populated only when the PDF parsed into domain metadata, and filing_record is populated only when an existing current domain.modelos.ModeloRecord could be stamped with live domain.modelos.ExternalEvidence.

Parameters:
snapshot: JustificanteCaptureSnapshot
justificante: Justificante | None
filing_record: ModeloRecord | None
property justificante_metadata_registered: bool

Return whether the captured receipt parsed into stored justificante metadata.

property filing_evidence_stamped: bool

Return whether the live receipt is locked to a local filing record.

property filing_record_id: str | None

Return the stamped local filing record id, when one was found.

async capture_expedientes(*, bucket_id, modelo, year)[source]

Live-walk the AEAT declaration register and persist a bucket-scoped snapshot.

Uses walk_declarations_register (the same register adapter the filed-data list/capture verbs drive), wraps the typed declarations in an ExpedientesCapture, and persists through ExpedientesService against the active bucket. The helper obtains its session via _session.active_verified_session(), so the read access gate is enforced before any remote contact.

Parameters:
async capture_expedientes_bulk(*, bucket_id, year_from, year_to, modelos=None)[source]

Live-walk AEAT declaration-register rows and return an ExpedientesBulkCaptureReport.

Return type:

ExpedientesBulkCaptureReport

Parameters:
async capture_notifications(*, bucket_id)[source]

Live-fetch DEHú notifications and persist a bucket-scoped snapshot.

The flow is:

  1. _AeatAccessGate.require_live_read() — keeps pytest live reads behind the live-test opt-in while allowing operator reads to continue to auth/profile/read-only guards.

  2. _ensure_authenticated_aeat_session(operation="live-notifications-read") — acquires or refreshes the authenticated session (e.g. triggers a Cl@ve Móvil push).

  3. fetch_notifications_query — drives Playwright against the authenticated DEHú surface and parses the HTML response.

  4. NotificationsService.capture — persists the typed snapshot in the active bucket under the aeat.application.live.notifications namespace.

  5. Bucket event live.notifications.snapshot_captured is emitted by the caller through the standard bucket-event repository so this function stays unit-testable against a stubbed snapshot.

Parameters:

bucket_id (str) – The active profile bucket id the notification snapshot is scoped to.

Returns:

A tuple of (snapshot_id, fetched_row_count, persisted_at).

async capture_justificante_snapshot(*, bucket_id, modelo, year, period, session_provider=<function _default_justificante_session>, declarations_provider=<function _default_justificante_declarations>, expedientes_provider=<function _default_justificante_expedientes>, justificante_provider=<function _default_justificante_capture>)[source]

Live-pull the AEAT justificante for one work unit and persist it.

The flow gates entry through _active_verified_session (the require_live_read + authenticated-session boundary), resolves the period-correct expediente by cross-referencing the period-bearing declarations register against the procedure tree (resolve_period_expediente()), pulls the signed PDF via capture_justificante, and persists it through JustificanteCaptureSnapshotService under the active bucket.

The four *_provider seams default to the live sede implementations; tests inject canned typed records to exercise the wiring offline without a network round-trip. The persistence path always uses the real service.

Return type:

JustificanteCaptureSnapshot

Returns:

The persisted JustificanteCaptureSnapshot.

Parameters:
async capture_justificante_snapshot_outcome(*, bucket_id, modelo, year, period, session_provider=<function _default_justificante_session>, declarations_provider=<function _default_justificante_declarations>, expedientes_provider=<function _default_justificante_expedientes>, justificante_provider=<function _default_justificante_capture>)[source]

Live-pull one AEAT justificante and report local filing-evidence enrolment.

The persisted JustificanteCaptureSnapshot is the durable evidence. Metadata registration and current-record evidence stamping are best-effort follow-up steps reported separately in JustificanteCaptureOutcome. A missing local filing record does not discard the captured receipt.

Return type:

JustificanteCaptureOutcome

Returns:

A JustificanteCaptureOutcome with the capture and enrolment result.

Parameters:

Submodules