aeat.domain.invoices._enums module

Closed enumerations for invoice records.

Defines IvaRate and PaymentStatus together with the iva_rate_percentage() helper that resolves the numeric Decimal percentage backing each IvaRate member.

The percentage helper queries the centralized IVA substrate at aeat.domain.iva rather than carrying its own rate literals. IvaRate keeps its closed-taxonomy role for invoice records; the legal-grade percentage value lives in registry/aeat/iva/rates.toml and is dated.

class IvaRate(*values)[source]

Bases: StrEnum

Closed taxonomy of Spanish IVA rate slots used on invoice lines.

The slot names map to substrate aeat.domain.iva.IvaRateKind tiers and the percentage backing each slot is resolved against aeat.domain.iva.lookup_rate() for Spain at a given date. This module no longer stores rate percentages as Python literals; if the legal rate changes, the substrate’s TOML registry is the single source of truth.

RATE_5 (a transient 2022-2024 rate) is intentionally absent from this slot taxonomy. If a future workflow ingests pre-2025 data this enum and the slot mapping below must be extended in sync with a corresponding registry rate entry.

Variables:

  • RATE_0 – Zero-rated supply.

  • RATE_4 – Super-reduced rate slot (LIVA art. 91 Dos).

  • RATE_10 – Reduced rate slot (LIVA art. 91 Uno).

  • RATE_21 – General rate slot (LIVA art. 90 Uno).

  • EXEMPT – Exempt operation; no numeric percentage.

  • NOT_SUBJECT – Operation outside the scope of IVA; no numeric percentage.

RATE_0
RATE_4
RATE_10
RATE_21
EXEMPT
NOT_SUBJECT
class PaymentStatus(*values)[source]

Bases: StrEnum

Lifecycle states for an invoice payment.

Variables:

  • PAID – Settled in full.

  • PENDING – Awaiting payment within agreed terms.

  • PARTIALLY_PAID – Partially settled; remainder outstanding.

  • OVERDUE – Past the due date and still outstanding.

  • CANCELLED – Cancelled, regardless of whether previously paid.

PAID
PENDING
PARTIALLY_PAID
OVERDUE
CANCELLED
iva_rate_percentage(rate, on_date=None)[source]

Return the fractional percentage backing rate at on_date.

Slot membership in IvaRate is structural; the actual percentage is resolved against aeat.domain.iva.lookup_rate() for Spain at on_date. When on_date is omitted the lookup uses today’s date.

Parameters:

  • rate (IvaRate) – IVA rate slot.

  • on_date (date | None) – Date at which to resolve the rate percentage. Defaults to date.today().

Return type:

Decimal | None

Returns:

Decimal("0") for IvaRate.RATE_0; the substrate’s rate as a fractional Decimal (pct/100) for the RATE_4 / RATE_10 / RATE_21 slots; None for IvaRate.EXEMPT and IvaRate.NOT_SUBJECT.

iva_rate_kind(rate)[source]

Return the substrate rate tier for an invoice line rate slot.

NOT_SUBJECT has no OSS/IOSS rate tier because it is outside the taxable-supply universe; callers that need a Modelo 369 candidate should skip or reject it explicitly. Numeric and exempt slots return their corresponding IvaRateKind.

Return type:

IvaRateKind | None

Parameters:

rate (IvaRate)

numeric_iva_rate_percentages()[source]

Return the integer-percentage values for the numeric IvaRate slots.

Parses the RATE_<n> member names of IvaRate to derive the closed set of integer percentages the CLI boundary accepts on --set iva.rate. IvaRate.EXEMPT and IvaRate.NOT_SUBJECT carry no numeric percentage and are excluded.

The derivation is structural — the RATE_ prefix is stripped and the remainder is parsed as an integer — so the returned set tracks IvaRate membership without re-listing 0 / 4 / 10 / 21 as literals.

Return type:

frozenset[Decimal]

Returns:

A frozenset of Decimal integer percentages; for the current taxonomy frozenset({Decimal("0"), Decimal("4"), Decimal("10"), Decimal("21")}).