Skip to content

API reference

NIF

validateNif(input: string): boolean

Validates a NIF: 9 digits, a recognised leading digit/range, and the mod-11 check digit. Accepts a PT prefix, spaces and dots.

normalizeNif(input: string): string

Strips a leading PT, spaces and dots.

entityType(input: string): NifEntityType

Classifies the taxpayer by its leading digit(s) — e.g. 'singular', 'coletiva', 'administracao-publica', 'fundo-investimento'. Returns 'desconhecido' for malformed input.

entityTypeLabel(input: string): string

Human-readable Portuguese label for the entity type.

IBAN

validateIban(input: string): boolean

Validates any IBAN via the ISO 7064 mod-97 checksum.

validatePortugueseIban(input: string): boolean

As above, but also requires the PT country code and the 25-character length.

normalizeIban(input: string): string

Uppercases and removes spaces.

formatIban(input: string): string

Groups the IBAN into blocks of four ("PT50 0002 0123 ...").

Postal code

validatePostalCode(input: string): boolean

Validates the CP7 format NNNN-NNN.

formatPostalCode(input: string): string | null

Normalizes "1234567" / "1234 567" into "1234-567"; returns null if it doesn't have 7 digits.

ATCUD

buildAtcud(parts: AtcudParts): string

Builds "<validationCode>-<sequence>". Throws if the validation code isn't uppercase-alphanumeric or the sequence isn't a positive integer.

interface AtcudParts {
  validationCode: string; // AT-issued series validation code
  sequence: number;       // >= 1
}

validateAtcud(input: string): boolean

Validates an ATCUD string, including the "0" pre-registration fallback.

Invoice QR code

buildInvoiceQRCode(data: InvoiceQRData): string

Composes the AT QR-code field string (A:...*B:...*...). Render the returned string with any QR library. See Invoicing for the full field reference.