aeat.application.ledger._models module

Strict Pydantic contracts for manual ledger transaction workflows.

class ManualLedgerTransactionCommand(**data)[source]

Bases: BaseModel

Backend command for creating or updating one manual ledger transaction.

Parameters:
bucket_id: BucketId
booked_date: date
value_date: date | None
amount: Decimal
currency: str
direction: TransactionDirection
counterparty: str | None
description: str
business_classification: BusinessClassification
business_pct: Decimal | None
category_id: str | None
taxable_base: Decimal | None
iva_rate: Decimal | None
iva_amount: Decimal | None
recargo_amount: Decimal | None
irpf_category: str | None
usage_ratio_id: str | None
prorrata_reference: str | None
purchase_invoice_evidence_id: str | None
attachment_ids: tuple[str, ...]
notes: str
iva_category: IvaCategory | None
counterparty_eu_member_state: EUMemberState | None
art_104_tres_exclusion: Art104TresExclusion | None
input_classification: InputClassification | None
prorrata_sector_id: str | None
actor: str
source_command: str
idempotency_key: str | None
classified_by_override: str | None
source_jurisdiction: str | None
group_label: str | None
class ManualLedgerTransactionPatch(**data)[source]

Bases: BaseModel

Typed partial update for one bucket-scoped ledger transaction.

Parameters:
booked_date: date | None
value_date: date | None
amount: Decimal | None
currency: str | None
direction: TransactionDirection | None
counterparty: str | None
description: str | None
business_classification: BusinessClassification | None
business_pct: Decimal | None
category_id: str | None
taxable_base: Decimal | None
iva_rate: Decimal | None
iva_amount: Decimal | None
recargo_amount: Decimal | None
irpf_category: str | None
usage_ratio_id: str | None
prorrata_reference: str | None
purchase_invoice_evidence_id: str | None
attachment_ids: tuple[str, ...] | None
notes: str | None
iva_category: IvaCategory | None
counterparty_eu_member_state: EUMemberState | None
source_jurisdiction: str | None
group_label: str | None
class ManualLedgerTransactionResult(**data)[source]

Bases: BaseModel

Backend result for a persisted manual ledger transaction mutation.

Parameters:
ref: BucketTransactionRef
transaction: Transaction
bucket_event_ids: tuple[str, ...]
class LedgerTransactionPayload(**data)[source]

Bases: BaseModel

Canonical read projection for one ledger transaction.

Parameters:

  • transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • date (str)

  • booked_date (str)

  • value_date (str | None)

  • amount (str)

  • currency (str)

  • direction (str)

  • counterparty (str)

  • description (str)

  • business_classification (str)

  • business_pct (str | None)

  • category_id (str | None)

  • taxable_base (str | None)

  • iva_rate (str | None)

  • iva_amount (str | None)

  • iva_category (str | None)

  • counterparty_eu_member_state (str | None)

  • irpf_category (str | None)

  • usage_ratio_id (str | None)

  • prorrata_reference (str | None)

  • purchase_invoice_evidence_id (str | None)

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

  • notes (str)

  • lifecycle_state (str)

  • classified_by (str)

  • classified_at (str | None)

  • classification_reason (str)

  • classification_confidence (str | None)

  • source_jurisdiction (str | None)

  • value_in_eur (str | None)

  • fx_rate (str | None)

  • created_at (str)

  • modified_at (str)

transaction_id: TransactionId
date: str
booked_date: str
value_date: str | None
amount: str
currency: str
direction: str
counterparty: str
description: str
business_classification: str
business_pct: str | None
category_id: str | None
taxable_base: str | None
iva_rate: str | None
iva_amount: str | None
iva_category: str | None
counterparty_eu_member_state: str | None
irpf_category: str | None
usage_ratio_id: str | None
prorrata_reference: str | None
purchase_invoice_evidence_id: str | None
attachment_ids: tuple[str, ...]
notes: str
lifecycle_state: str
classified_by: str
classified_at: str | None
classification_reason: str
classification_confidence: str | None
source_jurisdiction: str | None
value_in_eur: str | None
fx_rate: str | None
created_at: str
modified_at: str
class LedgerTransactionReviewPayload(**data)[source]

Bases: LedgerTransactionPayload

Canonical read projection for one ledger transaction plus review status.

Extends LedgerTransactionPayload with the derived operator review_status so the two projections share one field set, validator, and config; review_status serialises after the inherited fields.

