cadrumo.core.identity.nif_iva module

EU intra-community NIF-IVA identification-number format authority.

A counterparty’s intra-community IVA 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 typed kernel for that regulatory-shaped value. The country, prefix, and pattern records live in the non-Modelo facts registry; this module keeps only the opaque projected token, compiled-pattern value object, and normalisation mechanics. Consumers (the ledger invoice counterparty boundary today; the Modelo 349 manual-entry row in future) resolve a Member State’s expected shape through the domain registry and refuse a malformed number with an instructive, format-naming diagnostic.

Authority: the European Commission VIES national IVA-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 IVA prefix mirrors the GB structure and is accepted in intra-community contexts.

class NifIvaPrefix(value, *, _registry_validated=False)[source]

Bases: StrictRegistryToken

Opaque NIF-IVA prefix projected from the facts registry.

Membership is deliberately not represented by a Python enum. The registry owns the 27 prefixes, including the GR -> EL country divergence and XI. A token can only be constructed by the typed registry projection.

Parameters:

  • value (str)

  • _registry_validated (bool)

Return type:

Self

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 IVA prefix this spec validates.

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

  • pattern – Anchored regex matched against the full normalised IVA 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 IVA 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)

is_nif_iva_structurally_shaped(value)[source]

Return whether value has a generic prefixed tax-identifier shape.

This is deliberately only lexical structure. Country membership and dated per-country patterns are domain-registry policy and are resolved by cadrumo.domain.calculations.registry.nif_iva_catalogue.

Return type:

bool

Parameters:

value (str)