Faturação: ATCUD e o código QR da AT

Desde 2022, as faturas portuguesas têm de incluir um ATCUD e um código QR definidos pela Autoridade Tributária (AT). O pt-fiscal ajuda-te a compor ambos; não gera a assinatura/hash digital (campo Q) — isso vem do teu software de faturação certificado.

ATCUD

O ATCUD é o código único do documento:

<CodigoValidacaoSerie>-<NumeroSequencial>

• Código de validação — emitido pela AT quando registas uma série de documentos.
• Número sequencial — a posição do documento dentro dessa série.
• Documentos emitidos antes de a série ser comunicada usam o literal "0".

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

buildAtcud({ validationCode: 'CSDF7T5H', sequence: 1 }); // "CSDF7T5H-1"
validateAtcud('CSDF7T5H-1'); // true
validateAtcud('0');          // true (pré-registo)

Código QR

O buildInvoiceQRCode() devolve a string de campos que a AT espera. Depois renderizas como imagem QR com uma biblioteca como a qrcode.

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

const payload = buildInvoiceQRCode({
  issuerNif: '500000000',
  buyerNif: '999999990',      // 999999990 = consumidor final
  buyerCountry: 'PT',
  docType: 'FS',              // FT, FS, FR, NC, ND, ...
  docState: 'N',
  docDate: new Date(),
  docId: 'FS A/1',
  atcud: 'CSDF7T5H-1',
  vat: { PT: { standard: [10, 2.3] } }, // [base, imposto]
  totalTaxes: 2.3,
  totalWithTax: 12.3,
  hash4: 'kIrx',             // 4 chars do hash da assinatura (do teu software)
  certificateNumber: 9999,   // nº do certificado do programa (AT)
});

await QRCode.toFile('fatura-qr.png', payload);

Campos

Campo	Significado
A	NIF do emitente
B	NIF do adquirente (999999990 para consumidor final)
C	País do adquirente (ISO 3166-1 alpha-2)
D	Tipo de documento (FT, FS, FR, NC, ND, …)
E	Estado do documento (N, A, F, R)
F	Data do documento (AAAAMMDD)
G	Identificação única do documento
H	ATCUD
I1–I8	Espaço fiscal continente (PT): base tributável e IVA por taxa
J1–J8 / K1–K8	Equivalentes para Açores (PT-AC) / Madeira (PT-MA)
L	Valor não sujeito a IVA
M	Imposto do selo
N	Total de impostos
O	Total com impostos
P	Retenções na fonte
Q	4 chars do hash da assinatura
R	Nº do certificado do programa (AT)
S	Outras informações

O objeto vat aceita exemptBase, reduced, intermediate e standard (cada taxa como [base, imposto]) por região, e o builder emite os campos pela ordem que a especificação da AT exige.

Nota legal: as faturas oficiais têm de ser emitidas via Portal das Finanças ou software certificado pela AT. Este helper serve para construir o payload do QR, não para substituir a faturação certificada.