Webservice - e-Rechnung.gv.at (2024)

Voraussetzungen für die Einlieferung per Webservice

Der Aufruf des Webservices kann aus Programmen auf nahezu jeder Plattform (z.B. Java, .NET, PHP, Perl, Python, Ruby, ...) erfolgen. Es stehen zwei verschiedene Versionen des Webservice zur Verfügung, die beide die Einbringung einer Rechnung unterstützen. Webservice V2.0 ist die empfohlene Variante, da dort mehr Einstellungsmöglichkeiten als bei Webservice V1.2 vorhanden sind.

Hinweis: Die Beschreibung der Einrichtung eines Webservices richtet sich an Spezialisten. WSDL ist ein Standard für Webservices im Internet.

Es wird daher um Verständnis ersucht, dass das BMF und die Unternehmensservice Portal-Hotline für die Lösung von technischen Problemen im Zusammenhang mit der Einrichtung des Webservices nicht zur Verfügung stehen. Es wird empfohlen, derartige Fragen über das Kontaktformular zu stellen oder im ebInterface Forum zu posten.

Voraussetzung für das Webservice

Der Übermittler muss Teilnehmer am Unternehmensservice Portal sein.
Der Teilnehmer muss in der Benutzerverwaltung einen Benutzer für 'Webservices' anlegen. Eine detaillierte Anleitung ist in Kapitel 4.3 "Webservice-Benutzer anlegen" des Leitfaden für die Wirtschaft (PDF) zu finden.
Das e-Rechnung.gv.at Webservice ist mit diesem Webservice-Benutzer zu verwenden.
Das Passwort des Webservice-Benutzers muss bekannt sein.
Es muss eine strukturierte e-Rechnung in einem unterstützten Format vorliegen. Diese muss nicht (kann aber) elektronisch signiert sein.
Allfällige Beilagen zur Rechnung müssen elektronisch in einem unterstützten Format vorliegen.

Ablauf

Die Verarbeitung einer e-Rechnung per Webservice erfolgt in zwei Schritten.

Das eingehende Dokument wird validiert und die e-Rechnung aus selbigem extrahiert. Falls bei der Überprüfung der extrahierten e-Rechnung ein Fehler auftritt, so wird synchron - als direkte Antwort auf das eingehende Dokument - eine Fehlermeldung zurückgeliefert. Ist das Dokument technisch in Ordnung ist, wird es zur weiteren Verarbeitung weitergeleitet, und es wird eine synchrone Erfolgsmeldung (Annahmebestätigung) zurückgeliefert.
Falls der erste Schritt erfolgreich war, wird asynchron eine endgültige Annahme (Erfolg) oder Ablehnung (Fehler) signalisiert. Standardmäßig erfolgt dies per E-Mail. Optional kann im ursprünglichen Webservice-Aufruf aber auch eine sog. "Callback-URL" bzw. "Response-URL" angegeben werden. Falls diese gesetzt ist, versucht e-Rechnung.gv.at die Antwort an diese Webservice-URL zu senden. Falls der Aufruf der Response-URL nicht funktioniert, so wird ein E-Mail gesendet. Die zu implementierende Schnittstelle für dieses Service ist im Reiter Callback zu finden.

Hinweise:

Nach Beendigung des Webservice-Aufrufs wird der Benutzer automatisch ausgeloggt.
Für jede e-Rechnung ist ein eigener Webservice-Aufruf zu erzeugen und zu senden.

Schnittstellenbeschreibung (V2.0)

Diesen Service können Sie umsetzen, um automatisiert e-Rechnungen zu senden. Die Webservice-Schnittstelle bietet im Vergleich zu V1.2 zusätzliche Einstellungsmöglichkeiten an. Diese Schnittstelle steht parallel zu V1.2 zur Verfügung und es nur eine Version umgesetzt werden.

erb-in-invoice-201.wsdl

Der Aufruf des Webservices erfolgt derzeit über https und das USP Die gültige Webservice-Endpunkt-Adresse lautet:

https://txm.portal.at/at.gv.bmf.erb/V2

Eine Beschreibung, wie das Webservice getestet werden kann ist verfügbar.

Hinweise:

