validadores-pt

Generation and validation of Portuguese NIF, NISS, Citizen Card and IBAN. TypeScript, zero dependencies, test coverage with official cases.

The generated numbers are mathematically valid (they pass the check digits), but fictitious — they don't belong to anyone real. Meant for software testing and development, never for real documents.

Extracted from the library used at geranif.pt, where each algorithm is documented step by step with a hand-worked example:

• NIF algorithm
• NISS algorithm
• Citizen Card algorithm
• Portuguese IBAN algorithm

Installation

npm install validadores-pt

Usage

import { validateNIF, generateNIF, validateIBAN, generateIBAN } from 'validadores-pt';

validateNIF('123456789'); // true
generateNIF('individual'); // "217345670" (varies on each call)

validateIBAN('PT50000201231234567890154'); // true
generateIBAN();                            // "PT50..." from a random bank

Every validation function has a *Detailed variant that returns the exact reason for failure (useful for form error messages):

import { validateNIFDetailed } from 'validadores-pt';

validateNIFDetailed('123456780');
// { valid: false, error: 'checkDigit', expectedDigit: 9, type: 'individual' }

NIF

import { validateNIF, validateNIFDetailed, generateNIF, typeOfNIF } from 'validadores-pt';

validateNIF('123456789');          // true
typeOfNIF('123456789');            // "individual"
generateNIF('corporate');          // corporate NIF (prefix 5)
generateNIF();                     // random type

Types accepted by generateNIF: 'individual' | 'corporate' | 'nonResident' | 'public' | 'other' | 'any'.

NISS

import { validateNISS, generateNISS } from 'validadores-pt';

validateNISS('12345678902'); // true
generateNISS('individual');  // individual NISS (prefix 1)

Citizen Card

import { validateCC, generateCC } from 'validadores-pt';

validateCC('000000000ZZ4'); // true
generateCC();                // full document number (NIC + version + final check digit)

IBAN / NIB

import { validateIBAN, generateIBAN, generateNIB, validateNIB, validateNIBDetailed, PT_BANKS } from 'validadores-pt';

validateIBAN('PT50000201231234567890154'); // true
generateIBAN();                            // random bank among those in PT_BANKS
generateIBAN('0035');                      // Caixa Geral de Depósitos IBAN

validateNIBDetailed('000201231234567890154');
// { valid: true }

Display formatting

import { formatNIF, formatCC, formatIBAN } from 'validadores-pt';

formatNIF('123456789');                   // "123 456 789"
formatIBAN('PT50000201231234567890154');  // "PT50 0002 0123 1234 5678 9015 4"

Algorithms

| Document | Check digit rule | |---|---| | NIF | Modulo 11, weights 9 to 2 over the first 8 digits | | NISS | Prime weights [29,23,19,17,13,11,7,5,3,2], check digit = 9 − (sum mod 10) | | Citizen Card | Modulo 11 (NIC, former ID card rule) + base-36 Luhn (final check digit) | | IBAN / NIB | 98 − (mod 97) for the NIB · ISO 13616 (mod 97 = 1) for the full IBAN |

Full explanation of each, with a digit-by-digit worked example, at geranif.pt.

Try the generators and validators online

No installation needed: geranif.pt generates up to 100 numbers of each type at once, ready to export.

License

MIT