aeat.application.live._iva_remote_state module

IVA remote-state, compensation-history, and wallet live actions.

The module separates stored-evidence reads from live acquisition. Listing and load helpers read encrypted local IVA compensation history, wallet decisions, wallet observations, and acquisition manifests without contacting AEAT. Capture helpers enforce the live-read gate, acquire an authenticated AeatSession, then persist filed-history and wallet evidence before reconciliation consumes it.

Encrypted acquisition manifests are stored through the active bucket’s SecureObjectRepository via the typed manifest repository under LIVE_IVA_REMOTE_STATE_ACQUISITIONS_NAMESPACE. The manifest is redacted operational evidence of the acquisition attempt; it is not a remote submission record.

See also

IvaRemoteStateStoredEvidenceReport

Stored-evidence report returned without a live AEAT read.

IvaRemoteStateAcquisitionReport

Combined read-only acquisition report for filed history and wallet surfaces.

active_verified_session()

Shared read-only authenticated-session helper used by individual capture surfaces.

class IvaRemoteStateAcquisitionManifestRepository(*, objects=None)[source]

Bases: SecureBoundRepository[IvaRemoteStateAcquisitionManifest]

Repository for encrypted live IVA acquisition manifests.

The repository stores redacted IvaRemoteStateAcquisitionManifest payloads under the active profile bucket. Raw AEAT rows remain in their dedicated evidence stores.

The namespace, sensitivity, schema version, and object-key grammar come from LIVE_IVA_REMOTE_STATE_ACQUISITIONS_NAMESPACE. The SecureBoundRepository base writes each manifest through an Envelope so acquisition ids and redacted surface summaries stay inside the encrypted secure-object store.

Parameters:

objects (_SecureObjectRepository | None)

namespace: ClassVar[str]
sensitivity: ClassVar
schema_version: ClassVar[int]
payload_type

alias of IvaRemoteStateAcquisitionManifest

extract_identifier(payload)[source]

Return the acquisition’s stable string identifier.

Return type:

str

Parameters:

payload (IvaRemoteStateAcquisitionManifest)

list_iva_compensation_history(*, repository=None, decision_repository=None, as_of_year=None)[source]

List profile-local IVA compensation history and return an IvaCompensationHistoryReport.

Return type:

IvaCompensationHistoryReport

Parameters:
load_iva_remote_state(*, as_of_year=None, wallet_store=None, repository=None, decision_repository=None)[source]

Reload stored remote IVA evidence from the active profile without contacting AEAT.

Returns an IvaRemoteStateStoredEvidenceReport with the stored compensation history, wallet observations, reconciliation decisions, and redacted acquisition manifests.

Return type:

IvaRemoteStateStoredEvidenceReport

Parameters:
async capture_iva_compensation_history(*, year_from, year_to, output_root)[source]

Capture filed Modelo 303s across years and return an IvaCompensationHistoryCaptureReport.

Return type:

IvaCompensationHistoryCaptureReport

Parameters:

  • year_from (int)

  • year_to (int)

  • output_root (Path)

persist_and_reconcile_iva_compensation_wallet(observation, *, output_root, repository=None, decision_repository=None, decided_at=None)[source]

Persist, reload, reconcile, and report one AEAT IVA wallet observation.

The reload is intentional: downstream reconciliation must use evidence that actually survived the encrypted storage boundary, not only the in-memory result returned by the browser driver.

Returns an IvaWalletCaptureReport.

Return type:

IvaWalletCaptureReport

Parameters:
async capture_iva_compensation_wallet(*, target_year, target_period, taxpayer_nif=None, output_root=None)[source]

Live-fetch AEAT’s IVA compensation wallet and persist the observation.

This is the operator-approved live path. It will acquire or reuse the configured AEAT session, including Cl@ve Móvil approval when the auth provider requires it. Under pytest, the shared live-read gate still requires the live-test opt-in before remote contact.

Returns an IvaWalletCaptureReport.

Return type:

IvaWalletCaptureReport

Parameters:

  • target_year (int)

  • target_period (Period)

  • taxpayer_nif (str | None)

  • output_root (Path | None)

async capture_iva_remote_state(*, year_from, year_to, target_year, target_period, taxpayer_nif=None, output_root=None)[source]

Acquire filed-history and wallet/cartera IVA state as one typed read-only operation.

The operation reports each remote surface independently. A partial failure is captured as a redacted outcome and persisted in the acquisition manifest; a successful surface still persists and reloads its evidence before being reported.

Returns an IvaRemoteStateAcquisitionReport with the acquired state, compensation history, and any acquisition issues.

Return type:

IvaRemoteStateAcquisitionReport

Parameters:

  • year_from (int)

  • year_to (int)

  • target_year (int)

  • target_period (Period)

  • taxpayer_nif (str | None)

  • output_root (Path | None)

build_iva_remote_state_acquisition_report(*, output_root, year_from, year_to, target_year, target_period, acquisition_manifest_id=None, auth_result=None, auth_error=None, filed_history=None, wallet=None, filed_history_error=None, wallet_error=None)[source]

Build the redacted combined IvaRemoteStateAcquisitionReport from surface results.

Return type:

IvaRemoteStateAcquisitionReport

Parameters:
persist_iva_remote_state_acquisition_report(report, *, captured_at=None, repository=None)[source]

Persist a redacted encrypted manifest for a live IVA acquisition report.

Returns the persisted IvaRemoteStateAcquisitionManifest with the acquisition id and redacted summary fields.

Return type:

IvaRemoteStateAcquisitionManifest

Parameters:
load_iva_remote_state_acquisition_manifest(acquisition_id, *, repository=None)[source]

Load one encrypted live IVA acquisition manifest by id.

Returns:

The loaded manifest, or None.

Return type:

IvaRemoteStateAcquisitionManifest | None

Parameters:
list_iva_remote_state_acquisition_manifests(*, repository=None)[source]

List encrypted live IVA acquisition manifests for the active profile.

Returns a tuple of IvaRemoteStateAcquisitionManifest records.

Return type:

tuple[IvaRemoteStateAcquisitionManifest, ...]

Parameters:

repository (IvaRemoteStateAcquisitionManifestRepository | None)