aeat.core.identity._nif_iva module

EU intra-community NIF-IVA (VAT identification number) format authority.

A counterparty’s intra-community VAT number — the NIF-IVA intracomunitario declared on Modelo 303 / Modelo 349 — has a distinct structural format for each EU Member State. AEAT’s M349 validator (and the VIES registry behind it) bounces a number whose shape does not match its country’s published pattern, so the only defence against silently building an un-fileable declaration is to validate the structure (not live VIES existence) at the boundary where the number is accepted.

This module is the single typed authority for that closed, regulatory-shaped table, per the central-config discipline: the country -> pattern set lives here in core, not inlined as a literal in a feature module. Consumers (the ledger invoice counterparty boundary today; the Modelo 349 manual-entry row in future) resolve a Member State’s expected shape through nif_iva_format_for_country() and refuse a malformed number with an instructive, format-naming diagnostic.

Authority: the European Commission VIES national VAT-number structure rules (https://ec.europa.eu/taxation_customs/vies/), grounded in Council Directive 2006/112/EC. Spain (ES) is deliberately absent: a Spanish identifier is validated by the dedicated checksum authority validate_spanish_tax_id(), not by a structural pattern. Northern Ireland (XI) is included because its post-Brexit goods VAT prefix mirrors the GB structure and is accepted in intra-community contexts.

class NifIvaPrefix(*values)[source]

Bases: StrEnum

Closed set of EU VIES VAT-number country prefixes (plus Northern Ireland).

The values are the two-character prefix that leads the VAT number, which for every Member State equals its ISO 3166-1 alpha-2 code except Greece, whose VAT prefix is EL while its ISO code is GR. Spain (ES) is excluded: Spanish identifiers route through core.identity.validate_spanish_tax_id(). XI is the post-Brexit Northern Ireland goods prefix accepted in intra-community contexts.

AT
BE
BG
CY
CZ
DE
DK
EE
EL
FI
FR
HR
HU
IE
IT
LT
LU
LV
MT
NL
PL
PT
RO
SE
SI
SK
XI
class NifIvaFormatSpec(prefix, country_name, pattern, description, example)[source]

Bases: object

The structural format of one Member State’s NIF-IVA.

Variables:

  • prefix – The leading VAT prefix this spec validates.

  • country_name – Human-readable country name for instructive diagnostics.

  • pattern – Anchored regex matched against the full normalised VAT number (prefix included).

  • description – Operator-facing description of the expected shape, e.g. "DE + 9 digits".

  • example – A well-formed example number for the instructive refusal.

Parameters:
prefix: NifIvaPrefix
country_name: str
pattern: Pattern[str]
description: str
example: str
normalise_nif_iva(value)[source]

Return the uppercased VAT number with whitespace and separators stripped.

Operators routinely paste numbers carrying spaces, dots, or hyphens (BE 0123.456.789); the canonical form drops them so the structural pattern matches.

Return type:

str

Parameters:

value (str)

nif_iva_prefix_for_country(iso_country)[source]

Resolve an ISO-3166 alpha-2 country code (or VAT prefix) to its NifIvaPrefix.

Returns None for a country that has no NIF-IVA pattern (a non-EU counterparty, or Spain which uses the checksum validator).

Return type:

NifIvaPrefix | None

Parameters:

iso_country (str)

nif_iva_format_for_country(iso_country)[source]

Return the NifIvaFormatSpec for a country, or None if unknown.

A None result means the country is not an EU Member State carrying a structural NIF-IVA pattern; the caller applies its generic prefix/body check instead of refusing the counterparty outright.

Return type:

NifIvaFormatSpec | None

Parameters:

iso_country (str)