Parameters:

  • transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • date (Annotated[str, MinLen(min_length=10), MaxLen(max_length=10)])

  • booked_date (Annotated[str, MinLen(min_length=10), MaxLen(max_length=10)])

  • value_date (str | None)

  • amount (Annotated[str, MinLen(min_length=1)])

  • currency (Annotated[str, MinLen(min_length=3), MaxLen(max_length=3)])

  • direction (Annotated[str, MinLen(min_length=1)])

  • counterparty (str)

  • description (Annotated[str, MinLen(min_length=1)])

  • business_classification (Annotated[str, MinLen(min_length=1)])

  • business_pct (str | None)

  • category_id (str | None)

  • taxable_base (str | None)

  • iva_rate (str | None)

  • iva_amount (str | None)

  • iva_category (str | None)

  • counterparty_eu_member_state (str | None)

  • irpf_category (str | None)

  • usage_ratio_id (str | None)

  • prorrata_reference (str | None)

  • purchase_invoice_evidence_id (str | None)

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

  • notes (str)

  • lifecycle_state (Annotated[str, MinLen(min_length=1)])

  • classified_by (Annotated[str, MinLen(min_length=1)])

  • classified_at (str | None)

  • classification_reason (str)

  • classification_confidence (str | None)

  • source_jurisdiction (str | None)

  • value_in_eur (str | None)

  • fx_rate (str | None)

  • created_at (str)

  • modified_at (str)

  • review_status (LedgerReviewStatus)

review_status: LedgerReviewStatus
class LedgerTransactionResultPayload(**data)[source]

Bases: BaseModel

Canonical projection for a single ledger mutation/read result.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • review_status (LedgerReviewStatus)

  • transaction (LedgerTransactionPayload)

bucket_id: BucketId
transaction_id: TransactionId
review_status: LedgerReviewStatus
transaction: LedgerTransactionPayload
class LedgerTransactionTrackingPayload(**data)[source]

Bases: BaseModel

Durable event lineage fields for one ledger transaction.

Parameters:
transaction_id: TransactionId
created_event_id: str | None
evidence_provenance: tuple[TransactionEvidenceProvenanceEntry, ...]
edit_lineage: tuple[TransactionEditLineageEntry, ...]
lifecycle_state: str
lifecycle_lineage: tuple[TransactionLifecycleLineageEntry, ...]
class SplitChildCommand(**data)[source]

Bases: BaseModel

One slice of an N-way split.

Variables:

  • amount – Non-negative magnitude Decimal in the parent’s currency; direction is inherited from the parent (the split builder copies parent.direction onto every child).

  • description – Non-blank narrative for this slice.

  • counterparty – Optional override; falls back to the parent’s counterparty when None.

  • booked_date – Optional override; falls back to the parent’s booked_date.

  • value_date – Optional override; falls back to the parent’s value_date.

Parameters:

  • amount (Decimal)

  • description (str)

  • counterparty (str | None)

  • booked_date (date | None)

  • value_date (date | None)

amount: Decimal
description: str
counterparty: str | None
booked_date: date | None
value_date: date | None
class SplitTransactionResult(**data)[source]

Bases: BaseModel

Backend result of a successful N-way split.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • parent_transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • split_group_id (str)

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

  • parent_transaction (Transaction)

  • child_transactions (tuple[Transaction, ...])

  • bucket_event_id (str)

bucket_id: BucketId
parent_transaction_id: TransactionId
split_group_id: str
child_transaction_ids: tuple[str, ...]
parent_transaction: Transaction
child_transactions: tuple[Transaction, ...]
bucket_event_id: str
class MergeTransactionsResult(**data)[source]

Bases: BaseModel

Backend result of a successful split re-merge.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • split_group_id (str)

  • parent_transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • merged_transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

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

  • merged_transaction (Transaction)

  • parent_transaction (Transaction)

  • bucket_event_id (str)

bucket_id: BucketId
split_group_id: str
parent_transaction_id: TransactionId
merged_transaction_id: TransactionId
source_child_ids: tuple[str, ...]
merged_transaction: Transaction
parent_transaction: Transaction
bucket_event_id: str
class LedgerImportOperationResult(**data)[source]

Bases: BaseModel

Backend result for an imported ledger transaction batch.

Parameters:
summary: ImportSummary
import_batch_id: str | None
bucket_event_ids: tuple[str, ...]
class LedgerSourceValidationReport(**data)[source]

Bases: BaseModel

Backend read model for source-provider validation details.

Parameters:
valid: bool
warnings: tuple[str, ...]
encoding: str | None
dialect: str | None
class LedgerSourceVerificationReport(**data)[source]

Bases: BaseModel

Backend read model for optional source-file verification.

Parameters:

  • requested (bool)

  • path (str | None)

  • sha256 (str | None)

requested: bool
path: str | None
sha256: str | None
class LedgerImportDiagnosticReport(**data)[source]

Bases: BaseModel

Backend read model for one persisted or dry-run import diagnostic.

Parameters:

  • kind (str)

  • severity (str)

  • message (str)

  • source_path (str | None)

  • source_locator (str | None)

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

