Magic Heidi API QR-fatture svizzere: prepara l'integrazione
Chiarisci contratto e accesso di prova prima di implementare richieste e risposte. Validazione QR e controllo della fattura fanno parte del collaudo.
Sviluppi funzioni di fatturazione per il mercato svizzero? Distingui la generazione del PDF, la sezione di pagamento Swiss QR e la riconciliazione degli incassi. Questa pagina ti aiuta a definire requisiti e collaudo di una possibile integrazione.
Il tempo necessario si può stimare solo dopo aver verificato contratto, modello dei dati e casi di prova.
Chiarire disponibilità e accesso
Stato: 1° novembre 2026. Questa pagina è un orientamento tecnico, non una specifica approvata di un'API pubblica. Prima di integrare servono il contratto attualmente supportato, le condizioni di accesso e un ambiente di prova espressamente autorizzato. Contatta Magic Heidi descrivendo il caso d'uso e il volume previsto.
Le versioni precedenti di questa pagina e dell'articolo del blog contenevano esempi incompatibili di richiesta e risposta. Non sono una base affidabile per il codice di produzione. Per questo non vengono riproposti come integrazione da copiare: vanno confermati nomi dei campi, formato delle date, rappresentazione dell'IVA e struttura della risposta.
Non promettiamo un endpoint pubblico gratuito di prova, un metodo specifico di autenticazione, limiti di chiamata, prezzi, SLA o scadenze dei link PDF. Senza un ambiente concordato, non inviare a un endpoint dati reali di clienti, pazienti o conti bancari.
Cosa deve definire il contratto API approvato
| Ambito | Da chiarire prima dello sviluppo |
|---|---|
| Richiesta | Campi obbligatori, tipi di dati, formato data, valuta e numero fattura |
| IVA | Valori decimali o percentuali, arrotondamenti, importi lordi/netti e aliquote multiple |
| Indirizzi | Componenti separate, paese e regole di validazione |
| Conto e riferimento | Tipi di IBAN supportati, QRR/SCOR/NON, cifre di controllo e comunicazione facoltativa |
| Risposta | Percorso JSON effettivo del PDF, stati, errori e autorizzazione al download |
| Esercizio | Autenticazione, limiti, timeout, nuovi tentativi e protezione dalla generazione doppia |
| Dati | Luogo di conservazione, accessi, cancellazione, validità dei link e archivio proprio |
Collaudo tecnico
- Usa solo chiamate di prova concordate, non fatturabili, con dati sintetici.
- Confronta successi ed errori di validazione con la risposta effettiva. Non inventare nomi dei campi o codici di errore.
- Scarica il PDF e controlla totali, arrotondamenti, lingua e dati IVA.
- Decodifica i dati QR e verifica conto, riferimento, valuta e indirizzi secondo le specifiche SIX attuali.
- Prova IBAN non validi, combinazioni conto/riferimento non ammesse, indirizzi mancanti e valute non supportate. Una risposta HTTP positiva non dimostra che la fattura sia corretta.
- Prima di implementare nuovi tentativi, concorda come evitare PDF o numeri fattura duplicati. Non registrare nei log i dati personali completi della fattura.
Casi d'uso possibili
Un servizio di generazione approvato può inserirsi in un processo di fatturazione, nella gestione di soci o negli ordini di un negozio online. Un PDF con codice QR, però, non incassa denaro e non prova un pagamento. La riconciliazione automatica richiede anche dati bancari adatti e un processo di abbinamento collaudato.
Capire QR-IBAN e IBAN ordinario
La combinazione tra conto e riferimento determina il tipo di sezione di pagamento utilizzabile.
Quando usare un QR-IBAN
Usalo se il processo di pagamento concordato prevede QRR. Il riferimento QR di 27 cifre facilita un abbinamento univoco. La riconciliazione effettiva richiede dati bancari e software adatti: il PDF non contrassegna da solo una fattura come pagata.
Come riconoscerlo: Le posizioni dalla 5ª alla 9ª (IID) sono comprese tra 30000 e 31999. Verifica il QR-IBAN emesso dall'istituto; non usare un IBAN inventato per le prove.
Come ottenerlo: Chiedi alla banca. Condizioni e attivazione dipendono dall'istituto.
Quando usare un IBAN ordinario
Un IBAN ordinario CH/LI può essere usato con un riferimento creditore SCOR conforme a ISO 11649 oppure senza riferimento strutturato (NON). Anche SCOR può supportare la riconciliazione; il processo effettivo dipende da banca e software. L'IID dell'IBAN ordinario è fuori dall'intervallo QR-IID.
Compatibilità dei riferimenti
- QR-IBAN → QRR: riferimento QR di 27 cifre.
- IBAN ordinario CH/LI → SCOR o NON: riferimento creditore oppure nessun riferimento strutturato.
Da verificare nel collaudo: QRR con un IBAN ordinario non è una combinazione ammessa. Il contratto approvato deve specificare come il servizio segnala questo errore. Non presumere che calcoli automaticamente una cifra di controllo a partire da un riferimento incompleto.
Sezione di pagamento svizzera e fatture internazionali
La sezione Swiss QR usa conti CH/LI e valute CHF o EUR. Questo non significa che solo clienti di questi paesi possano ricevere fatture. Altre valute o conti non compatibili richiedono un blocco di pagamento diverso nel documento.
La QR-fattura ha sostituito le precedenti polizze di versamento dal 1° ottobre 2022, ma non è obbligatoria su ogni fattura. Mantieni gli indirizzi strutturati e verifica le direttive SIX e le disposizioni transitorie applicabili. Un servizio non può trasformare automaticamente dati errati in una fattura legalmente corretta.
Prossimo passo
Richiedi il contratto supportato e un accesso di prova approvato a hello@magicheidi.ch. Chiarisci prima accesso, protezione dei dati e fatturazione del servizio. Solo dopo sviluppa il client nel tuo linguaggio e collaudalo con prove riproducibili.