Receitas

Soluções copy-paste para tarefas comuns.

Validar um cliente no onboarding

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

function validarCliente(input: { nif: string; iban: string; postal: string }) {
  const erros: string[] = [];
  if (!validateNif(input.nif)) erros.push('NIF inválido');
  if (!validatePortugueseIban(input.iban)) erros.push('IBAN inválido');
  const postal = formatPostalCode(input.postal);
  if (!postal) erros.push('Código postal inválido');
  return { ok: erros.length === 0, erros, tipo: entityTypeLabel(input.nif), postal };
}

Validar em lote um CSV de NIFs

import { readFileSync } from 'node:fs';
import { validateNif } from 'pt-fiscal';

const linhas = readFileSync('clientes.csv', 'utf8').trim().split('\n');
const invalidos = linhas.filter((nif) => !validateNif(nif));
console.log(`${invalidos.length} inválidos de ${linhas.length}`);

Gerar a imagem do código QR da fatura

import { buildInvoiceQRCode } from 'pt-fiscal';
import QRCode from 'qrcode'; // npm i qrcode

const payload = buildInvoiceQRCode({
  issuerNif: '500000000',
  buyerNif: '999999990',
  buyerCountry: 'PT',
  docType: 'FS',
  docState: 'N',
  docDate: new Date(),
  docId: 'FS A/1',
  atcud: 'CSDF7T5H-1',
  vat: { PT: { standard: [10, 2.3] } },
  totalTaxes: 2.3,
  totalWithTax: 12.3,
  hash4: 'kIrx',            // da assinatura do teu software de faturação certificado
  certificateNumber: 9999,
});

await QRCode.toFile('fatura-qr.png', payload, { errorCorrectionLevel: 'M' });

Construir e validar um ATCUD

import { buildAtcud, validateAtcud } from 'pt-fiscal';

const atcud = buildAtcud({ validationCode: 'CSDF7T5H', sequence: 42 }); // "CSDF7T5H-42"
validateAtcud(atcud); // true

Usar num formulário (React)

import { validateNif } from 'pt-fiscal';

<input
  onBlur={(e) => setNifError(validateNif(e.target.value) ? '' : 'NIF inválido')}
/>