kind: str
severity: str
message: str
source_path: str | None
source_locator: str | None
affected_transaction_ids: tuple[str, ...]
class LedgerSourceImportCommand(**data)[source]

Bases: BaseModel

Backend command for importing ledger rows from an operator source file.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)] | None)

  • path (Path)

  • provider (str)

  • dry_run (bool)

  • verify (bool)

  • source (Path | None)

  • period (Period | None)

  • actor (str)

  • source_command (str)

bucket_id: BucketId | None
path: Path
provider: str
dry_run: bool
verify: bool
source: Path | None
period: Period | None
actor: str
source_command: str
class LedgerSourceImportResult(**data)[source]

Bases: BaseModel

Backend result for source-file import diagnostics and persistence.

Parameters:
rows: int
imported: int
skipped: int
likely_duplicates: int
dry_run: bool
verify: bool
period: Period | None
bucket_id: BucketId | None
import_batch_id: str | None
bucket_event_ids: tuple[str, ...]
imported_transaction_refs: tuple[BucketTransactionRef, ...]
skipped_transaction_refs: tuple[BucketTransactionRef, ...]
likely_duplicate_transaction_refs: tuple[BucketTransactionRef, ...]
validation: LedgerSourceValidationReport
source: LedgerSourceVerificationReport
diagnostics: tuple[LedgerImportDiagnosticReport, ...]
class LedgerReviewQuery(**data)[source]

Bases: BaseModel

Backend query for operator review rows in one bucket ledger.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • period (Period | None)

  • status (str | None)

  • issue (str | None)

  • import_id (str | None)

  • classification (str | None)

  • text (str | None)

  • direction (str | None)

  • transaction_id (str | None)

bucket_id: BucketId
period: Period | None
status: str | None
issue: str | None
import_id: str | None
classification: str | None
text: str | None
direction: str | None
transaction_id: str | None
class LedgerReviewRow(**data)[source]

Bases: BaseModel

Backend projection for one ledger review row.

Parameters:
id: str
date: str
amount: str
description: str
status: str
transaction: LedgerTransactionPayload | None
class LedgerReviewQueryResult(**data)[source]

Bases: BaseModel

Backend result for operator ledger review queries.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • rows (tuple[LedgerReviewRow, ...])

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

bucket_id: BucketId
rows: tuple[LedgerReviewRow, ...]
filters: tuple[str, ...]
class LedgerStatusReport(**data)[source]

Bases: BaseModel

Backend read model summarizing one bucket’s ledger transaction state.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • business_income_total (str)

  • business_expense_total (str)

  • business_net_total (str)

  • total_count (int)

  • active_count (int)

  • archived_count (int)

  • stashed_count (int)

  • split_count (int)

  • pending_review_count (int)

  • reviewed_count (int)

  • skipped_count (int)

  • period (Period | None)

  • checked_transaction_count (int)

  • readiness_issue_count (int)

  • ready (bool | None)

bucket_id: BucketId
business_income_total: str
business_expense_total: str
business_net_total: str
total_count: int
active_count: int
archived_count: int
stashed_count: int
split_count: int
pending_review_count: int
reviewed_count: int
skipped_count: int
period: Period | None
checked_transaction_count: int
readiness_issue_count: int
ready: bool | None
class LedgerRemovalBlocker(**data)[source]

Bases: BaseModel

Finalized modelo revision that prevents ledger transaction removal.

Parameters:

  • work_unit_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • calculation_revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • revision_state (str)

  • modelo (str)

  • filing_year (int)

  • period (str)

work_unit_id: WorkUnitId
calculation_revision_id: CalculationRevisionId
revision_state: str
modelo: str
filing_year: int
period: str
class LedgerTransactionRemovalReport(**data)[source]

Bases: BaseModel

Backend report for one bucket-local ledger transaction removal.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • removed (bool)

  • dry_run (bool)

  • actor (str)

  • reason (str)

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

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

  • blocking_modelo_references (tuple[LedgerRemovalBlocker, ...])

  • stale_draft_revision_references (tuple[LedgerRemovalBlocker, ...])

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

bucket_id: BucketId
transaction_id: TransactionId
removed: bool
dry_run: bool
actor: str
reason: str
cascaded_purchase_invoice_evidence_ids: tuple[str, ...]
cascaded_attachment_ids: tuple[str, ...]
blocking_modelo_references: tuple[LedgerRemovalBlocker, ...]
stale_draft_revision_references: tuple[LedgerRemovalBlocker, ...]
bucket_event_ids: tuple[str, ...]
class LedgerCatalogueResetReport(**data)[source]

Bases: BaseModel

Backend report for a protected bucket-local ledger catalogue reset.

