aeat.application.live._remote_state_models module

Typed report models for live AEAT filed-data and IVA remote-state services.

These frozen records are renderer-facing summaries, not raw evidence stores. They carry typed Period values, secure-storage references, redacted diagnostic fields, and counts/ids needed by CLI and workflow surfaces after live capture has persisted the underlying observations.

See also

aeat.application.live.IvaRemoteStateAcquisitionReport

Combined read-only IVA remote-state acquisition result.

aeat.application.live.IvaRemoteStateStoredEvidenceReport

Stored-evidence view that can be loaded without live AEAT contact.

class FiledDataCaptureReport(**data)[source]

Bases: BaseModel

Read-only filed-declaration capture report.

Parameters:

  • output_root (str)

  • modelo (str)

  • year (int)

  • captured_count (int)

  • observation_paths (tuple[str, ...])

  • artefact_refs (tuple[str, ...])

  • justificante_metadata_count (int)

  • justificante_csvs (tuple[str, ...])

  • filing_evidence_stamped_count (int)

  • filing_record_ids (tuple[str, ...])

  • filing_evidence_conflict_count (int)

  • filing_evidence_conflict_record_ids (tuple[str, ...])

  • casilla_count (int)

  • calculation_observation_count (int)

  • calculation_observation_keys (tuple[str, ...])

output_root: str
modelo: str
year: int
captured_count: int
observation_paths: tuple[str, ...]
artefact_refs: tuple[str, ...]
justificante_metadata_count: int
justificante_csvs: tuple[str, ...]
filing_evidence_stamped_count: int
filing_record_ids: tuple[str, ...]
filing_evidence_conflict_count: int
filing_evidence_conflict_record_ids: tuple[str, ...]
casilla_count: int
calculation_observation_count: int
calculation_observation_keys: tuple[str, ...]
class FiledDataCaptureFailureRow(**data)[source]

Bases: BaseModel

One failed filed-declaration capture attempt in a bulk run.

Parameters:

  • modelo (str)

  • year (int)

  • period (Period | None)

  • expediente_id (str | None)

  • error_type (str)

  • message (str)

modelo: str
year: int
period: Period | None
expediente_id: str | None
error_type: str
message: str
class BulkFiledDataCaptureReport(**data)[source]

Bases: BaseModel

Read-only bulk filed-declaration capture report.

Parameters:
output_root: str
modelos: tuple[str, ...]
year_from: int
year_to: int
captured_count: int
failed_count: int
observation_paths: tuple[str, ...]
artefact_refs: tuple[str, ...]
justificante_metadata_count: int
justificante_csvs: tuple[str, ...]
filing_evidence_stamped_count: int
filing_record_ids: tuple[str, ...]
filing_evidence_conflict_count: int
filing_evidence_conflict_record_ids: tuple[str, ...]
casilla_count: int
calculation_observation_count: int
calculation_observation_keys: tuple[str, ...]
failures: tuple[FiledDataCaptureFailureRow, ...]
class ExpedientesBulkCaptureFailureRow(**data)[source]

Bases: BaseModel

One failed expedientes register walk in a bulk run.

Parameters:
modelo: str
year: int
error_type: str
message: str
class ExpedientesBulkCaptureReport(**data)[source]

Bases: BaseModel

Read-only bulk expedientes snapshot capture report.

Parameters:
bucket_id: str
modelos: tuple[str, ...]
year_from: int
year_to: int
captured_snapshot_count: int
declaration_count: int
snapshot_ids: tuple[str, ...]
failures: tuple[ExpedientesBulkCaptureFailureRow, ...]
class SourceFiledDataCaptureReport(**data)[source]

Bases: BaseModel

Read-only source-observation capture report for one target filing.

Parameters:

  • output_root (str)

  • target_modelo (str)

  • target_year (int)

  • target_period (Period)

  • captured_count (int)

  • observation_paths (tuple[str, ...])

  • artefact_refs (tuple[str, ...])

  • justificante_metadata_count (int)

  • justificante_csvs (tuple[str, ...])

  • filing_evidence_stamped_count (int)

  • filing_record_ids (tuple[str, ...])

  • filing_evidence_conflict_count (int)

  • filing_evidence_conflict_record_ids (tuple[str, ...])

  • casilla_count (int)

  • calculation_observation_count (int)

  • calculation_observation_keys (tuple[str, ...])

output_root: str
target_modelo: str
target_year: int
target_period: Period
captured_count: int
observation_paths: tuple[str, ...]
artefact_refs: tuple[str, ...]
justificante_metadata_count: int
justificante_csvs: tuple[str, ...]
filing_evidence_stamped_count: int
filing_record_ids: tuple[str, ...]
filing_evidence_conflict_count: int
filing_evidence_conflict_record_ids: tuple[str, ...]
casilla_count: int
calculation_observation_count: int
calculation_observation_keys: tuple[str, ...]
class IvaWalletCaptureReport(**data)[source]

