aeat.domain.submission._models module

Strict pydantic v2 records for the filing submission engine.

Every type that crosses a public boundary is a strict+frozen pydantic.BaseModel or a closed enum.StrEnum. No dataclasses; no bare dict[str, Any].

The records describe a local or imported filing audit trail. They do not authorize a live AEAT write; live-write refusal stays with the core access gate and application facades compose these records into draft/import flows.

See also

aeat.domain.submission.SubmissionEngine

Runs preflight and reads these records from the repository.

aeat.application.filing.import_filing_from_justificante()

Builds a companion ModeloPresentado when an offline justificante PDF is imported.

aeat.domain.modelos.ModeloRecord

Work-unit filing record used by the modelo application facade.

aeat.application.live

Read-only live-capture surface that may attach AEAT evidence to existing local filing records.

class SubmissionStatus(*values)[source]

Bases: StrEnum

Lifecycle status of a ModeloPresentado.

Values are retained for historical records imported from AEAT, even though live AEAT submission is now permanently forbidden. Member names and values mirror the AEAT Sede labels per ADR A7.2.

Variables:

  • PENDIENTE_DE_PRESENTAR – Filing recorded but no attempt has run.

  • EN_TRAMITACION – An attempt is currently underway.

  • PRESENTADA – Attempt completed; awaiting AEAT acknowledgement.

  • ACEPTADA – AEAT issued a justificante CSV and PDF.

  • RECHAZADA – AEAT explicitly rejected the filing.

  • FALLIDA – Attempt could not complete (transport / browser).

PENDIENTE_DE_PRESENTAR
EN_TRAMITACION
PRESENTADA
ACEPTADA
RECHAZADA
FALLIDA
class SubmissionAttempt(**data)[source]

Bases: BaseModel

A historical attempt record imported or retained locally.

Variables:

  • attempt_id – Stable identifier for this attempt (<submission_id>.<ordinal>).

  • started_at – UTC timestamp when the attempt began.

  • ended_at – UTC timestamp when the attempt ended (success or failure).

  • status – Terminal SubmissionStatus for the attempt.

  • error_code – Optional machine-readable error code.

  • error_message – Optional multilingual error message.

  • browser_trace_path – Optional path to a Playwright trace file written for this attempt.

Parameters:
attempt_id: str
started_at: datetime
ended_at: datetime
status: SubmissionStatus
error_code: str | None
error_message: str | None
browser_trace_path: Path | None
class ModeloPresentado(**data)[source]

Bases: BaseModel

The typed audit record for one historical filing.

Variables:

  • submission_id – Stable SHA-256-derived hex digest of f"{draft_id}:{attempt_ordinal}". See make_submission_id().

  • draft_id – The upstream draft identifier.

  • modelo – The AEAT modelo identifier.

  • period – The Period covered, serialised as {"filing_year": int, "code": str} across the persistence boundary.

  • profile_tax_id – The validated taxpayer identity value carried by the upstream draft or imported receipt.

  • status – The overall SubmissionStatus for the filing.

  • justificante_csv – The AEAT-issued CSV, when present.

  • justificante_pdf_path – Local path to the justificante PDF, when present.

  • submitted_at – UTC timestamp of the first attempt start.

  • acknowledged_at – UTC timestamp the user acknowledged the filing, when set.

  • attempts – Non-empty tuple of SubmissionAttempt records in chronological order.

Parameters:
submission_id: str
draft_id: str
modelo: str
period: Period
profile_tax_id: SubjectTaxId
status: SubmissionStatus
justificante_csv: str | None
justificante_pdf_path: Path | None
submitted_at: datetime
acknowledged_at: datetime | None
attempts: tuple[SubmissionAttempt, ...]
make_submission_id(draft_id, attempt_ordinal)[source]

Return a stable 16-hex-char SHA-256 prefix for a submission.

The output is deterministic: identical (draft_id, attempt_ordinal) pairs always produce identical ids across runs and processes.

Parameters:

  • draft_id (str) – The upstream draft identifier.

  • attempt_ordinal (int) – A strictly positive ordinal (>= 1) distinguishing multiple submission attempts against the same draft.

Return type:

str

Returns:

A 16-character lowercase hex string.

Raises:

SubmissionValidationError – If draft_id is empty or attempt_ordinal is not a positive integer.