aeat.core.identity._documents module

NIF / NIE / CIF parser and check-letter validator.

The three document shapes:

  • NIF (Número de Identificación Fiscal): 8 digits, or a leading K/L/M plus 7 digits for natural persons without DNI/NIE, followed by 1 check letter. Check letter computed from the numeric portion via "TRWAGMYFPDXBNJZSQVHLCKE"[number % 23].

  • NIE (Número de Identidad de Extranjero): leading X / Y / Z + 7 digits + 1 check letter. Used by foreigners resident in Spain. Check letter computed by replacing the leading letter with 0 / 1 / 2 respectively, then applying the same table as NIF.

  • CIF (Código de Identificación Fiscal): leading letter (A-H, J, N, P-S, U, V, W) + 7 digits + 1 check character. Used by legal entities. The check character is either a digit or a letter depending on the leading kind code; the algorithm is the Luhn-style sum-of-doubled- odd-digits method described by AEAT.

The public validate_identity() parser returns an IdentityDocument member and raises IdentityError on malformed input. It accepts mixed case, trims surrounding whitespace, and rejects values whose check letter does not match the algorithm, not just shape mismatches. Callers that only need the canonical string form use validate_spanish_tax_id() from the sibling tax-id module.

class IdentityDocument(*values)[source]

Bases: StrEnum

Closed catalogue of recognised Spanish identity-document kinds.

Variables:

  • NIF – Número de Identificación Fiscal — Spanish nationals.

  • NIE – Número de Identidad de Extranjero — foreign residents.

  • CIF – Código de Identificación Fiscal — legal entities.

NIF
NIE
CIF
exception IdentityError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatError, ValueError

Raised when a candidate string is not a valid Spanish identity document.

Bound to the registered error code INTEGRITY_IDENTITY_DOCUMENT in aeat.core.errors.ERROR_REGISTRY. Carries a human-readable diagnostic that names the failing shape (NIF, NIE, CIF) and, where relevant, the expected vs observed check character.

Inherits from ValueError so that pydantic’s AfterValidator can wrap it directly into a ValidationError without a re-raise shim.

Parameters:

  • message (str | None)

  • context (dict[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
nif_check_letter(number)[source]

Return the AEAT NIF / NIE check letter for a numeric body.

Implements the AEAT control-letter table _NIF_LETTERS (TRWAGMYFPDXBNJZSQVHLCKE) indexed by number % 23. This is the single source of the check-letter computation for the whole aeat.core.identity package; the sibling aeat.core.identity._tax_id re-exports it rather than re-declaring the % 23 expression, and every enum-returning validator in this module computes its expected letter through it.

Return type:

str

Parameters:

number (int)

validate_identity(candidate)[source]

Parse and check-letter-validate a Spanish identity document.

Disambiguates by leading character: K/L/M route to prefixed NIF, X/Y/Z route to NIE, leading letters in _CIF_KIND_LETTERS route to CIF, and everything else is attempted as NIF. The check-letter / check-digit algorithm is then applied for the chosen shape and the parsed IdentityDocument is returned.

Parameters:

candidate (object) – A free-form candidate value. Strings tolerate surrounding whitespace, dashes, spaces, and casing; non-string values are rejected with a typed IdentityError.

Return type:

IdentityDocument

Returns:

The matching IdentityDocument enum member.

Raises:

IdentityError – When candidate is not a string, is empty, or does not match any valid shape, or when the check letter or digit fails the AEAT algorithm.