Du entwickelst Rechnungsfunktionen für den Schweizer Markt? Trenne PDF-Erzeugung, Swiss-QR-Zahlteil und Zahlungsabgleich. Diese Seite hilft, die fachlichen Anforderungen und die Abnahme einer möglichen Integration festzulegen.
Ein konkreter Zeitaufwand lässt sich erst nach Prüfung von Vertrag, Datenmodell und Testfällen abschätzen.
Integrationsstand und Zugang klären
Stand: 1. November 2026. Diese Seite ist eine technische Orientierung, keine freigegebene Spezifikation einer öffentlichen API. Vor einer Integration benötigst du den aktuell unterstützten Vertrag, Zugangsbedingungen und einen ausdrücklich freigegebenen Testweg. Kontaktiere Magic Heidi mit deinem Anwendungsfall und erwarteten Volumen.
Frühere Fassungen dieser Seite und des Blogartikels enthielten widersprüchliche Request- und Response-Beispiele. Diese Beispiele sind keine verlässliche Grundlage für Produktivcode und werden hier nicht als «Copy-paste»-Integration fortgeführt. Insbesondere sind Feldnamen, Datumsformat, MWST-Skalierung und Antwortstruktur vor einer Nutzung zu bestätigen.
Es wird hier weder ein kostenloser öffentlicher Test-Endpunkt noch ein bestimmtes Authentifizierungsverfahren, Rate Limit, Preis, SLA oder Ablaufdatum von PDF-Links zugesichert. Sende ohne abgestimmte Testumgebung keine realen Kunden-, Patienten- oder Bankdaten an einen Endpunkt.
Was ein freigegebener API-Vertrag festlegen muss
| Bereich | Vor Implementierung klären |
|---|---|
| Request | Pflichtfelder, Datentypen, Datumsformat, Währung und Rechnungsnummer |
| MWST | Dezimal- oder Prozentdarstellung, Rundung, Brutto-/Netto-Modus und mehrere Sätze |
| Adresse | Getrennte Adressbestandteile, Land und Validierungsregeln |
| Konto/Referenz | Unterstützte IBAN-Typen, QRR/SCOR/NON, Prüfziffern und optionale Mitteilung |
| Antwort | Tatsächlicher JSON-Pfad zum PDF, Status-/Fehlerformat und Downloadberechtigung |
| Betrieb | Authentifizierung, Limits, Zeitüberschreitungen, Wiederholungen und Schutz vor doppelter Erzeugung |
| Daten | Speicherort, Zugriff, Löschung, Linkgültigkeit und eigene Archivierung |
Technischer Abnahmetest
- Verwende nur abgestimmte, nicht abrechenbare Testaufrufe mit synthetischen Daten.
- Prüfe Erfolg und Validierungsfehler gegen die tatsächliche Antwort; rate keine Feldnamen oder Fehlercodes.
- Lade das PDF herunter und prüfe Summen, Rundung, Sprache und Steuerangaben.
- Lies den QR-Datensatz aus und prüfe Konto, Referenz, Währung und Adressfelder gegen die aktuellen SIX-Vorgaben.
- Teste Fehlerfälle für ungültige IBAN, unzulässige Kontoreferenz-Kombination, fehlende Adresse und nicht unterstützte Währung. Ein HTTP-Erfolg allein beweist keine korrekte Rechnung.
- Vereinbare vor einem Wiederholungsmechanismus, wie doppelte PDF-Erzeugung oder doppelte Rechnungsnummern vermieden werden. Protokolliere keine vollständigen personenbezogenen Rechnungsdaten.
Sinnvolle Anwendungsfälle
Ein freigegebener Erzeugungsdienst kann in einen bestehenden Rechnungsprozess, eine Mitgliederverwaltung oder eine Bestellabwicklung eingebunden werden. Ein QR-PDF nimmt jedoch keine Zahlung entgegen und belegt keinen Zahlungseingang. Für einen automatischen Abgleich brauchst du zusätzlich passende Bankdaten und einen getesteten Zuordnungsprozess.
QR-IBAN vs normale IBAN verstehen
Das verwirrt die meisten Entwickler anfangs. Hier ist der praktische Unterschied:
Wann QR-IBAN verwenden
QR-IBAN verwenden, wenn: dein vereinbarter Zahlungsprozess QRR nutzt. Die 27-stellige QR-Referenz unterstützt eine eindeutige Zuordnung. Ein tatsächlicher Abgleich braucht zusätzlich geeignete Bankdaten und Software; das erzeugte PDF selbst markiert keine Rechnung als bezahlt.
QR-IBAN erkennen: Die 5. bis 9. Stelle (IID) liegt zwischen 30000 und 31999.
- Prüfe die vom Institut ausgegebene QR-IBAN; verwende keine erfundene Beispiel-IBAN für Tests.
QR-IBAN erhalten: Kontaktiere deine Schweizer Bank. Banken stellen QR-IBANs neben deinen normalen IBANs aus. Konditionen und Einrichtung richten sich nach dem Institut.
Wann normale IBAN verwenden
Normale IBAN verwenden, wenn: einfache Rechnungsstellung genügt. Du gleichst eingehende Zahlungen manuell mit Rechnungen ab, oder du nutzt das Creditor Reference Feld (ISO 11649 Format) für halbautomatischen Abgleich.
Normale IBAN erkennen: Standard Schweizer IBAN-Format mit IID ausserhalb des Bereichs 30000-31999.
Referenz-Kompatibilität
- QR-IBAN → Muss QR-Referenz verwenden (27 Stellen)
- Normale IBAN → Kann Creditor Reference oder keine Referenz verwenden
In der Abnahme prüfen: Eine QR-Referenz mit normaler IBAN ist keine zulässige Kombination. Wie der konkrete Dienst diesen Fehler meldet, muss der freigegebene Vertrag festlegen.
Schweizer QR-Zahlteil und internationale Rechnungen
Der Swiss-QR-Zahlteil verwendet CH- oder LI-Kontodaten und CHF oder EUR. Daraus folgt nicht, dass nur Kunden in diesen Ländern Rechnungen erhalten dürfen. Für andere Währungen oder nicht QR-fähige Kontodaten braucht das Rechnungsdokument einen passenden anderen Zahlungsblock.
Die QR-Rechnung ersetzt seit 1. Oktober 2022 die früheren Einzahlungsscheine; sie ist keine Pflicht für jedes Rechnungsdokument. Pflege Adressdaten strukturiert und prüfe die jeweils geltenden SIX-Richtlinien und Übergangshinweise. Ein Dienst kann fehlerhafte Eingaben nicht pauschal in rechtlich korrekte Rechnungen verwandeln.
Nächster Schritt
Fordere den unterstützten Vertrag und einen freigegebenen Testzugang über hello@magicheidi.ch an. Kläre zuerst Zugang, Datenschutz und Abrechnung. Erst danach lohnt es sich, einen sprachspezifischen Client zu schreiben und mit reproduzierbaren Tests abzunehmen.