Bases: BaseModel

Read-only IVA compensation wallet capture report.

Parameters:

  • taxpayer_ref (str)

  • target_year (int)

  • target_period (Period)

  • observation_path (str)

  • decision_key (str)

  • row_count (int)

  • total_pending (str)

  • selected_authority (str)

  • selected_amount (str | None)

  • local_recurrence_amount (str | None)

  • divergence (str)

  • blocked (bool)

  • captured_at (datetime)

taxpayer_ref: str
target_year: int
target_period: Period
observation_path: str
decision_key: str
row_count: int
total_pending: str
selected_authority: str
selected_amount: str | None
local_recurrence_amount: str | None
divergence: str
blocked: bool
captured_at: datetime
class IvaCompensationHistoryRow(**data)[source]

Bases: BaseModel

One secure stored Modelo 303 IVA compensation history row.

Parameters:

  • year (int)

  • period (Period)

  • status (str)

  • presented_at (datetime)

  • prior_pending_amount (str | None)

  • applied_amount (str | None)

  • pending_for_later_amount (str | None)

  • period_result_amount (str | None)

  • final_result_amount (str | None)

  • generated_amount (str)

  • available_end_amount (str)

year: int
period: Period
status: str
presented_at: datetime
prior_pending_amount: str | None
applied_amount: str | None
pending_for_later_amount: str | None
period_result_amount: str | None
final_result_amount: str | None
generated_amount: str
available_end_amount: str
class IvaCompensationCarryForwardLotRow(**data)[source]

Bases: BaseModel

One CLI-safe IVA compensation carry-forward lot.

Parameters:

  • taxpayer_ref (str)

  • source_filing_year (int)

  • source_period (Period)

  • generated_amount (str)

  • applied_amount (str)

  • remaining_amount (str)

  • age_years (int)

  • expiry_review_state (str)

  • source_observation_key (str)

taxpayer_ref: str
source_filing_year: int
source_period: Period
generated_amount: str
applied_amount: str
remaining_amount: str
age_years: int
expiry_review_state: str
source_observation_key: str
class IvaWalletAuthorityDecisionRow(**data)[source]

Bases: BaseModel

One persisted wallet/local/override authority decision for CLI display.

Parameters:

  • taxpayer_ref (str)

  • target_year (int)

  • target_period (Period)

  • selected_authority (str)

  • selected_amount (str | None)

  • wallet_amount (str | None)

  • local_recurrence_amount (str | None)

  • override_amount (str | None)

  • divergence (str)

  • blocked (bool)

  • stale_wallet (bool)

  • reason (str)

  • wallet_captured_at (datetime | None)

  • decided_at (datetime)

  • authority_sources (tuple[str, ...])

taxpayer_ref: str
target_year: int
target_period: Period
selected_authority: str
selected_amount: str | None
wallet_amount: str | None
local_recurrence_amount: str | None
override_amount: str | None
divergence: str
blocked: bool
stale_wallet: bool
reason: str
wallet_captured_at: datetime | None
decided_at: datetime
authority_sources: tuple[str, ...]
class IvaCompensationHistoryReport(**data)[source]

Bases: BaseModel

Profile-local IVA compensation history report.

Parameters:
row_count: int
rows: tuple[IvaCompensationHistoryRow, ...]
as_of_year: int
carry_forward_lot_count: int
carry_forward_lots: tuple[IvaCompensationCarryForwardLotRow, ...]
unallocated_applied_amount: str
authority_decision_count: int
authority_decisions: tuple[IvaWalletAuthorityDecisionRow, ...]
class StoredIvaWalletObservationRow(**data)[source]

Bases: BaseModel

One redacted stored wallet observation summary reloaded from secure storage.

Parameters:
taxpayer_ref: str
target_year: int
target_period: Period
row_count: int
total_pending: str
captured_at: datetime
raw_sha256: str | None
class StoredIvaRemoteStateAcquisitionRow(**data)[source]

Bases: BaseModel

One redacted stored live IVA acquisition manifest summary.

Parameters:

  • acquisition_ref (str)

  • captured_at (datetime)

  • auth_status (str)

  • auth_outcome_mode (str)

  • auth_failure_mode (str | None)

  • auth_failure_type (str | None)

  • auth_diagnostic_ref (str | None)

  • auth_provider_kind (str | None)

  • auth_reused_persisted_session (bool | None)

  • year_from (int)

  • year_to (int)

  • target_year (int)

  • target_period (Period)

  • filed_history_succeeded (bool)

  • wallet_succeeded (bool)

  • surfaces (tuple[str, ...])

