Começar

Requisitos

• Node.js 20 ou superior

Instalação

npm install pt-fiscal

O pt-fiscal é distribuído como ESM com tipos TypeScript e sem dependências em runtime.

Importa só o que precisas

import { validateNif, validatePortugueseIban, formatPostalCode } from 'pt-fiscal';

validateNif('123456789');                              // true
validatePortugueseIban('PT50000201231234567890154');  // true
formatPostalCode('1000001');                           // "1000-001"

Tarefas comuns

Validar um cliente no onboarding

import { validateNif, entityTypeLabel, validatePortugueseIban } from 'pt-fiscal';

function verificarCliente(nif: string, iban: string) {
  return {
    nifValido: validateNif(nif),
    tipo: entityTypeLabel(nif),          // "Pessoa singular" / "Pessoa coletiva (empresa)"
    ibanValido: validatePortugueseIban(iban),
  };
}

Construir o payload do QR de uma fatura

Ver o guia dedicado: Faturação: ATCUD e o código QR da AT.

Notas de âmbito

• Esta biblioteca verifica estrutura e dígitos de controlo. Não contacta a AT, um banco ou os CTT. Um NIF pode ser estruturalmente válido mas não estar atribuído; um IBAN pode ser válido mas estar encerrado.
• Tudo é puro e determinístico — seguro para correr no cliente ou no servidor.

Desenvolvimento

git clone https://github.com/marcelogdomingues/pt-fiscal
cd pt-fiscal
npm install
npm test
npm run build