cadrumo.application.modelo.external_import_actions module

External filing import actions for modelo baselines.

import_external_filing_evidence() turns AEAT-attested external evidence into a presented CalculationRevision plus current ModeloRecord. Evidence-bearing imports validate the referenced Justificante, stamp an ExternalEvidence payload on the filing record, supersede any prior current filing for the same target, and emit modelo.filing.imported through BucketEventHistoryRepositoryProtocol.

The imported record is the production baseline consumed by the amendment path. It is intentionally distinct from a locally calculated and filed return: external_evidence marks that the values came from official AEAT evidence, while external_filing_observations() keeps the imported casilla values on the same registry-grounded CasillaObservation contract as local calculation revisions.

See also

filing_record_import():

CLI surface that parses filing-record import options and calls this service.

amend_modelo_revision():

Consumes the imported current ModeloRecord as an amendment baseline.

justificante:

Receipt metadata store required by justificante-PDF and live-capture evidence kinds. CSV/XLSX register imports bind the source reference directly to the target work-unit coordinates instead of masquerading as a receipt.

reject_unknown_import_casillas():

Resolves the registry snapshot and refuses noncanonical or undeclared imported casilla ids.

ExternalEvidence:

Filing-record metadata that records the official evidence source.

Core types: RegistrySnapshot.

class ExternalFilingBaselineSource(modelo, filing_year, period, evidence_kind, evidence_reference_id, tax_id, casilla_lexicals, registry_revision_id=None)[source]

Bases: object

One source-only, casilla-complete external filing observation.

Parameters:
modelo: str
filing_year: int
period: Period
evidence_kind: ExternalEvidenceKind
evidence_reference_id: str
tax_id: str
casilla_lexicals: Mapping[TypeAliasType, str]
registry_revision_id: str | None
class ExternalFilingTarget(modelo, filing_year, period, registry_revision_id=None)[source]

Bases: object

The filing coordinate an external filing is recorded against.

Parameters:

  • modelo (str)

  • filing_year (int)

  • period (Period)

  • registry_revision_id (str | None)

modelo: str
filing_year: int
period: Period
registry_revision_id: str | None
class ExternalFilingRevisionDraft(work_units, work_unit, revisions, revisions_revision_id, revision, evidence_reference_id, snapshot, canonical_values)[source]

Bases: object

A validated, not yet persisted, presented revision for external filing content.

Parameters:
work_units: WorkUnitCatalogue
work_unit: WorkUnit
revisions: CalculationRevisionCatalogue
revisions_revision_id: str
revision: CalculationRevision
evidence_reference_id: str
snapshot: RegistrySnapshot
canonical_values: Mapping[TypeAliasType, Decimal]
resolve_external_filing_work_unit(target, *, bucket_id, actor, ports, operation, clock)[source]

Resolve the active work unit for target, creating one when it is absent.

Return type:

WorkUnit

Parameters:
external_filing_source_casillas(source)[source]

Return a source’s printed lexicals and their parsed values, once proven complete.

Refuses a source whose coordinate is inconsistent, whose lexicals are blank or non-numeric, or which omits a required numeric casilla of the registry revision.

Raises:

ExternalModeloImportError – The source cannot be recorded as a baseline.

Return type:

tuple[dict[TypeAliasType, str], dict[TypeAliasType, Decimal]]

Parameters:

source (ExternalFilingBaselineSource)

import_external_filing_source(source, *, bucket_id, work_lifecycle_ports, operation, filing_instance_evidence=None, declared_kind=None, actor='aeat-import', calculation_repository=None, filing_repository=None, justificante_repository=None, observation_repository, clock=None)[source]

Resolve or create the target work unit and reconcile an amendable baseline.

Source lexical tokens are retained verbatim on the revision input snapshot; their independently parsed Decimal values feed the filing baseline.

Return type:

ExternalFilingImportResult

Parameters:
advance_external_filing_work_unit(catalogue, *, work_unit, revision_id, filing_record_id, now)[source]

Point one work unit at the co-committed external filing and its revision.

Return type:

WorkUnitCatalogue