für die https-Übertragung an die oben genannte Webservice-Endpunkt-Adresse muss mindestens TLS 1.2 verwendet werden. SSL 3.0, TLS 1.0 und TLS 1.1 können nicht mehr verwendet werden.
es darf kein Slash ("/") am Ende der Webservice-Endpunkt-Adresse stehen!
die SOAP-Nachricht muss in UTF-8 oder iso-8859-1 übertragen werden!
die SOAP-Nachricht muss Windows-(\r\n) oder Linux-Zeilenumbrüche (\n) haben. Mac-Zeilenumbrüche (\r) führen zu einem Fehler!
das SOAP Root-Element Envelope muss eine lange Zeile sein, und darf sich nicht über mehrere Zeilen erstrecken!
im WSSE-Password-Element dürfen keine Leerzeichen enthalten sein! (Gutfall: <wsse:Password>passwd<wsse:Password>; Fehler: <wsse:Password> passwd <wsse:Password>)
im SOAP-Header sollte außer dem minimalen WSSE-Header keine sonstigen Header (z.B. WS-Addressing) enthalten sein. Der WSSE-Header sollte außer Security/UsernameToken keine weiteren Elemente enthalten.
als Content-Type bei der Übertragung muss text/xml verwendet werden!
es muss die XML-Deklaration (<?xml version="1.0" ... ?>) vorhanden sein!
beachten Sie die Formatierung des SOAP-XMLs, wie im Forum beschrieben!
der Base64-codierte Rechnungstext darf keinen BOM (Byte Order Mark) enthalten!
Beilagen die nicht mit der Rechnung übertragen werden (Element ExternalAttachment) sind zwar in der WSDL-Datei spezifiziert, werden aber nicht unterstützt!
für SOAP-Requests die größer als 15MB sind, muss das HTTP Chunked Encoding verwendet werden! (Wikipedia-Eintrag)
unter SOAP-Nachricht testen steht eine interaktive Funktionalität zur Überprüfung von SOAP-Nachrichten auf Korrektheit zur Verfügung.
für die Verwendung via PVP gibt es eigene URLs!

Einstellungsmöglichkeiten

Alle Einstellungen für einen Webservice-Aufruf befinden sich im Element Settings. Folgende Kind-Elemente sind vorhanden:

Callback (0..1) - enthält Einstellungen für den asynchronen Webservice-Callback, bestehend aus:
- Passthrough (0..n) - damit können bei der Rechnungseinbringung beliebige Schlüssel-Wert-Paare angegeben werden, die beim asynchronen Callback wieder zurückgeliefert werden. Der Zweck dieses Elements ist das einfache Mapping einer asynchronen Antwort zu einer Rechnungseinbringung. Der Name muss im Attribut name angegeben werden. Es muss darauf geachtet werden, dass jedes Passthrough-Element einen eindeutigen Namen hat.
- @url (1..1) - gibt die URL an, unter der das Webservice-Callback erreichbar ist. Diese URL muss öffentlich zugänglich sein, kann jedoch mit einem IP-Adressen-Filter auf www.e-rechnung.gv.at und/oder test.e-rechnung.gv.at geschützt werden.
- @version (1..1) - gibt die Version des asynchronen Callbacks an, dass verwendet werden soll. Derzeit gibt es nur Version 1.0 des asynchronen Callbacks und dafür muss als Wert 100 angegeben werden.
- @soapaction (0..1) - falls das in @url spezifizierte Webservice eine SOAP-Action benötigt, so kann diese in diesem Attribut angegeben werden. Standardmäßig wird keine SOAP-Action gesendet.
EmailSettings (0..1) - enthält Einstellungen für den E-Mail-Versand, bestehend aus:
- AlternateResponseEmail (0..n) - überschreibt die E-Mail-Adressen für die asynchrone E-Mail-Kommunikation. Wenn mindestens ein AlternateResponseEmail-Element vorhanden ist, wird das E-Mail mit der Erfolgs- oder Fehlermeldung an diese E-Mail-Adresse(n) gesendet und nicht mehr an die in der Rechnung spezifizierten E-Mail-Adresse(n).
- AdditionalResponseEmail (0..n) - fügt zusätzliche E-Mail-Adressen für die asynchrone E-Mail-Kommunikation hinzu. Diese Element wird nur ausgewertet wenn kein AlternateResponseEmail-Element vorhanden ist.
- ResponseEmailCC (0..n) - fügt zusätzliche E-Mail-Adressen als CC-Empfänger zur Rechnung hinzu. Dieses Element wird immer ausgewertet.
- ResponseEmailBCC (0..n) - fügt zusätzliche E-Mail-Adressen als BCC-Empfänger zur Rechnung hinzu. Dieses Element wird immer ausgewertet.
- SubjectPrefix (0..1) - fügt der versendeten E-Mail ein zusätzliches Präfix hinzu und dient zur besseren Filterung von e-Rechnung.gv.at-E-Mails. Hinweis: dieses Präfix wird immer nach dem Standard-Präfix [ERB] hinzugefügt.
TechnicalContact (0..1) - dient zur Angabe der E-Mail-Adresse eines technischen Verantwortlichen falls es beim Aufruf des asynchronen Webservice-Callbacks zu Problemen kommt.
@test (0..1) - dient zur Angabe ob es sich bei dem Webservice-Aufruf um einen Test handelt (Wert true) oder um eine produktive Einlieferung (Wert false). Eine ausführlichere Beschreibung befindet sich unter Test.
@language (0..1) - definiert die Sprache, in der Fehlermeldungen ausgegeben werden sollen. Standardmäßig wird der Wert de für Deutsch verwendet. Alternativ kann derzeit nur en für Englisch verwendet werden.

