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.

Generazione Fatture QR Svizzere

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.
Funzionalità Complete

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
Quick Start

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

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.

Esempi di Codice

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.

Tempo di risposta 2 secondi
🔒 Conforme ISO 20022
🌍 Pronto multilingue
Indirizzi strutturati 2025
💼
Piattaforme SaaS di Fatturazione

Aggiungi supporto per il mercato svizzero. I codici QR rendono i pagamenti dei clienti semplici tramite scansione dall'app bancaria.

🔄
Integrazione ERP e CRM

Collega i sistemi esistenti alla generazione automatica di fatture. Creazione fatture attivata da webhook con dati CRM.

👨‍💼
Strumenti per Liberi Professionisti

Supporto multilingue, gestione IVA corretta, PDF professionali. Conformità svizzera gestita automaticamente.

🛒
Checkout E-commerce

Offri il metodo di pagamento "Fattura" per B2B. Genera fatture QR immediatamente dopo la conferma dell'ordine.

🏢
Organizzazioni con Membri

Automatizza la riscossione delle quote associative. Riferimenti QR univoci per abbinamento automatico dei pagamenti.

📱
Applicazioni Mobile

Genera fatture ovunque ti trovi. Integrazione API leggera per app iOS e Android.

Dettagli Tecnici

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.

FAQ

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

CHF0/month
Fatture di Test Illimitate
  • Fatture di test illimitate
  • Nessuna autenticazione richiesta
  • Tutte le funzionalità disponibili
  • Perfetto per proof-of-concept
Inizia a Testare Ora

Enterprise

CHFCustom/month
Infrastruttura Dedicata
  • Infrastruttura dedicata
  • Supporto prioritario
  • SLA personalizzati
  • Rate limit più elevati
  • Ideale per vendor ERP
  • Piattaforme ad alto volume
Contatta le Vendite
🛡️Tutti i piani includono accesso API completo, supporto multilingue, compatibilità QR-IBAN e aggiornamenti automatici di conformità.

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?

  1. Testa immediatamente: Copia il comando curl sopra ed eseguilo nel tuo terminale
  2. Consulta la documentazione: Riferimento API completo con esempi
  3. 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.