Sa., 14.12.2024, ca. 05:00 bis So., 15.12.2024, ca. 23:00 Uhr
Aufgrund von Wartungsarbeiten im angegebenen Zeitraum kann es auf E-RECHNUNG.GV.AT zu regelmäßigen Ausfällen kommen.
Web service transmission
Prerequisites for transmission via web service
Web services can be invoked from nearly all applications on nearly every platform (like Java, .NET, PHP, Perl, Python, Ruby, ...). Two different web service versions are available for e-Invoice transmission. Web service V2.0 is the recommended variant, as it contains improved customizability compared to Web service V1.2.
Note: the description on how to setup a webs services targets technical specialists. WSDL is a standard for describing web services interfaces.
We therefore ask for your understanding that the Ministry of Finance and the Unternehmensservice portal hotline are not available for solving technical problems in connection with setting up the web service. It is recommended to ask respective questions via the contact form or to post them in the ebInterface forum.
Preconditions for using the web service
- The transmitter must be a registered participant in the Unternehmensservice Portal.
- The participant must create a separate 'Web service user' in the USP administration. A detailed description can be found in chapter 4.3 of the Manual for Invoicing and Submitting (PDF).
- The e-Rechnung.gv.at web service has to be access with this web service user.
- The password of the web service user need to be known.
- A structured electronic invoice in one of the supported formats must be available. The invoice must not be digitally signed. An eventually existing digital signature is ignored.
- Required attachments to the invoice must be available in any of the supported formats.
Process
The processing of an e-Invoice transmitted via web service happens in two steps.
- The incoming document is validated and the e-Invoice is extracted from it. If an error occurs while checking the extracted e-Invoice, an error message is returned synchronously - as a direct response to the incoming document. If the document is technically correct, it is forwarded for further processing and a synchronous success message (acceptance confirmation) is returned.
- If the first step was successful, a final acceptance (success) or rejection (error) is signalled asynchronously. By default, this is done by e-mail. Optionally, however, a so-called "Callback URL" or "Response URL" can also be specified in the original web service call. If this is set, e-Rechnung.gv.at attempts to send the response to this web service URL. If calling up the response URL does not work, an e-mail is sent instead. The interface to be implemented for this service can be found on the Callback tab.
Notes:
- The web service user is automatically logged out after the invocation of the web service.
- A separate web service call needs to be triggered for each e-Invoice.
Interface description (V2.0)
Implement this service to automatically transmit e-Invoices. This web service offers increased customizability options compared to version 1.2. This interface exists in parallel to version 1.2 and only one version needs to be implemented.
The invocation of the web service has to be done via https and the USP. The valid web service endpoint URL is:
https://txm.portal.at/at.gv.bmf.erb/V2
See Testing the web service on how to test the transmission via web service.
Notes:
- The https transmission to the endpoint URL requires at least TLS 1.2. SSL 3.0, TLS 1.0 and TLS 1.1 are no longer supported
- The web service endpoint URL may NOT end with a slash character ("/")
- The SOAP message must use UTF-8 or iso-8859-1 encoding
- The SOAP message must use Windows (
\r\n
) or Linux (\n
) line breaks. Mac line breaks (\r
) will lead to an error. - The SOAP message root element
Envelope
must be one long line and must not span several lines. - The WSSE
Password
element may not contain any whitespaces. (Good case:<wsse:Password>passwd<wsse:Password>
; bad case:<wsse:Password> passwd <wsse:Password>
) - The SOAP header should only contain the minimal WSSE header and no other headers (e.g. WS addressing). The WSSE header should only contain the
Security/UsernameToken
elements. - The http
Content-Type
of the transmission must betext/xml
. - The XML declaration (
<?xml version="1.0" ... ?>
) must be present. - The formatting rules of SOAP XMLs are described in the forum.
- The Base64 encoded e-Invoice representation may not contains a BOM (Byte Order Mark).
- Attachments that are not transmitted together with the e-Invoice (element
ExternalAttachment
) are specified in the WSDL file but are NOT supported. - SOAP requests larger than 15MB require the usage of HTTP chunked encoding (see Wikipedia)
- The SOAP message tester provides an interactive way to test complete SOAP messages for correctness.
- Separate URLs are required when using PVP (the Austrian governmental SSO solution).
Customizing options
All customizing settings of a web service invocation can be found in element Settings
. It contains the following child elements:
Callback
(0..1) - contains settings for the asynchronous web service callback, consisting of:-
Passthrough
(0..n) - so that any key-value pairs can be specified during invoice insertion, which are returned during asynchronous callback. The purpose of this element is the simple mapping of an asynchronous response to an invoice transmission. The name must be specified in the attributename
. It must be ensured that eachPassthrough
element has a unique name. -
@url
(1..1) - specifies the URL where the web service callback can be reached. This URL must be publicly accessible, but can be protected with an IP address filter onwww.e-rechnung.gv.at
and/ortest.e-rechnung.gv.at
. -
@version
(1..1) - specifies the version of the asynchronous callback to be used. Currently there is only version 1.0 of the asynchronous callback and for that you have to enter100
as value. -
@soapaction
(0..1) - if the callback web service specified in@url
requires a SOAP action, this can be specified in this attribute. By default no SOAP action is sent.
-
-
EmailSettings
(0..1) - contains settings for e-mail sending:-
AlternateResponseEmail
(0..n) - overwrites the e-mail addresses for asynchronous e-mail communication. If there is at least oneAlternateResponseEmail
element, the e-mail with the success or error message is sent to this/these e-mail address(es) and no longer to the e-mail address(es) specified in the invoice. -
AdditionalResponseEmail
(0..n) - adds additional e-mail addresses for asynchronous e-mail communication. This element is only evaluated if noAlternateResponseEmail
element is present. -
ResponseEmailCC
(0..n) - adds additional e-mail addresses as CC receivers. This element is always evaluated. -
ResponseEmailBCC
(0..n) - adds additional e-mail addresses as BCC receivers. This element is always evaluated. -
SubjectPrefix
(0..1) - adds an additional prefix to the sent e-mail and serves for better filtering of e-Rechnung.gv.at e-mails. Note: this prefix will be inserted after the default prefix[ERB]
.
-
-
TechnicalContact
(0..1) - is used to specify the e-mail address of a technical responsible person in case problems occur when calling the asynchronous web service callback. -
@test
(0..1) - is used to indicate whether the web service call is a test (valuetrue
) or a productive posting (valuefalse
). A more detailed description can be found under Test. -
@language
(0..1) - defines the language in which error messages are to be displayed. By default, the valuede
is used for German. Alternatively, onlyen
can be used for English at present.
Interface description (V1.2)
Implement this service to automatically transmit e-Invoices.
It is recommended to implement Version 2.0 of the web service since it contains more customizing options.
The invocation of the web service has to be done via https and the USP. The valid web service endpoint URL is:
https://txm.portal.at/at.gv.bmf.erb/V1
See Testing the web service on how to test the transmission via web service.
Notes:
- The https transmission to the endpoint URL requires at least TLS 1.2. SSL 3.0, TLS 1.0 and TLS 1.1 are no longer supported
- The web service endpoint URL may NOT end with a slash character ("/")
- The SOAP message must use UTF-8 or iso-8859-1 encoding
- The SOAP message must use Windows (
\r\n
) or Linux (\n
) line breaks. Mac line breaks (\r
) will lead to an error. - The SOAP message root element
Envelope
must be one long line and must not span several lines. - The WSSE
Password
element may not contain any whitespaces. (Good case:<wsse:Password>passwd<wsse:Password>
; bad case:<wsse:Password> passwd <wsse:Password>
) - The SOAP header should only contain the minimal WSSE header and no other headers (e.g. WS addressing). The WSSE header should only contain the
Security/UsernameToken
elements. - The http
Content-Type
of the transmission must betext/xml
. - The XML declaration (
<?xml version="1.0" ... ?>
) must be present. - The formatting rules of SOAP XMLs are described in the forum.
- The Base64 encoded e-Invoice representation may not contains a BOM (Byte Order Mark).
- Attachments that are not transmitted together with the e-Invoice (element
ExternalAttachment
) are specified in the WSDL file but are NOT supported. - SOAP requests larger than 15MB require the usage of HTTP chunked encoding (see Wikipedia)
- The SOAP message tester provides an interactive way to test complete SOAP messages for correctness.
- Separate URLs are required when using PVP (the Austrian governmental SSO solution).
USP web service account
For authentication, a web service account must be created for a company in the Unternehmensservice Portal. The corresponding access data must be listed in the SOAP security header in the so-called <UsernameToken>
. Detailed instructions for setting up the e-Rechnung.gv.at web service user in the USP can be found in the guideline (PDF) (which is also available under Downloads).
The official OASIS specification is available under http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0.pdf.
The bold parts are the UsernameToken
and the other necessary elements. The XML namespace must be carried over as shown and is case sensitive. <wsse:Username>
and <wsse:Password>
must contain the data in plain text which is okay since a secured communication channel is used. Your credentials are not passed to e-Rechnung.gv.at, they are solely validated by the USP and then removed from the document.
Note: all existing USP web service accounts work for both web service version 1.2 and 2.0.
Note: the credentials must only be part of the SOAP message and may NOT additionally be sent via HTTP BasicAuth.
A description on how to use WS Security Username Tokens in Java can e.g. be found at https://dzone.com/articles/jax-ws-header-part-1-client.
Asynchronous web service callback (V1.0)
You may implement this service as a server to receive an automated asynchronous response from e-Rechnung.gv.at. As soon as it is established whether the invoice is correct in terms of content or not, you will be informed by e-Rechnung.gv.at via this interface. You may use either an http
or an https
endpoint - e-Rechnung.gv.at can communicate via both protocols. When using https
a self-signed certificate is sufficient to fulfill the technical requirements. The callback on your system must use one of the following ports: 8080
, 8412
, 44300-44399
or 58700-58799
. Ports 80 and 443 are not allowed for security reasons.
Note: when using https
you must at least offer TLS 1.2. SSLv3, TLS 1.0 and TLS 1.1 are not supported.
Usage with web service 2.0: the endpoint address at which your service implementation is available must be stored in the url
attribute of the Settings/Callback
element when the invoice is submitted. The attribute version
in Element Settings/Callback
must be set. This indicates the version of the callback and currently only supports the value 100
. If one of these attributes has not been set, or if the web service call has not worked, you will be informed of this in an e-mail.
Usage with web service 1.2: the endpoint address at which your service implementation is available must be stored in the ResponseServiceURL
attribute of the Settings
element when the invoice is submitted. If one of these attributes has not been set, or if the web service call has not worked, you will be informed of this in an e-mail.
Note: this service is only available when using the web service transmission. This option is not available when delivering the e-invoice via upload, online form or Peppol.
Error messages
Since the error messages of the web service integration are sometimes very cryptic (and we unfortunately have no influence on them), here is a little help, which error can mean what (this list makes no claim to completeness):
- HTTP 302 → account does not exist/invalid user name (error message
Wrong Credentials (1)
) - HTTP 302 → password is incorrect (error message
Wrong Credentials (2)
) - HTTP 302 → the user does not have assigned the necessary rights (the check box is not set in the USP) (error message
Missing Permissions
) - HTTP 302 → HTTP 404 → account is locked since the user sent too often (4 times) an invalid password. This requires a manual interaction in the USP. See the document "Unlock a web service user in the USP" at Downloads for details.
- HTTP 412 → because of an internal error the web service call could not be handled. Please try again.
- HTTP 415 → an invalid
Content-Type
HTTP header is used. You have to usetext/xml
. - HTTP 500 → the USP web service account is missing the necessary access rights. If the test web service is targeted, the access rights must first be activated by the e-Rechnung.gv.at support before you can assign it.
- HTTP 500 → the SOAP message does not conform to the WSDL file. Try the message in the SOAP tester to check for known errors.
- HTTP 500 → the SOAP message uses invalid line breaks (Mac -
\r
) - HTTP 500 → the SOAP message uses a different character encoding than
ISO-8859-1
orUTF-8
- HTTP 500 → the root element of the SOAP message (
Envelope
) is not provided in a single line
If the check of user name and password was successful, regular SOAP-Faults with speaking error messages as they can be found in the error list are returned.