Schnittstellenbeschreibung (V1.2)

Diesen Service können Sie umsetzen, um automatisiert e-Rechnungen zu senden.

Es wird empfohlen die Version 2.0 des Webservices umzusetzen, da diese mehr Einstellungsmöglichkeiten bietet.

erb-in-invoice-122.wsdl

Der Aufruf des Webservices erfolgt derzeit über https und das USP. Die gültige Webservice-Endpunkt-Adresse lautet:

https://txm.portal.at/at.gv.bmf.erb/V1

Eine Beschreibung, wie das Webservice getestet werden kann ist verfügbar.

Hinweise:

für die https-Übertragung an die oben genannte Webservice-Endpunkt-Adresse muss mindestens TLS 1.2 verwendet werden. SSL 3.0, TLS 1.0 und TLS 1.1 können nicht mehr verwendet werden.
es darf kein Slash ("/") am Ende der Webservice-Endpunkt-Adresse stehen!
die SOAP-Nachricht muss in UTF-8 oder iso-8859-1 übertragen werden!
die SOAP-Nachricht muss Windows-(\r\n) oder Linux-Zeilenumbrüche (\n) haben. Mac-Zeilenumbrüche (\r) führen zu einem Fehler!
das SOAP Root-Element Envelope muss eine lange Zeile sein, und darf sich nicht über mehrere Zeilen erstrecken!
im WSSE-Password-Element dürfen keine Leerzeichen enthalten sein! (Gutfall: <wsse:Password>passwd<wsse:Password>; Fehler: <wsse:Password> passwd <wsse:Password>)
im SOAP-Header sollte außer dem minimalen WSSE-Header keine sonstigen Header (z.B. WS-Addressing) enthalten sein. Der WSSE-Header sollte außer Security/UsernameToken keine weiteren Elemente enthalten.
als Content-Type bei der Übertragung muss text/xml verwendet werden!
es muss die XML-Deklaration (<?xml version="1.0" ... ?>) vorhanden sein!
beachten Sie die Formatierung des SOAP-XMLs, wie im Forum beschrieben!
der Base64-codierte Rechnungstext darf keinen BOM (Byte Order Mark) enthalten!
für SOAP-Requests die größer als 15MB sind, muss das HTTP Chunked Encoding verwendet werden! (Wikipedia-Eintrag)
unter SOAP-Nachricht testen steht eine interaktive Funktionalität zur Überprüfung von SOAP-Nachrichten auf Korrektheit zur Verfügung.
für die Verwendung via PVP gibt es eigene URLs!

USP Webservicekonto

Für die Authentifizierung muss für ein Unternehmen im Unternehmensservice Portal ein Webservicekonto angelegt sein. Die dazugehörigen Zugangsdaten sind im SOAP-SecurityHeader im sogenannten <UsernameToken> anzuführen. Eine ausführliche Anleitung zum Einrichten des e-Rechnung.gv.at-Webservice-Benutzers im USP finden Sie im Leitfaden (PDF) (der auch unter Downloads verfügbar ist)!

Die offizielle Spezifikation von OASIS finden Sie unter http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf.

Asynchroner Webservice Callback (V1.0)

