QR-RECHNUNG SCHWEIZ – API

Zur Vereinfachung und Harmonisierung des Zahlungsverkehrs wird in der Schweiz die QR-Rechnung eingeführt. Seit dem 30. Juni 2020 ist es möglich, QR-Rechnungen zu verwenden. Bis zum 30. September 2022 ist ein Parallelbetrieb der verschiedenen EZ-Systeme vorgesehen. Ab dem 1. Oktober 2022 kann nur noch die QR-Rechnung verwendet werden. Bei etlichen Systemen besteht also dringender Handlungsbedarf.

Rechnung oder Code kostenlos generieren lassen

Die Implementierung der QR-Rechnung in bestehende Applikationen ist nicht immer ohne Weiteres möglich. Setzt man als Entwickler die Generierung der QR-Rechnung selber um, so ist das zudem u.U. mit erheblichem Aufwand für Recherche und Programmierung verbunden. LivingTech stellt daher interessierten Entwicklern eine kostenlose API zur Generierung der QR-Rechnung zur Verfügung. Hier finden Sie ein Beispiel der generierten Daten.

Wirklich kostenlos?

Private wie kleinere Unternehmen unterstützen wir mit unserem API Service zur Zeit kostenlos. Die standardmässige tägliche Limite an Requests kann bei Bedarf individuell angepasst werden. Grössere Unternehmen oder Nutzer mit vielen API Calls können sich gerne an uns wenden.

Nutzung – code snippets

FAQ / Nutzungshinweise

Die Version 1 der Schnittstelle für die QR-Rechnung erstellt Rechnungen auf Basis der QR-IBAN sowie einer Referenznummer. Beide Werte sind obligatorisch.

  • Die QR-IBAN finden Sie im Normalfall im Info-Bereich des Zielkontos in Ihrem Online-Banking. Alternativ erkundigen Sie sich bitte bei der kontoführenden Bank und verlangen Sie eine entsprechende QR-IBAN. Bisherige IBAN werden in V1 der API nicht unterstützt.
  • Die Referenznummer für die QR-Rechnung entspricht strukturell dem Schema der bisherigen ESR-Referenznummer. Sie besteht aus der Basis-Nummer (26 Zeichen) sowie der anschliessenden Prüfziffer (Zeichen 27).

V1 der API kann eine Fehlermeldung zurückgeben, falls Sie die Schnittstelle mit einer bisherigen IBAN und/oder einer ungültigen Referenznummer aufrufen.

Falls Bedarf nach QR-Rechnungen ohne Referenznummer oder für bisherige IBAN besteht, so lesen Sie die mit «V2» beschrifteten FAQ. Auch in diesem Fall ist es möglich, Rechnungen mit unserer API erstellen zu lassen.

Zum Generieren von QR-Rechnungen wird standardmässig eine QR-IBAN benötigt. Diese Nummer finden Sie im Normalfall in Ihrem Online-Banking. Die Nummer ist einfach daran erkennbar, dass die Zahl zwischen Position 5 und 9 zwischen 30000 und 31999 liegt. Ist das gegeben, handelt es sich um eine QR-IBAN, ansonsten um eine bisherige IBAN.

Die QR Rechnung-API von LivingTech akzeptiert die QR-IBAN genauso wie die bisherige IBAN. Allerdings gibt es diesbezüglich Unterschiede bei der erlaubten Referenznummer. Mehr dazu finden Sie in der FAQ zu den Referenznummern.

Standardmässig wird bei QR-Rechnungen eine Referenznummer im bisherigen Format verlangt. Diese Referenznummer besteht aus 27 Zahlen, wobei 26 die Nummer definieren und die 27. Stelle als Prüfziffer verwendet wird. Die QR-API von LivingTech akzeptiert diese Referenznummer sowohl mit 26 Zeichen (ohne Prüfziffer – wir berechnen diese und fügen sie dynamisch an) wie auch mit 27 Zeichen (inkl. Prüfziffer). Die Referenznummern bisheriger ESR-Systeme sollten übernommen werden können.

Eine QR-Rechnung mit QR-IBAN aber ohne Referenznummer ist nicht vorgesehen und nicht möglich.

Möchten Sie QR-Rechnungen ohne Referenznummer erstellen oder verfügen Sie nicht über eine QR-IBAN, dann halten Sie sich an die Details der FAQ «QR-Rechnung mit bisheriger IBAN».

Es ist grundsätzlich möglich, eine QR-Rechnung ohne Referenznummer zu erstellen. Möchten Sie eine Rechnung ohne Referenz erstellen, so müssen Sie als Kontonummer die bisherige IBAN angeben (nicht QR-IBAN).

Sollten Sie nur über eine bisherige IBAN und keine QR-IBAN verfügen und trotzdem eine Referenznummer in die Rechnung einfügen wollen, so ist auch dies möglich. Übergeben Sie als Konto die bisherige IBAN und senden Sie uns als Referenznummer eine Nummer im SCOR-Format (Structured Creditor Reference – ISO-11649). Beispiel einer solchen Referenz: RF54O00WER. Die Referenznummer beginnt jeweils mit «RF», gefolgt von zwei Prüfziffern und der selbstgewählten eigentlichen Referenznummer (alphanumerisch – maximal 21 Zeichen).

Die QR-API von LivingTech unterstützt Sie bei der Erstellung der SCOR. Sie können der API entweder eine vollständige und gültige SCOR übergeben oder alternativ lediglich den individuellen Teil. Erkennen wir keine gültige/vollständige Referenznummer, so versuchen wir, die angegebene Referenznummer zu einer gültigen SCOR zu vervollständigen. Übergeben Sie uns also z.B. «O00WER» als Referenznummer, so wandeln wir diese in «RF54O00WER» um und integrieren diesen String als Referenz in die QR-Rechnung.

V1 der API ermöglichte lediglich QR-Rechnungen mit QR-IBAN und Referenznummer. V2 der Schnittstelle adressiert dieses Problem und stellt weitere Funktionen zur Verfügung (vgl. weitere FAQ). Für die API gilt:

  • Verwenden Sie im Normalfall V2 und den Endpoint: http://v2.qrbillservice.livingtech.ch
  • Ihr API-Schlüssel gilt sowohl für V1 wie auf für V2 der Schnittstelle
  • Ihre Abfrage-Limite gilt unabhängig von V1 oder V2 für alle Requests an unsere QR-Schnittstellen gemeinsam
  • Die oben aufgeführten Snippets beziehen sich auf V2 – V1 ist weiterhin unter http://qrbillservice.livingtech.ch erreichbar

Anpassungen von V1 auf V2

Der Umstieg von V1 auf V2 sollte mit wenigen Anpassungen am Code möglich sein. Grundsätzlich stellt die API die gleichen Funktionen zur Verfügung, erweitert sie jedoch um die Optionen zu bisherigem IBAN oder Weglassen der Referenznummer. Trotzdem haben sich kleinere Änderungen an der Response ergeben, welche im Client-Code implementiert werden müssen.

  • «isSuccessed» heisst neu «isSuccess«

Anpassungen V1.R1 auf V1.R2:

  • die Base64-Payload kommt nun im Feld «base64Content» zurück (bisher «base64Image»)
  • die Nachricht wird neu im Feld «message» statt bisher «Message» zurückgegeben

Über uns

Die QR-Rechnungs-API ist ein kostenloser Service der LivingTech GmbH. Wir erstellen Webseiten, setzen E-Commerce-Projekte um und entwickeln kundenspezifische Webapplikationen. Alles aus einer Hand – lokal, unkompliziert und fair. Haben Sie Fragen? Melden Sie sich bei uns.

QR-RECHNUNG SCHWEIZ – API

Zur Vereinfachung und Harmonisierung des Zahlungsverkehrs wird in der Schweiz die QR-Rechnung eingeführt. Seit dem 30. Juni 2020 ist es möglich, QR-Rechnungen zu verwenden. Bis zum 30. September 2022 ist ein Parallelbetrieb der verschiedenen EZ-Systeme vorgesehen. Ab dem 1. Oktober 2022 kann nur noch die QR-Rechnung verwendet werden. Bei etlichen Systemen besteht also dringender Handlungsbedarf.

Rechnung oder Code kostenlos generieren lassen

Die Implementierung der QR-Rechnung in bestehende Applikationen ist nicht immer ohne Weiteres möglich. Setzt man als Entwickler die Generierung der QR-Rechnung selber um, so ist das zudem u.U. mit erheblichem Aufwand für Recherche und Programmierung verbunden. LivingTech stellt daher interessierten Entwicklern eine kostenlose API zur Generierung der QR-Rechnung zur Verfügung. Hier finden Sie Beispiel der generierten Daten.

Nutzung – code snippets

FAQ / Nutzungshinweise

Die Version 1 der Schnittstelle für die QR-Rechnung erstellt Rechnungen auf Basis der QR-IBAN sowie einer Referenznummer. Beide Werte sind obligatorisch.

  • Die QR-IBAN finden Sie im Normalfall im Info-Bereich des Zielkontos in Ihrem Online-Banking. Alternativ erkundigen Sie sich bitte bei der kontoführenden Bank und verlangen Sie eine entsprechende QR-IBAN. Bisherige IBAN werden in V1 der API nicht unterstützt.
  • Die Referenznummer für die QR-Rechnung entspricht strukturell dem Schema der bisherigen ESR-Referenznummer. Sie besteht aus der Basis-Nummer (26 Zeichen) sowie der anschliessenden Prüfziffer (Zeichen 27).

V1 der API kann eine Fehlermeldung zurückgeben, falls Sie die Schnittstelle mit einer bisherigen IBAN und/oder einer ungültigen Referenznummer aufrufen.

Falls Bedarf nach QR-Rechnungen ohne Referenznummer oder für bisherige IBAN besteht, so lesen Sie die mit «V2» beschrifteten FAQ. Auch in diesem Fall ist es möglich, Rechnungen mit unserer API erstellen zu lassen.

Zum Generieren von QR-Rechnungen wird standardmässig eine QR-IBAN benötigt. Diese Nummer finden Sie im Normalfall in Ihrem Online-Banking. Die Nummer ist einfach daran erkennbar, dass die Zahl zwischen Position 5 und 9 zwischen 30000 und 31999 liegt. Ist das gegeben, handelt es sich um eine QR-IBAN, ansonsten um eine bisherige IBAN.

Die QR Rechnung-API von LivingTech akzeptiert die QR-IBAN genauso wie die bisherige IBAN. Allerdings gibt es diesbezüglich Unterschiede bei der erlaubten Referenznummer. Mehr dazu finden Sie in der FAQ zu den Referenznummern.

Standardmässig wird bei QR-Rechnungen eine Referenznummer im bisherigen Format verlangt. Diese Referenznummer besteht aus 27 Zahlen, wobei 26 die Nummer definieren und die 27. Stelle als Prüfziffer verwendet wird. Die QR-API von LivingTech akzeptiert diese Referenznummer sowohl mit 26 Zeichen (ohne Prüfziffer – wir berechnen diese und fügen sie dynamisch an) wie auch mit 27 Zeichen (inkl. Prüfziffer). Die Referenznummern bisheriger ESR-Systeme sollten übernommen werden können.

Eine QR-Rechnung mit QR-IBAN aber ohne Referenznummer ist nicht vorgesehen und nicht möglich.

Möchten Sie QR-Rechnungen ohne Referenznummer erstellen oder verfügen Sie nicht über eine QR-IBAN, dann halten Sie sich an die Details der FAQ «QR-Rechnung mit bisheriger IBAN».

Es ist grundsätzlich möglich, eine QR-Rechnung ohne Referenznummer zu erstellen. Möchten Sie eine Rechnung ohne Referenz erstellen, so müssen Sie als Kontonummer die bisherige IBAN angeben (nicht QR-IBAN).

Sollten Sie nur über eine bisherige IBAN und keine QR-IBAN verfügen und trotzdem eine Referenznummer in die Rechnung einfügen wollen, so ist auch dies möglich. Übergeben Sie als Konto die bisherige IBAN und senden Sie uns als Referenznummer eine Nummer im SCOR-Format (Structured Creditor Reference – ISO-11649). Beispiel einer solchen Referenz: RF54O00WER. Die Referenznummer beginnt jeweils mit «RF», gefolgt von zwei Prüfziffern und der selbstgewählten eigentlichen Referenznummer (alphanumerisch – maximal 21 Zeichen).

Die QR-API von LivingTech unterstützt Sie bei der Erstellung der SCOR. Sie können der API entweder eine vollständige und gültige SCOR übergeben oder alternativ lediglich den individuellen Teil. Erkennen wir keine gültige/vollständige Referenznummer, so versuchen wir, die angegebene Referenznummer zu einer gültigen SCOR zu vervollständigen. Übergeben Sie uns also z.B. «O00WER» als Referenznummer, so wandeln wir diese in «RF54O00WER» um und integrieren diesen String als Referenz in die QR-Rechnung.

V1 der API ermöglicht lediglich QR-Rechnungen mit QR-IBAN und Referenznummer. V2 der Schnittstelle adressiert dieses Problem und stellt weitere Funktionen zur Verfügung (vgl. weitere FAQ). Sollten Sie Funktionen der V2 benötigen, so gilt:

  • Verwenden Sie den Endpoint: http://v2.qrbillservice.livingtech.ch
  • Ihr API-Schlüssel gilt sowohl für V1 wie auf für V2 der Schnittstelle
  • Ihre Abfrage-Limite gilt unabhängig von V1 oder V2 für alle Requests an unsere QR-Schnittstellen gemeinsam

Anpassungen von V1 auf V2

Der Umstieg von V1 auf V2 sollte mit wenigen Anpassungen am Code möglich sein. Grundsätzlich stellt die API die gleichen Funktionen zur Verfügung, erweitert sie jedoch um die Optionen zu bisherigem IBAN oder Weglassen der Referenznummer. Trotzdem haben sich kleinere Änderungen an der Response ergeben, welche im Client-Code implementiert werden müssen.

  • «isSuccessed» heisst neu «isSuccess«

Anpassungen V1.R1 auf V1.R2:

  • die Base64-Payload kommt nun im Feld «base64Content» zurück (bisher «base64Image»)
  • die Nachricht wird neu im Feld «message» statt bisher «Message» zurückgegeben

API Key anfordern

Erstellen Sie sich mit folgenden Formular einen API-Key. Der Service ist für Private und kleine Unternehmen kostenlos (fair use policy) und der Key wird Ihnen umgehend per Mail zugestellt. Happy coding.

API Key anfordern

Erstellen Sie sich mit folgenden Formular einen API-Key. Der Service ist für Private und kleine Unternehmen kostenlos (fair use policy) und der Key wird Ihnen umgehend per Mail zugestellt. Happy coding.

Beispiele für Rückgabe

Sie können über Parameter festlegen, welche Art von Rückgabe Sie von der API erwarten. Entweder ein normiertes PDF mit dem vollständigen Einzahlungsschein oder den reinen QR-Code. Die Daten werden jeweils als Base64-kodierter String zurückgegeben.

Einzahlungsschein als PDF

Standardmässig gibt Ihnen die API ein einseitiges PDF-Dokument mit dem QR-Einzahlungsschein am unteren Ende zurück. Dieses Dokument können Sie Ihrer Rechnung anstelle des bisherigen orangen EZ beifügen. Der QR-EZ enthält alle notwendigen Informationen und entspricht den offiziellen Vorgaben.

QR Rechnung

QR-Code als PNG

Alternativ können Sie sich den Einzahlungsschein auch selber erstellen – oder ganz darauf verzichten. In diesem Fall fordern Sie bei der API lediglich den QR-Code als PNG an. Der Code enthält alle relevanten Zahlungsinformationen und kann vom Enduser in der Banking-App gescannt werden.

QR Code