Parameters:
bucket_id: BucketId
removed_transaction_ids: tuple[str, ...]
reset: bool
dry_run: bool
actor: str
reason: str
cascaded_purchase_invoice_evidence_ids: tuple[str, ...]
cascaded_attachment_ids: tuple[str, ...]
blocking_modelo_references: tuple[LedgerRemovalBlocker, ...]
stale_draft_revision_references: tuple[LedgerRemovalBlocker, ...]
bucket_event_ids: tuple[str, ...]
class LedgerExportCommand(**data)[source]

Bases: BaseModel

Backend command for exporting one bucket’s canonical ledger rows.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • export_format (ExportSerializationFormat)

  • include_inactive (bool)

  • output_path (Path | None)

  • period (Period | None)

  • actor (str)

  • source_command (str)

bucket_id: BucketId
export_format: ExportSerializationFormat
include_inactive: bool
output_path: Path | None
period: Period | None
actor: str
source_command: str
class BulkClassifyRow(**data)[source]

Bases: BaseModel

One row from a ledger classify --from-csv CSV input file.

Required columns: transaction_id, classification. Optional columns: category_id, business_pct, usage_ratio_id, taxable_base, iva_rate, iva_amount, iva_category, irpf_category. Unknown column names are rejected pre-persistence to protect against silent field mis-mapping. The IVA facts (taxable_base, iva_rate, iva_amount) are typed Decimal exactly as the single-classify path coerces them, so a malformed value reds the row rather than coercing silently.

Parameters:
transaction_id: str
classification: BusinessClassification
category_id: str | None
business_pct: Decimal | None
usage_ratio_id: str | None
taxable_base: Decimal | None
iva_rate: Decimal | None
iva_amount: Decimal | None
iva_category: IvaCategory | None
irpf_category: str | None
class BulkClassifyFailure(**data)[source]

Bases: BaseModel

One failed row from a ledger classify --from-csv operation.

Parameters:

  • row_index (int)

  • transaction_id (str)

  • reason (str)

row_index: int
transaction_id: str
reason: str
class BulkClassifyResult(**data)[source]

Bases: BaseModel

Aggregate result for a ledger classify --from-csv operation.

Uses partial-success semantics matching the ledger import pattern: all parseable rows that pass validation are applied; failures are collected into failures and reported without aborting the batch.

Parameters:
total: int
applied: int
skipped: int
failures: tuple[BulkClassifyFailure, ...]
bucket_event_ids: tuple[str, ...]
class ApplyRulesAppliedRow(**data)[source]

Bases: BaseModel

One successfully rule-applied transaction from ledger rule apply.

Parameters:
transaction_id: str
matched_rule_id: str
classification: BusinessClassification
class ApplyRulesResult(**data)[source]

Bases: BaseModel

Aggregate result for a ledger rule apply operation.

Parameters:
rules_evaluated: int
transactions_scanned: int
matched: int
skipped_already_classified: int
no_match: int
applied: tuple[ApplyRulesAppliedRow, ...]
bucket_event_ids: tuple[str, ...]
class LedgerExportRow(**data)[source]

Bases: BaseModel

One serialized ledger transaction row exported from the canonical catalogue.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • transaction_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • lifecycle_state (str)

  • booked_date (str)

  • value_date (str)

  • effective_date (str)

  • amount (str)

  • currency (str)

  • direction (str)

  • counterparty (str)

  • description (str)

  • business_classification (str)

  • business_pct (str)

  • category_id (str)

  • taxable_base (str)

  • iva_rate (str)

  • iva_amount (str)

  • iva_category (str)

  • counterparty_eu_member_state (str)

  • irpf_category (str)

  • usage_ratio_id (str)

  • prorrata_reference (str)

  • purchase_invoice_evidence_id (str)

  • attachment_ids (str)

  • notes (str)

  • created_by (str)

  • created_source_command (str)

  • source_jurisdiction (str)

  • value_in_eur (str)

  • fx_rate (str)

bucket_id: BucketId
transaction_id: TransactionId
lifecycle_state: str
booked_date: str
value_date: str
effective_date: str
amount: str
currency: str
direction: str
counterparty: str
description: str
business_classification: str
business_pct: str
category_id: str
taxable_base: str
iva_rate: str
iva_amount: str
iva_category: str
counterparty_eu_member_state: str
irpf_category: str
usage_ratio_id: str
prorrata_reference: str
purchase_invoice_evidence_id: str
attachment_ids: str
notes: str
created_by: str
created_source_command: str
source_jurisdiction: str
value_in_eur: str
fx_rate: str
class LedgerExportResult(**data)[source]

Bases: BaseModel

Backend result for an exported canonical ledger transaction snapshot.

Parameters:
bucket_id: BucketId
export_id: str
export_format: ExportSerializationFormat
media_type: str
filename_extension: str
row_count: int
byte_size: int
sha256: str
fieldnames: tuple[str, ...]
rows: tuple[LedgerExportRow, ...]
payload: bytes
bucket_event_ids: tuple[str, ...]