Diesen Service können Sie als Server implementieren, um eine asynchrone Antwort von e-Rechnung.gv.at zu bekommen. Sobald feststeht, ob die Rechnung inhaltlich korrekt ist oder nicht, werden Sie von e-Rechnung.gv.at über diese Schnittstelle informiert. Sie können sowohl einen http- als auch einen https-Endpunkt verwenden - e-Rechnung.gv.at kann mit beiden Protokollen kommunizieren. Falls Sie https verwenden, reicht die Verwendung eines selbst-signierten Zertifikats technisch aus. Das Callback muss auf einem der folgenden Ports auf ihrem System laufen: 8080, 8412, 44300-44399 oder 58700-58799. Port 80 und 443 sind aus Sicherheitsgründen leider keine Option!

Hinweis: wenn Sie https verwenden muss die Gegenstelle mindestens TLS 1.2 unterstützen! SSLv3, TLS 1.0 und TLS 1.1 werden nicht unterstützt.

erb-out-invoice-callback-100.wsdl

Verwendung mit Webservice 2.0: die Endpunkt-Adresse, auf der Ihre Service Implementierung verfügbar ist, muss im Attribut url des Elements Settings/Callback bei der Einlieferung der Rechnung hinterlegt sein. Außerdem muss das Attribut version im Element Settings/Callback gesetzt sein. Dieses gibt die Version des Callbacks an und unterstützt derzeit nur den Wert 100. Wurde eines dieser Attribute nicht gesetzt, oder hat der Aufruf des Webservices nicht funktioniert, werden Sie in einer E-Mail darüber informiert.

Verwendung mit Webservice 1.2: die Endpunkt-Adresse, auf der Ihre Service Implementierung verfügbar ist, muss im Attribut ResponseServiceURL des Elements Settings bei der Einlieferung der Rechnung hinterlegt sein. Wurde dieses Attribut nicht gesetzt, oder hat der Aufruf des Webservices nicht funktioniert, werden Sie in einer E-Mail darüber informiert.

Hinweis: dieser Service steht nur bei Verwendung der Webservice-Einlieferung zur Verfügung. Bei der Einbringung der e-Rechnung im Wege des Uploads, des Online-Formulars oder Peppol besteht diese Option nicht.

Fehlermeldungen

Nachdem die Fehlermeldungen der Webserviceeinbringung teilweise sehr kryptisch sind (und wir leider keinen Einfluss auf diese haben), hier eine kleine Hilfestellung, welcher Fehler was bedeuten kann (diese Liste erhebt keinen Anspruch auf Vollständigkeit):

HTTP 302 → Konto nicht vorhanden/falscher Username (Fehlermeldung Wrong Credentials (1))
HTTP 302 → Passwort nicht korrekt (Fehlermeldung Wrong Credentials (2))
HTTP 302 → Das Hakerl im USP ist nicht gesetzt (Fehlermeldung Missing Permissions)
HTTP 302 → HTTP 404 → Konto ist gesperrt, da der User zu oft (4 mal) ein falsches Passwort mitgeschickt hat (Entsperrung im USP notwendig - eine Anleitung findet sich im Dokument "Entsperren eines Webservice-Benutzers im USP" unter Downloads)
HTTP 412 → auf Grund eines internen Fehlers konnte der Webservice-Aufruf nicht durchgeführt werden. Bitte versuchen Sie es erneut.
HTTP 415 → der falsche Content-Type HTTP-Header wird verwendet. Es muss text/xml verwendet werden.
HTTP 500 → das USP-Webservice-Konto hat das notwendige Recht nicht zugewiesen. Falls das Test-Webservice angesprochen werden soll, so muss vorher das notwendige Recht im USP von uns freigeschaltet und von Ihnen aktiviert werden!
HTTP 500 → die SOAP-Nachricht entspricht nicht der WSDL-Datei (in diesem Fall kann die SOAP-Nachricht im SOAP-Tester auf bekannte Fehlerquellen untersucht werden)
HTTP 500 → in der SOAP-Nachricht werden die falschen Zeilenumbrüche (Mac - \r) verwendet
HTTP 500 → in der SOAP-Nachricht wird ein anderes Encoding als ISO-8859-1 oder UTF-8 verwendet
HTTP 500 → das Root-Element der SOAP-Nachricht (Envelope) ist nicht in einer einzigen Zeile angegeben!

Wenn die Überprüfung von Benutzername und Passwort erfolgreich war, werden ganze "normale" SOAP-Faults mit sprechenden Fehlermeldungen wie sie auch in der Fehlerliste zu finden sind zurück gegeben.