aeat.domain.invoices._validators module

Counterparty identity validators for invoice records.

The EU-IVA prefix check and ISO-3166 alpha-2 country-code normaliser remain in this module because they are invoice-domain concerns. Each helper raises ValueError on failure so pydantic surfaces the error as a validation error in the enclosing Invoice model.

The registry-grounded helpers is_eu_member_state_code() and assert_eu_member_state_code() anchor the EU axis to the substrate’s aeat.domain.iva.EUMemberState enum. Modelo 369 binding selectors and the OSS / IOSS classifier boundary checks consume these helpers so the EU membership decision flows from the substrate, not from a hand-maintained list.

EU_MEMBER_STATE_CODES: frozenset[str]

Closed set of ISO-3166 alpha-2 codes (uppercase) for the 27 EU Member States, sourced from aeat.domain.iva.EUMemberState while excluding the Northern Ireland IVA prefix XI.

validate_country_code(value)

Normalise and validate an ISO-3166 alpha-2 country code.

Parameters:

value (str) – Raw country code to validate.

Return type:

str

Returns:

The uppercased two-letter country code.

Raises:

InvoiceValidationError – If the input is not exactly two alphabetic characters.

is_eu_member_state_code(value)

Return True when value matches one of the 27 EU Member State codes.

The membership check is anchored to aeat.domain.iva.EUMemberState; if the substrate’s enum changes (Brexit-style additions or withdrawals) the helper picks up the new shape automatically.

Parameters:

value (str) – Raw country code to check.

Return type:

bool

Returns:

True when value normalises to one of the 27 EU codes.

assert_eu_member_state_code(value)

Validate value and assert it names an EU Member State.

Parameters:

value (str) – Raw country code to validate.

Return type:

str

Returns:

The uppercased two-letter EU Member State code.

Raises:

InvoiceValidationError – If the input is malformed or names a non-EU country.

validate_iva_number(value, country)

Validate a non-ES IVA number shape against its country format.

For an EU Member State (and Northern Ireland XI) the number is matched against the country’s published NIF-IVA structural pattern, sourced from the central aeat.core.identity.NIF_IVA_FORMATS authority: a malformed intra-community VAT number is bounced by AEAT’s Modelo 349 validator, so the refusal names the country and the expected format. Live VIES existence is not checked — only the structure. For a non-EU counterparty (no published pattern) the helper falls back to a generic leading-prefix plus 4-20 character alphanumeric body check, so non-EU counterparties remain acceptable.

Parameters:

• value (str) – Raw IVA identifier to validate.

• country (str) – ISO-3166 alpha-2 country code already validated.

Return type:

str

Returns:

The uppercased, whitespace-trimmed IVA identifier.

Raises:

InvoiceValidationError – If the value is malformed, the prefix does not match country, or the EU NIF-IVA format does not match.