Parameters:
build_external_filing_observation_payload(*, evidence_kind, observation_repository, work_unit, revision, occurred_at, cleaned_reference, expected_tax_id, filing_record_id, source_headers)[source]

Build the CSV observation envelope when that evidence channel applies.

Parameters:

  • evidence_kind (ExternalEvidenceKind) – The import’s evidence channel; only an AEAT register CSV carries an observation envelope.

  • observation_repository (CalculationObservationRepositoryProtocol) – The store that prepares the envelope.

  • work_unit (WorkUnit) – The filing coordinate the import targets.

  • revision (CalculationRevision) – The imported CalculationRevision, whose observations the envelope carries.

  • occurred_at (datetime) – When the import was captured.

  • cleaned_reference (str) – The canonical register reference.

  • expected_tax_id (str | None) – The authenticated identity, when one is asserted.

  • filing_record_id (str) – The chain entry the envelope belongs to.

  • source_headers (tuple[ObservedHeaderFact, ...]) – The register’s typed header facts.

Return type:

ObservationEnvelopePayload | None

Returns:

The prepared envelope, or None for an evidence channel that has none.

class ExternalFilingImportResult(filing_record, reconciliation)[source]

Bases: object

The chain entry an external filing import left in force, and the decision that placed it.

Parameters:
filing_record: ModeloRecord
reconciliation: FilingReconciliationResult
import_external_filing_evidence(*, work_unit_id, casilla_values, source_lexical_values_by_casilla_id=None, evidence_kind, evidence_reference_id, filing_instance_evidence=None, declared_kind=None, actor='aeat-import', work_unit_repository=None, calculation_repository=None, filing_repository=None, bucket_event_repository=None, justificante_repository=None, observation_repository, expected_tax_id=None, clock=None, source_headers=(), operation=None)[source]

Reconcile an externally filed return with its period’s filing chain.

The target WorkUnit supplies the bucket, modelo, filing year, period, and registry revision used to validate imported casillas. Justificante-bound evidence requires stored receipt metadata matching that target; CSV-register evidence binds the imported file itself to the target, and source_headers carries the register’s typed header facts, such as the Modelo 303 declaration type its carry ingress requires.

The values go through reconcile_aeat_register_entry(): a matching pending local filing is confirmed, a disagreeing one is superseded by the imported content, and otherwise the imported content is appended in force. declared_kind is the declaration kind AEAT states; importing after a confirmed declaration requires it.

Return type:

ExternalFilingImportResult

Returns:

The in-force ModeloRecord and the reconciliation result.

Raises:

ExternalModeloImportError – The evidence cannot be bound to the work unit, or the import cannot be reconciled with the chain.

Parameters:
prepare_external_filing_revision(*, work_unit_id, casilla_values, source_lexical_values_by_casilla_id, evidence_kind, evidence_reference_id, filing_instance_evidence, expected_tax_id, actor, now, work_unit_repository, calculation_repository, justificante_repository)[source]

Validate external filing content and stage its presented revision in memory.

Refuses undeclared casillas, missing filing-instance evidence and unbound receipt evidence, then inserts a PRESENTADO revision into a revision-guarded copy of the catalogue. Nothing is written: the caller co-commits the returned catalogues with its own filing transition.

Return type:

ExternalFilingRevisionDraft

Parameters:
build_external_filing_record(*, filing_record_id, work_unit, calculation_revision_id, filed_at, filed_by, evidence_kind, evidence_reference_id, declaration_kind, member_nif=None, amends_filing_record_id=None, aeat_register=None)[source]

Build the in-force, AEAT-origin chain entry for externally presented content.

Return type:

ModeloRecord

Parameters:
require_bound_justificante_artifact(*, evidence_kind, evidence_reference_id, modelo, filing_year, period, expected_tax_id, justificante_repository)[source]

Require matching stored Justificante metadata.

Justificante-PDF and live-capture imports are treated as receipt-bound baselines: the evidence reference must resolve to stored justificante metadata for the same taxpayer, modelo, filing year, and period. The taxpayer comparison is case-insensitive after stripping.

Return type:

None

Parameters: