Magic Heidi Schweizer QR-Rechnung API: Integration gezielt vorbereiten
Klären Sie den unterstützten Vertrag und Testzugang, bevor Sie Request-Felder oder Antwortformate implementieren. QR-Validierung und Rechnungsprüfung bleiben Teil der Abnahme.
Sie entwickeln Rechnungsfunktionen für den Schweizer Markt? Trennen Sie 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ötigen Sie den aktuell unterstützten Vertrag, Zugangsbedingungen und einen ausdrücklich freigegebenen Testweg. Kontaktieren Sie Magic Heidi mit Ihrem 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. Senden Sie 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
- Verwenden Sie nur abgestimmte, nicht abrechenbare Testaufrufe mit synthetischen Daten.
- Prüfen Sie Erfolg und Validierungsfehler gegen die tatsächliche Antwort; raten Sie keine Feldnamen oder Fehlercodes.
- Laden Sie das PDF herunter und prüfen Sie Summen, Rundung, Sprache und Steuerangaben.
- Lesen Sie den QR-Datensatz aus und prüfen Sie Konto, Referenz, Währung und Adressfelder gegen die aktuellen SIX-Vorgaben.
- Testen Sie 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.
- Vereinbaren Sie vor einem Wiederholungsmechanismus, wie doppelte PDF-Erzeugung oder doppelte Rechnungsnummern vermieden werden. Protokollieren Sie 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 brauchen Sie 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: Ihr 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üfen Sie die vom Institut ausgegebene QR-IBAN; verwenden Sie keine erfundene Beispiel-IBAN für Tests.
QR-IBAN erhalten: Kontaktieren Sie Ihre Schweizer Bank. Sie stellen QR-IBANs neben Ihren normalen IBANs aus. Konditionen und Einrichtung richten sich nach dem Institut.
Wann normale IBAN verwenden
Normale IBAN verwenden, wenn: Einfache Rechnungsstellung genügt. Sie gleichen eingehende Zahlungen manuell mit Rechnungen ab, oder Sie nutzen 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. Pflegen Sie Adressdaten strukturiert und prüfen Sie die jeweils geltenden SIX-Richtlinien und Übergangshinweise. Ein Dienst kann fehlerhafte Eingaben nicht pauschal in rechtlich korrekte Rechnungen verwandeln.
Nächster Schritt
Fordern Sie den unterstützten Vertrag und einen freigegebenen Testzugang über hello@magicheidi.ch an. Klären Sie zuerst Zugang, Datenschutz und Abrechnung. Erst danach lohnt es sich, einen sprachspezifischen Client zu schreiben und mit reproduzierbaren Tests abzunehmen.