acquisition_ref: str
captured_at: datetime
auth_status: str
auth_outcome_mode: str
auth_failure_mode: str | None
auth_failure_type: str | None
auth_diagnostic_ref: str | None
auth_provider_kind: str | None
auth_reused_persisted_session: bool | None
year_from: int
year_to: int
target_year: int
target_period: Period
filed_history_succeeded: bool
wallet_succeeded: bool
surfaces: tuple[str, ...]
class IvaRemoteStateStoredEvidenceReport(**data)[source]

Bases: BaseModel

Stored remote IVA evidence available without a live AEAT read.

Parameters:
history: IvaCompensationHistoryReport
wallet_observation_count: int
wallet_observations: tuple[StoredIvaWalletObservationRow, ...]
acquisition_manifest_count: int
acquisition_manifests: tuple[StoredIvaRemoteStateAcquisitionRow, ...]
class IvaCompensationHistoryCaptureReport(**data)[source]

Bases: BaseModel

Read-only multi-year Modelo 303 IVA compensation history capture report.

Parameters:
output_root: str
year_from: int
year_to: int
captured_count: int
observation_paths: tuple[str, ...]
artefact_refs: tuple[str, ...]
casilla_count: int
calculation_observation_count: int
calculation_observation_keys: tuple[str, ...]
reloaded_history_count: int
reloaded_rows: tuple[IvaCompensationHistoryRow, ...]
failed_declaration_count: int
failed_declarations: tuple[str, ...]
class LiveIvaReadSurface(*values)[source]

Bases: StrEnum

Read-only IVA remote-state surfaces acquired from AEAT.

FILED_HISTORY
WALLET_CARTERA
class LiveIvaReadStatus(*values)[source]

Bases: StrEnum

Per-surface outcome for one live IVA read attempt.

SUCCEEDED
FAILED
class LiveIvaReadOutcome(**data)[source]

Bases: BaseModel

Redacted per-surface acquisition outcome.

Parameters:
surface: LiveIvaReadSurface
status: LiveIvaReadStatus
outcome_mode: LiveIvaAcquisitionFailureMode
failure_mode: LiveIvaAcquisitionFailureMode | None
failure_type: str | None
failure_context: dict[str, object] | None
captured_count: int | None
calculation_observation_count: int | None
class LiveIvaAuthOutcome(**data)[source]

Bases: BaseModel

Redacted authentication outcome for a live IVA acquisition.

Parameters:
status: LiveIvaReadStatus
outcome_mode: LiveIvaAcquisitionFailureMode
failure_mode: LiveIvaAcquisitionFailureMode | None
failure_type: str | None
diagnostic_ref: str | None
provider_kind: str | None
reused_persisted_session: bool | None
fresh: bool | None
class IvaRemoteStateAcquisitionReport(**data)[source]

Bases: BaseModel

Combined read-only IVA remote-state acquisition report.

Parameters:
acquisition_manifest_id: str | None
output_root: str
year_from: int
year_to: int
target_year: int
target_period: Period
auth: LiveIvaAuthOutcome
filed_history: IvaCompensationHistoryCaptureReport | None
wallet: IvaWalletCaptureReport | None
outcomes: tuple[LiveIvaReadOutcome, ...]
property filed_history_succeeded: bool

Return True when the filed-history surface outcome is SUCCEEDED.

property wallet_succeeded: bool

Return True when the wallet-cartera surface outcome is SUCCEEDED.

class IvaRemoteStateAcquisitionSurfaceManifest(**data)[source]

Bases: BaseModel

One persisted redacted surface outcome from a live IVA acquisition.

Parameters:
surface: LiveIvaReadSurface
status: LiveIvaReadStatus
outcome_mode: LiveIvaAcquisitionFailureMode
failure_mode: LiveIvaAcquisitionFailureMode | None
failure_type: str | None
failure_context: dict[str, object] | None
captured_count: int | None
calculation_observation_count: int | None
reloaded_history_count: int | None
wallet_row_count: int | None
decision_ref: str | None
selected_authority: str | None
divergence: str | None
blocked: bool | None
class IvaRemoteStateAcquisitionManifest(**data)[source]

Bases: BaseModel

Encrypted profile-local manifest for one read-only live IVA acquisition.

Parameters:
acquisition_id: str
captured_at: datetime
year_from: int
year_to: int
target_year: int
target_period: Period
auth: LiveIvaAuthOutcome
filed_history_succeeded: bool
wallet_succeeded: bool
surfaces: tuple[IvaRemoteStateAcquisitionSurfaceManifest, ...]