Getting started

Requirements

• Node.js 20 or newer

Install

npm install pt-fiscal

pt-fiscal ships as ESM with TypeScript types and no runtime dependencies.

Import what you need

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

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

Common tasks

Validate a customer at onboarding

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

function checkCustomer(nif: string, iban: string) {
  return {
    nifValid: validateNif(nif),
    kind: entityTypeLabel(nif),          // "Pessoa singular" / "Pessoa coletiva (empresa)"
    ibanValid: validatePortugueseIban(iban),
  };
}

Build an invoice QR payload

See the dedicated guide: Invoicing: ATCUD & the AT QR code.

Notes on scope

• This library checks structure and check digits. It does not call the AT, a bank or CTT. A NIF can be structurally valid but not assigned; an IBAN can be valid but closed.
• Everything is pure and deterministic — safe to run client- or server-side.

Development

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