aeat.core.identity package

Spanish identity-document parsing and validation.

Public surface for NIF / NIE / CIF documents — the identity-number shapes Spanish taxpayers and legal entities use in tax filings. The module is intentionally tiny:

  • IdentityDocument — closed enum.StrEnum naming the three document kinds.

  • validate_identity() — parses a candidate string and returns the matching IdentityDocument on success.

  • validate_spanish_tax_id() — pure-string validator that returns the canonical form rather than the kind enum, used by call sites that only need to check well-formedness.

  • IdentityError — typed failure shape that registers under the stable error code INTEGRITY_IDENTITY_DOCUMENT.

  • SubjectTaxId — pydantic-ready alias for fields that must carry a validated Spanish tax identifier.

The module lives in core because identity validation is a domain concern, not a persistence concern. The persistence layer’s redaction rule patterns remain permissive (over-redaction is the safer failure mode); domain code that needs a strict yes/no answer consumes this module instead.

Submodules