La risposta in breve

Generare una QR-fattura dal proprio software significa produrre una stringa di dati conforme alle Implementation Guidelines, codificarla in un codice QR di livello M con la croce svizzera, quindi comporre la sezione pagamento e la ricevuta secondo lo Style Guide. Alcune librerie open source coprono l'intero processo in Java e .NET (SwissQRBill), PHP (php-swiss-qr-bill), Python (swiss-qr-bill), JavaScript (swissqrbill), LaTeX e Typst. SIX non certifica le librerie: la conformità si verifica sul portale di validazione, e il team resta responsabile del monitoraggio delle versioni dello standard.

Cosa occorre produrre

Generare una QR-fattura significa concatenare tre elaborazioni distinte.

Tappa Contenuto Riferimento normativo
1. Dati Costruire la stringa di circa 30 righe: intestazione SPC / 0200 / 1, creditore, importo, debitore, riferimento, informazioni, EPD, S1, procedure alternative Implementation Guidelines, capitolo 4
2. Codice Codificare la stringa in un codice QR ISO 18004, livello M, UTF-8, versione più piccola, poi aggiungere la croce svizzera; esportare in formato vettoriale Implementation Guidelines, capitolo 6
3. Impaginazione Comporre ricevuta e sezione pagamento: zone, caratteri, dimensioni, diciture nella lingua scelta, campi vuoti con angoli, forbici o perforazione Style Guide

La guida sullo Swiss QR Code descrive in dettaglio la struttura dei dati e fornisce un payload completo.

Le librerie open source

Tutte le librerie elencate qui sotto producono la sezione pagamento completa (spesso in SVG o PDF) e non solo il codice. Prima di scegliere, verificate la data dell’ultima versione e il supporto dei soli indirizzi strutturati (versione 2.3).

Linguaggio Libreria Punti di forza
Java SwissQRBill (manuelbl) Generazione e decodifica, validazione completa, output SVG, PDF e PNG, sviluppata congiuntamente alla versione .NET
.NET SwissQRBill.NET (manuelbl) Stessa API della versione Java, integrazione negli ERP Windows
PHP php-swiss-qr-bill (sprain) Molto diffusa nei negozi online e nei software web svizzeri, output HTML, SVG e PDF (FPDF, TCPDF)
Python swiss-qr-bill (claudep) Riga di comando e classe QRBill, output SVG, integrazione Django
JavaScript / TypeScript swissqrbill (schoero) Node.js e browser, output SVG e PDF (PDFKit), utile per portali e applicazioni web
LaTeX qrbill (CTAN) Per le fatture composte in LaTeX
Typst payqr-swiss Per i documenti Typst

Questi progetti sono mantenuti dalla comunità, per lo più sotto licenza MIT. Nessuno è certificato da SIX, che non certifica nessuno: a essere validato è il vostro output, non la libreria.

Punti di attenzione nell’implementazione

Dati

  • Indirizzi: sono ammessi solo gli indirizzi strutturati (tipo S); via e numero sono due elementi, il codice postale è senza paese, il paese è un codice ISO 3166-1. Un debitore è o completo o assente (gruppo vuoto).
  • Coppia conto-riferimento: rifiutate in fase di generazione QRR senza QR-IBAN (IID 30000–31999) e SCOR o NON con un QR-IBAN. Dalla versione 2.4, rifiutate anche QRR in EUR.
  • Riferimenti: 27 cifre per il riferimento QR, controllo modulo 10 ricorsivo calcolato e non digitato; da 5 a 25 caratteri per la Creditor Reference, controllo mod 97-10; codifica senza spazi.
  • Importo: stringa decimale con il punto, due decimali, senza separatore delle migliaia né zeri iniziali; tra 0.01 e 999999999.99.
  • 140 caratteri condivisi tra Ustrd e StrdBkgInf: troncate il testo libero, mai S1.
  • Set di caratteri: filtrate o sostituite i caratteri fuori dal set latino ammesso prima della codifica; emoji e virgolette tipografiche esotiche sono frequenti nei nomi inseriti dai clienti.
  • Creditore finale: sette righe vuote; non compilate mai questo gruppo.

Codice

  • Livello di correzione M forzato, qualunque sia il valore predefinito della libreria QR.
  • Versione più piccola possibile, poi scalatura a 46 × 46 mm in formato vettoriale; mai bitmap.
  • Croce svizzera conforme al modello di SIX, centrata; le librerie specializzate la aggiungono.
  • Margine bianco di 5 mm attorno al codice nella sezione pagamento.

Impaginazione

  • Caratteri Arial, Frutiger, Helvetica o Liberation Sans incorporati nel PDF (Liberation Sans è libero e metricamente compatibile con Arial).
  • Diciture tratte dall’Allegato D delle Implementation Guidelines, nelle cinque lingue, mai tradotte liberamente.
  • Titoli nascosti quando il valore è assente; angoli neri per importo o debitore lasciati vuoti.
  • Linea e forbici in PDF; posizioni allineate alla perforazione per la carta.

Testare

  1. Test unitari sulle cifre di controllo (riferimento QR, Creditor Reference, IBAN) con valori noti: 210000000003139471430009017 è valido, RF18539007547034 è valido, CH4431999123000889012 è un QR-IBAN.
  2. Test di non regressione: confrontare il testo decodificato del codice con un riferimento per ogni caso di fattura (importo libero, debitore assente, EUR, S1, procedura alternativa).
  3. Validate i dati dello Swiss QR Code con gli strumenti SIX nei formati accettati. Controllate separatamente PDF definitivo e foglio stampato con lo Style Guide, poi testate il trattamento bancario e la riconciliazione.
  4. Validatore Swico per la sintassi S1.
  5. Scansione reale in due app bancarie, su schermo e su carta.

Seguire lo standard

SIX pubblica le modifiche delle Implementation Guidelines e il calendario di introduzione. Iscrivetevi agli annunci del centro download, leggete la documentazione delle modifiche e pianificate l’aggiornamento della libreria e dei vostri test. La guida alle versioni riassume le scadenze in corso: versione 2.4 il 14 novembre 2026, fine del mantenimento della 2.3 a novembre 2027.

Fonti e riferimenti