Invoicing: ATCUD & the AT QR code

Since 2022, Portuguese invoices must carry an ATCUD and a QR code defined by the Autoridade Tributária (AT). pt-fiscal helps you compose both; it does not generate the digital signature/hash (field Q) — that comes from your certified invoicing software.

ATCUD

The ATCUD is the document's unique code:

<CodigoValidacaoSerie>-<NumeroSequencial>

• Validation code — issued by the AT when you register a document series.
• Sequential number — the document's position within that series.
• Documents issued before a series is communicated use the literal "0".

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

buildAtcud({ validationCode: 'CSDF7T5H', sequence: 1 }); // "CSDF7T5H-1"
validateAtcud('CSDF7T5H-1'); // true
validateAtcud('0');          // true (pre-registration)

QR code

buildInvoiceQRCode() returns the field string the AT expects. You then render it as an actual QR image with a library such as 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, tax]
  totalTaxes: 2.3,
  totalWithTax: 12.3,
  hash4: 'kIrx',             // 4 chars of the signature hash (from your software)
  certificateNumber: 9999,   // AT program certificate number
});

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

Fields

Field	Meaning
A	Issuer NIF
B	Buyer NIF (999999990 for final consumer)
C	Buyer country (ISO 3166-1 alpha-2)
D	Document type (FT, FS, FR, NC, ND, …)
E	Document state (N, A, F, R)
F	Document date (YYYYMMDD)
G	Unique document id
H	ATCUD
I1–I8	Mainland (PT) fiscal region: tax base and VAT per rate
J1–J8 / K1–K8	Azores (PT-AC) / Madeira (PT-MA) equivalents
L	Non-taxable amount
M	Stamp duty
N	Total taxes
O	Total with taxes
P	Withholding
Q	4 chars of the signature hash
R	AT program certificate number
S	Other info

The vat object accepts exemptBase, reduced, intermediate and standard (each rate as [base, tax]) per region, and the builder emits the fields in the order the AT specification requires.

Legal note: official invoices must be issued via the Portal das Finanças or AT-certified software. This helper is for building the QR payload, not for replacing certified invoicing.