Referência da API

NIF

validateNif(input: string): boolean

Valida um NIF: 9 dígitos, um dígito/gama inicial reconhecido e o dígito de controlo mod-11. Aceita prefixo PT, espaços e pontos.

normalizeNif(input: string): string

Remove um PT inicial, espaços e pontos.

entityType(input: string): NifEntityType

Classifica o contribuinte pelo(s) dígito(s) inicial(is) — ex.: 'singular', 'coletiva', 'administracao-publica', 'fundo-investimento'. Devolve 'desconhecido' para entrada malformada.

entityTypeLabel(input: string): string

Descrição legível em português do tipo de entidade.

IBAN

validateIban(input: string): boolean

Valida qualquer IBAN pelo checksum ISO 7064 mod-97.

validatePortugueseIban(input: string): boolean

Como acima, mas exige também o código de país PT e o comprimento de 25 caracteres.

normalizeIban(input: string): string

Passa a maiúsculas e remove espaços.

formatIban(input: string): string

Agrupa o IBAN em blocos de quatro ("PT50 0002 0123 ...").

Código postal

validatePostalCode(input: string): boolean

Valida o formato CP7 NNNN-NNN.

formatPostalCode(input: string): string | null

Normaliza "1234567" / "1234 567" em "1234-567"; devolve null se não tiver 7 dígitos.

ATCUD

buildAtcud(parts: AtcudParts): string

Constrói "<validationCode>-<sequence>". Lança exceção se o código de validação não for alfanumérico maiúsculo ou a sequência não for um inteiro positivo.

interface AtcudParts {
  validationCode: string; // código de validação da série (emitido pela AT)
  sequence: number;       // >= 1
}

validateAtcud(input: string): boolean

Valida uma string ATCUD, incluindo o fallback "0" pré-registo.

Código QR da fatura

buildInvoiceQRCode(data: InvoiceQRData): string

Compõe a string de campos do QR da AT (A:...*B:...*...). Renderiza a string devolvida com qualquer biblioteca de QR. Ver Faturação para a referência completa dos campos.