aeat.application.aggregation._oss_ioss module¶

Modelo 369 OSS/IOSS source-mesh resolver and candidate validator.

The ledger_oss_aggregation source projects OSS/IOSS-tagged issued invoices from the bucket’s InvoiceCatalogueRepository into substrate-classified OssIossLedgerCandidate rows. Pre-classified callers can also pass candidates directly. Each candidate is validated against the destination Member State’s published IVA rate through domain.iva.lookup_rate() and becomes a registry-ready OssIossLedgerObservation.

Per the OSS / IOSS regulation suite, the IVA amount on each line MUST match the destination Member State’s published rate for the chosen rate tier on the supply date. A persisted IVA amount that disagrees with the lookup is a data-quality blocker: the wrapper rejects it before the registry resolver sees it, so calculation revisions never land on inconsistent ledger facts.

The OssIossLedgerSourceResolver returns a CalculationSourceResolution with resolved binding values, transaction provenance, and non-blocking diagnostics for empty live catalogues or declarable OSS observations that no ledger_oss_aggregation binding consumes.

class OssIossLedgerCandidate(**data)[source]¶

Bases: BaseModel

One un-validated ledger line tagged with substrate classification.

The candidate is the application-layer hand-off shape: a ledger line carrying the four classification axes the Modelo 369 binding selectors require, plus the base and IVA amounts the bucket persists. The validate_oss_ioss_observation() function turns a candidate into a registry-ready OssIossLedgerObservation once the persisted IVA amount has been checked against the destination MS rate.

Variables:

ledger_id – Stable id of the source ledger line.
transaction_date – When the supply takes place. Drives the rate lookup.
regime – OSS / IOSS Esquema the line is filed under.
destination_member_state – Member State of consumption per the OSS / IOSS place-of-supply rules.
rate_kind – Substrate rate tier (general / reduced / etc.).
invoice_direction – Whether the autónomo issued or received the invoice.
transaction_kind – Substrate domain.iva.TransactionKind the line resolves to.
base_amount – Taxable base in EUR. Must be non-negative.
iva_amount – IVA amount in EUR persisted on the ledger. Must be non-negative.

Parameters:

ledger_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_date (date)
regime (OssIossRegime)
destination_member_state (EUMemberState)
rate_kind (IvaRateKind)
invoice_direction (InvoiceKind)
transaction_kind (TransactionKind)
base_amount (Decimal)
iva_amount (Decimal)

ledger_id: _LedgerId¶

transaction_date: date¶

regime: OssIossRegime¶

destination_member_state: EUMemberState¶

rate_kind: IvaRateKind¶

invoice_direction: InvoiceKind¶

transaction_kind: TransactionKind¶

base_amount: Decimal¶

iva_amount: Decimal¶

validate_oss_ioss_observation(candidate)[source]¶

Validate candidate and return the registry-ready observation.

Looks up the destination Member State’s rate at the supply date, derives the expected IVA amount from base_amount and the looked-up rate, and rejects the candidate if the persisted iva_amount deviates from the derived value by more than _IVA_TOLERANCE (one cent).

Parameters:: candidate (OssIossLedgerCandidate) – The substrate-classified ledger line to validate.
Return type:: OssIossLedgerObservation
Returns:: A registry-ready OssIossLedgerObservation carrying the same identifier, supply date, classification axes, base amount, and persisted IVA amount as the candidate.
Raises:: AggregationValidationError – When the persisted IVA amount disagrees with the destination MS rate by more than the one-cent tolerance.

validate_oss_ioss_observations(candidates)[source]¶

Validate every candidate; raise on the first failure.

Parameters:: candidates (Iterable[OssIossLedgerCandidate]) – The substrate-classified ledger lines to validate.
Return type:: tuple[OssIossLedgerObservation, ...]
Returns:: A tuple of registry-ready OssIossLedgerObservation records in input order.

aggregate_oss_ioss_bindings(revision, candidates)[source]¶

Validate candidates then resolve every ledger_oss_aggregation binding.

Pipeline:

Each candidate is validated through validate_oss_ioss_observation(), which checks the persisted IVA against the destination MS rate.
The validated observations are handed off to the registry’s resolve_ledger_oss_aggregation_binding_values() resolver, which filters by every binding’s selector and aggregates the matched lines.

Parameters:

revision (ModeloRevision) – The Modelo 369 ModeloRevision whose ledger_oss_aggregation bindings should be resolved.
candidates (Sequence[OssIossLedgerCandidate]) – Substrate-classified ledger lines for the period.

Return type:

dict[TypeAliasType, Decimal]

Returns:

A mapping from each binding id on the revision to its aggregated Decimal value.

oss_ioss_candidates_from_repositories(*, bucket_id, period, invoice_repository=None)[source]¶

Project OSS/IOSS-tagged issued invoices into Modelo 369 ledger candidates.

Parameters:

bucket_id (str) – Active bucket id for the default invoice repository.
period (Period) – Filing period whose date span filters issued invoices.
invoice_repository (InvoiceCatalogueRepository | None) – Optional InvoiceCatalogueRepository used instead of the active bucket repository.

Return type:

tuple[OssIossLedgerCandidate, ...]

Returns:

A tuple of OssIossLedgerCandidate rows projected from issued invoices in the period.

aggregate_oss_ioss_from_repositories(revision, *, bucket_id, period, invoice_repository=None)[source]¶

Resolve Modelo 369 OSS/IOSS bindings from the live invoice catalogue.

Parameters:

revision (ModeloRevision) – The ModeloRevision whose OSS/IOSS bindings are resolved.
bucket_id (str) – Active bucket id for the default invoice repository.
period (Period) – Filing period whose date span filters issued invoices.
invoice_repository (InvoiceCatalogueRepository | None) – Optional InvoiceCatalogueRepository used instead of the active bucket repository.

Return type:

dict[TypeAliasType, Decimal]

class OssIossLedgerSourceResolver(*, candidates=None, invoice_repository=None)[source]¶

Bases: object

Source mesh resolver for Modelo 369 OSS / IOSS ledger candidates.

Parameters:

candidates (Sequence[OssIossLedgerCandidate] | None)
invoice_repository (InvoiceCatalogueRepository | None)

resolver_id¶

owned_sources: tuple[BindingSourceKind, ...]¶

resolve(context)[source]¶

Validate candidates and return the resolved OSS/IOSS binding values.

Validates every candidate through validate_oss_ioss_observation() then delegates to the registry’s resolve_ledger_oss_aggregation_binding_values to aggregate the matched lines per binding selector.

When the resolver is constructed with explicit candidates, those candidates are folded directly. When candidates is omitted, the live operator path projects OSS/IOSS-tagged issued invoices from the invoice repository into candidates first. If no candidate is available, the resolver still CLAIMS ledger_oss_aggregation (so the binding compiles and is not flagged as a novel source) but surfaces one non-blocking oss_no_live_source advisory per declared OSS binding. This keeps a Modelo 369 OSS cuota from resolving to a SILENT claimed-zero when the catalogue carries no classifiable OSS invoices.

Parameters:: context (CalculationSourceContext) – The CalculationSourceContext carrying the ModeloRevision whose ledger_oss_aggregation bindings should be resolved.
Return type:: CalculationSourceResolution
Returns:: A CalculationSourceResolution with resolved binding values, source transaction ids, and per-observation provenance records — or, when no candidates were supplied, an empty resolution carrying one oss_no_live_source advisory per declared OSS binding when no candidates can be projected.
Raises:: AggregationValidationError – When any candidate’s persisted IVA amount disagrees with the destination Member State rate by more than one cent.