API Fattura QR Svizzera: Genera Fatture Conformi in Secondi
API RESTful per la generazione di fatture QR svizzere. Conforme ISO 20022, supporto multilingue, compatibile QR-IBAN. Una chiamata API, PDF completamente conforme.

Stai sviluppando funzionalità di fatturazione per il mercato svizzero? Smetti di lottare con le specifiche QR-Rechnung e gli standard ISO 20022. La nostra API genera fatture QR svizzere conformi con una singola chiamata—nessuna libreria complessa, nessun grattacapo sulla conformità.
Che tu stia costruendo una piattaforma SaaS, integrando la fatturazione nel tuo ERP o creando uno strumento per liberi professionisti, avrai fatture QR completamente conformi operative in meno di 30 minuti.
Perché Usare un'API Invece di Sviluppare Internamente?
La generazione di fatture QR svizzere sembra semplice finché non entri nei dettagli. Ecco cosa ti aspetta se decidi di costruirla da zero:
Complessità della Conformità
Linee guida di implementazione v2.3 di 67 pagine. Standard ISO 20022, validazione QR-IBAN, cifre di controllo, indirizzi strutturati.Manutenzione Continua
Gli standard bancari svizzeri evolvono. Solo l'aggiornamento 2025 ha introdotto indirizzi strutturati, set di caratteri ampliati, nuove regole di validazione.Onere dei Test
Ogni combinazione di tipo IBAN, formato riferimento, valuta e lingua richiede test. Più casi limite, aliquote IVA, formattazione PDF.Time to Market
Sviluppare da zero: 2-3 mesi. Usando la nostra API: fatture generate in poche ore.Progettata per Sviluppatori Professionisti
Tutto il necessario per generare fatture QR svizzere conformi, mantenute e aggiornate automaticamente.
Supporto QR-IBAN e IBAN Standard
Entrambi i metodi di pagamento funzionano perfettamente. QR-IBAN (IID 30000-31999) per riconciliazione automatica con riferimenti a 27 cifre. IBAN standard con Creditor Reference o senza riferimento per fatturazione semplice.
- Validazione automatica formato IBAN
- Calcolo cifra di controllo incluso
- Validazione numero di riferimento per tipo IBAN
- Nessuna validazione manuale richiesta
Indirizzi Strutturati Pronti per il 2025
Aggiornamento critico: Dal 21 novembre 2025, le fatture QR richiedono indirizzi strutturati. La nostra API supporta già il nuovo formato.
- Formato indirizzo strutturato (tipo S)
- Nome via e numero civico separati
- Validazione CAP e città
- Supporto codice paese
Generazione Fatture Multilingue
Genera fatture in tutte le lingue ufficiali svizzere più inglese. La lingua influenza etichette, formattazione e visualizzazione date.
- Tedesco (Deutsch) – QR-Rechnung
- Francese (Français) – Facture QR
- Italiano – Fattura QR
- Inglese – QR Invoice
Gestione Intelligente Numeri di Riferimento
Tutti i formati di riferimento supportati con validazione automatica e calcolo cifra di controllo.
- QR Reference (27 cifre) con cifra di controllo automatica
- Creditor Reference (ISO 11649, 5-25 caratteri)
- Opzione senza riferimento per fatturazione semplice
- Validazione formato in base al tipo IBAN
Gestione IVA Integrata
IVA svizzera con aliquote standard o personalizzate. Calcolo automatico e formattazione secondo standard svizzeri.
- Aliquote standard (8.1%, 2.6%, 3.8%)
- Aliquote IVA personalizzate supportate
- Aliquote IVA multiple per fattura
- Calcolo automatico lordo e netto
Opzioni di Personalizzazione Brand
Fatture professionali con la vostra identità aziendale e integrazione gestione documenti.
- Integrazione logo (PNG, max 2MB)
- Nomi file PDF personalizzati
- Controllo numerazione fatture
- Assegnazione ID interno
Testa l'API Subito
Nessuna autenticazione richiesta per i test. Copia questo comando ed eseguilo nel tuo terminale:
curl --location --request POST \
'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": {
"user_details": {
"name": "Your Company GmbH",
"address": "Bahnhofstrasse 1",
"zip": "8001",
"city": "Zürich",
"iban": "CH0700700112900411647"
},
"customer_details": {
"name": "Customer AG",
"address": "Rue du Rhône 1",
"zip": "1204",
"city": "Genève"
},
"invoice_items": [
{
"description": "Software Development",
"quantity": 8.5,
"unit_price": 150.00
}
]
}
}'
Riceverai una fattura PDF completa con codice QR scansionabile. Nessuna chiave API necessaria per i test.
Parametri della Richiesta Spiegati
Struttura JSON semplice con campi obbligatori e opzionali.
Campi Obbligatori
{
"user_details": {
"name": "Nome creditore (max 70 caratteri)",
"address": "Via e numero",
"zip": "CAP",
"city": "Città",
"iban": "CH76 0070 0112 3456 7890 1"
},
"customer_details": {
"name": "Nome debitore (max 70 caratteri)",
"address": "Via e numero",
"zip": "CAP",
"city": "Città"
},
"invoice_items": [
{
"description": "Servizio o prodotto",
"quantity": 1.0,
"unit_price": 100.00
}
]
}
Parametri Opzionali
{
"invoice_number": "INV-2024-001",
"invoice_date": "2024-01-15",
"reference": "210000000003139471430009017",
"language": "de",
"currency": "CHF",
"vat_rate": 8.1,
"filename": "invoice_customer_2024_001",
"logo_url": "https://yoursite.com/logo.png"
}
Gestione Risposte
Successo (HTTP 200):
{
"result": {
"pdf_url": "https://storage.googleapis.com/...",
"invoice_id": "abc123",
"total_amount": 1275.00
}
}
Errore (HTTP 400):
{
"error": {
"code": "INVALID_IBAN",
"message": "IBAN check digit validation failed"
}
}
L'URL del PDF rimane accessibile per 30 giorni. Scaricalo e archivialo nel tuo sistema immediatamente.
Implementazione nel Tuo Linguaggio
Esempi copia-incolla per JavaScript, Python, PHP, Ruby, Go e Java.
JavaScript / Node.js
const axios = require('axios');
async function generateInvoice() {
const response = await axios.post(
'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d',
{
data: {
user_details: {
name: "Tech Solutions AG",
address: "Technoparkstrasse 1",
zip: "8005",
city: "Zürich",
iban: "CH0700700112900411647"
},
customer_details: {
name: "Client Corp",
address: "Avenue de la Gare 10",
zip: "1003",
city: "Lausanne"
},
invoice_items: [
{
description: "API Integration Service",
quantity: 5,
unit_price: 200.00
}
]
}
}
);
return response.data.result.pdf_url;
}
Python
import requests
import json
def generate_qr_invoice():
url = "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d"
payload = {
"data": {
"user_details": {
"name": "Your Company GmbH",
"address": "Bahnhofstrasse 1",
"zip": "8001",
"city": "Zürich",
"iban": "CH0700700112900411647"
},
"customer_details": {
"name": "Customer Name",
"address": "Street Address",
"zip": "1000",
"city": "Lausanne"
},
"invoice_items": [
{
"description": "Consulting Services",
"quantity": 10,
"unit_price": 180.00
}
]
}
}
response = requests.post(url, json=payload)
return response.json()['result']['pdf_url']
PHP
<?php
$curl = curl_init();
$data = [
'data' => [
'user_details' => [
'name' => 'Swiss Services SA',
'address' => 'Route de Berne 5',
'zip' => '1010',
'city' => 'Lausanne',
'iban' => 'CH0700700112900411647'
],
'customer_details' => [
'name' => 'Client Company',
'address' => 'Via Nassa 1',
'zip' => '6900',
'city' => 'Lugano'
],
'invoice_items' => [
[
'description' => 'Web Development',
'quantity' => 20,
'unit_price' => 125.00
]
]
]
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_HTTPHEADER => ['Content-Type: application/json']
]);
$response = curl_exec($curl);
$result = json_decode($response, true);
echo $result['result']['pdf_url'];
?>
Ruby
require 'net/http'
require 'json'
require 'uri'
uri = URI('https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d')
payload = {
data: {
user_details: {
name: "Development Studio GmbH",
address: "Seestrasse 20",
zip: "8002",
city: "Zürich",
iban: "CH0700700112900411647"
},
customer_details: {
name: "Client Business AG",
address: "Spalenring 5",
zip: "4055",
city: "Basel"
},
invoice_items: [
{
description: "Design Services",
quantity: 15,
unit_price: 160.00
}
]
}
}
response = Net::HTTP.post(uri, payload.to_json,
'Content-Type' => 'application/json')
result = JSON.parse(response.body)
puts result['result']['pdf_url']
Go
package main
import (
"bytes"
"encoding/json"
"net/http"
)
type InvoiceRequest struct {
Data struct {
UserDetails struct {
Name string `json:"name"`
Address string `json:"address"`
Zip string `json:"zip"`
City string `json:"city"`
IBAN string `json:"iban"`
} `json:"user_details"`
CustomerDetails struct {
Name string `json:"name"`
Address string `json:"address"`
Zip string `json:"zip"`
City string `json:"city"`
} `json:"customer_details"`
InvoiceItems []struct {
Description string `json:"description"`
Quantity float64 `json:"quantity"`
UnitPrice float64 `json:"unit_price"`
} `json:"invoice_items"`
} `json:"data"`
}
func generateInvoice() (string, error) {
url := "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d"
var req InvoiceRequest
req.Data.UserDetails.Name = "Swiss Tech AG"
req.Data.UserDetails.Address = "Technoparkstrasse 1"
req.Data.UserDetails.Zip = "8005"
req.Data.UserDetails.City = "Zürich"
req.Data.UserDetails.IBAN = "CH0700700112900411647"
jsonData, _ := json.Marshal(req)
resp, err := http.Post(url, "application/json", bytes.NewBuffer(jsonData))
// Handle response...
return "pdf_url", err
}
Java
import java.net.http.*;
import java.net.URI;
import org.json.JSONObject;
public class QRInvoiceGenerator {
public static String generateInvoice() throws Exception {
String url = "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d";
JSONObject payload = new JSONObject()
.put("data", new JSONObject()
.put("user_details", new JSONObject()
.put("name", "Software GmbH")
.put("address", "Europaallee 1")
.put("zip", "8004")
.put("city", "Zürich")
.put("iban", "CH0700700112900411647"))
.put("customer_details", new JSONObject()
.put("name", "Client AG")
.put("address", "Bahnhofstrasse 10")
.put("zip", "3011")
.put("city", "Bern"))
.put("invoice_items", new JSONArray()
.put(new JSONObject()
.put("description", "Development")
.put("quantity", 40)
.put("unit_price", 150.00))));
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(payload.toString()))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
JSONObject result = new JSONObject(response.body());
return result.getJSONObject("result").getString("pdf_url");
}
}
Casi d'Uso Comuni e Pattern di Integrazione
Scenari reali in cui la nostra API risolve le sfide della fatturazione svizzera per sviluppatori e aziende.
Aggiungi supporto per il mercato svizzero. I codici QR rendono i pagamenti dei clienti semplici tramite scansione dall'app bancaria.
Collega i sistemi esistenti alla generazione automatica di fatture. Creazione fatture attivata da webhook con dati CRM.
Supporto multilingue, gestione IVA corretta, PDF professionali. Conformità svizzera gestita automaticamente.
Offri il metodo di pagamento "Fattura" per B2B. Genera fatture QR immediatamente dopo la conferma dell'ordine.
Automatizza la riscossione delle quote associative. Riferimenti QR univoci per abbinamento automatico dei pagamenti.
Genera fatture ovunque ti trovi. Integrazione API leggera per app iOS e Android.
Comprendere QR-IBAN vs IBAN Standard
Questo punto confonde inizialmente la maggior parte degli sviluppatori. Ecco la differenza pratica:
Quando Usare QR-IBAN
Usa QR-IBAN quando: Hai bisogno di riconciliazione automatica dei pagamenti. Il riferimento QR a 27 cifre collega i pagamenti in entrata a fatture specifiche automaticamente. La tua banca abbina il riferimento e ti notifica quale fattura è stata pagata.
Come riconoscere QR-IBAN: I caratteri dal 5° al 9° (IID) vanno da 30000 a 31999.
- Esempio: CH12 30123 4567 8901 2345 6 (30123 = QR-IID)
Come ottenere QR-IBAN: Contatta la tua banca svizzera. Emetteranno QR-IBAN insieme ai tuoi IBAN standard. La maggior parte delle banche svizzere offre questo servizio gratuitamente per i conti aziendali.
Quando Usare IBAN Standard
Usa IBAN standard quando: La fatturazione semplice è sufficiente. Abbini manualmente i pagamenti in entrata alle fatture, oppure usi il campo Creditor Reference (formato ISO 11649) per abbinamento semi-automatico.
Riconoscimento IBAN standard: Formato IBAN svizzero standard con IID fuori dall'intervallo 30000-31999.
Compatibilità Riferimenti
- QR-IBAN → Deve usare QR Reference (27 cifre)
- IBAN standard → Può usare Creditor Reference o nessun riferimento
L'API valida questo automaticamente. Passi un QR Reference con un IBAN standard? Riceverai un errore prima di generare una fattura non valida.
Implementazione Pronta per la Produzione
Pattern professionali per gestione errori, test, performance e monitoraggio.
Gestione Errori
Avvolgi sempre le chiamate API in blocchi try-catch. Registra gli errori con contesto includendo numero fattura e ID cliente.
- INVALID_IBAN – Formato o cifra di controllo errati
- REFERENCE_MISMATCH – QR Reference con IBAN standard
- INVALID_AMOUNT – Totale negativo o zero
- MISSING_FIELD – Parametro obbligatorio mancante
Strategia di Test
Approccio di test in tre fasi per integrazione e deployment affidabili.
- Sviluppo: Endpoint di test gratuito con dati fittizi
- Staging: Formati IBAN reali con clienti dummy
- Produzione: Lancio soft con test interni prima
- Verifica i codici QR in più app bancarie
Ottimizzazione Performance
Strategie per mantenere tempi di risposta rapidi e gestire volumi elevati efficacemente.
- Elaborazione asincrona: Accoda i job, non bloccare le richieste
- Caching: Memorizza gli URL PDF (validi 30 giorni)
- Generazione batch: Richieste parallele con rate limit
- Contattaci per rate limit enterprise
Monitoraggio
Traccia metriche chiave e configura alert per l'affidabilità in produzione.
- Tasso di successo: Dovrebbe essere >99.5%
- Tempo di risposta: Media <2 secondi
- Tipi di errore: Traccia pattern e picchi
- Download fatture: Monitora accessi PDF
Domande Frequenti
Perché il mio IBAN non funziona?
Prima, verifica che sia un IBAN svizzero o del Liechtenstein (inizia con CH o LI). Le fatture QR supportano solo questi paesi. Secondo, controlla se stai mescolando tipi di IBAN—i QR Reference richiedono QR-IBAN, non IBAN standard.
Ho bisogno di un conto bancario speciale?
Nessun conto speciale necessario per fatture con IBAN standard. Per fatture QR-IBAN con abbinamento automatico dei pagamenti, contatta la tua banca per attivare il servizio QR-IBAN. La maggior parte dei conti aziendali svizzeri lo include.
Qual è la scadenza per gli indirizzi strutturati?
Obbligatori dal 21 novembre 2025. Conformità completa richiesta entro il 30 settembre 2026. La nostra API supporta già il formato strutturato—sei coperto.
Posso usare IBAN internazionali?
No. La specifica QR-bill svizzera accetta solo IBAN svizzeri (CH) e del Liechtenstein (LI). Per fatturazione internazionale, considera invece le fatture SEPA.
Come calcolo la cifra di controllo del QR Reference?
Non devi farlo. Passa il tuo riferimento a 26 cifre e noi calcoliamo la 27ª cifra (Modulo 10, ricorsivo). L'API gestisce la validazione della cifra di controllo sia per IBAN che per riferimento.
E se l'app bancaria del mio cliente non riconosce il codice QR?
Questo indica: (1) problema di qualità del codice QR nella stampa/visualizzazione PDF, (2) generazione codice QR non conforme, o (3) app bancaria obsoleta. La nostra API genera codici QR completamente conformi testati con tutte le principali app bancarie svizzere. Assicurati che i clienti scansionino dal PDF originale, non da una fotocopia di bassa qualità.
Posso personalizzare il layout della fattura?
Logo e colori sì, layout strutturale no. Le fatture QR svizzere seguono requisiti di formattazione rigorosi per la compatibilità bancaria. Puoi aggiungere il tuo logo, ma il posizionamento della sezione di pagamento e del codice QR sono regolamentati.
Qual è l'uptime della vostra API?
Manteniamo il 99.9% di uptime. Meno di 9 ore di downtime all'anno. I clienti enterprise ricevono supporto prioritario e possono richiedere infrastruttura dedicata.
Quanto velocemente posso integrare questo?
La maggior parte degli sviluppatori completa l'integrazione base in 2-4 ore. Un'implementazione pronta per la produzione con gestione errori, integrazione webhook e test richiede tipicamente 1-2 giorni.
Prezzi Semplici e Trasparenti
Paga solo quello che usi. Sconti volume disponibili per applicazioni ad alto volume.
Test Gratuito
- Fatture di test illimitate
- Nessuna autenticazione richiesta
- Tutte le funzionalità disponibili
- Perfetto per proof-of-concept
Produzione
- Pagamento per fattura generata
- Sconti volume disponibili
- Tutte le funzionalità incluse
- Aggiornamenti conformità 2025 automatici
- Supporto email incluso
- Documentazione completa
Enterprise
- Infrastruttura dedicata
- Supporto prioritario
- SLA personalizzati
- Rate limit più elevati
- Ideale per vendor ERP
- Piattaforme ad alto volume
Inizia a Sviluppare Oggi
Testa immediatamente senza registrazione. Genera la tua prima fattura QR svizzera conforme nei prossimi 5 minuti.
Pronto per integrare la fatturazione QR svizzera?
- Testa immediatamente: Copia il comando curl sopra ed eseguilo nel tuo terminale
- Consulta la documentazione: Riferimento API completo con esempi
- Ottieni la tua chiave API: Richiedi accesso ora
Domande sull'implementazione? Il nostro team di supporto sviluppatori risponde entro 24 ore.
Scrivi a support@magicheidi.ch con il tuo caso d'uso.
Costruito da sviluppatori, per sviluppatori. Comprendiamo la complessità della fatturazione svizzera perché l'abbiamo risolta per noi stessi. Ora condividiamo quella soluzione con voi.
Prova l'API gratis – nessuna carta di credito, nessuna registrazione richiesta per i test.