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.

erb-in-invoice-201.wsdl

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 be text/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 attribute name. It must be ensured that each Passthrough 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 on www.e-rechnung.gv.at and/or test.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 enter 100 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 one AlternateResponseEmail 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 no AlternateResponseEmail 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 (value true) or a productive posting (value false). 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 value de is used for German. Alternatively, only en 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.

erb-in-invoice-122.wsdl

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 be text/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.

Web service V2.0
Web service V1.2

<?xml version="1.0" encoding="utf-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<env:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>your_username</wsse:Username>
<wsse:Password>your_password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</env:Header>
<env:Body>
<deliverInvoiceInvoiceInput xmlns="http://erb.eproc.brz.gv.at/ws/invoicedelivery/201306/">
<!-- The base64 encoded e-Invoice UTF-8 as the original character set: -->
<Invoice encoding="UTF-8">PD94bWwgd.....WNlPg0K</Invoice>
<!-- Optional base64 encoded attachment test.pdf: -->
<EmbeddedAttachment name="test.pdf">JVBERk....lbHQ=</EmbeddedAttachment>
<!-- test="true" means the "test flag" is set: -->
<Settings test="true"/>
</deliverInvoiceInvoiceInput>
</env:Body>
</env:Envelope>

<?xml version="1.0" encoding="utf-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<env:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>your_username</wsse:Username>
<wsse:Password>your_password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</env:Header>
<env:Body>
<uploadDocument xmlns="http://erb.eproc.brz.gv.at/ws/documentupload/20121205/">
<!-- The base64 encoded e-Invoice UTF-8 as the original character set: -->
<Document encoding="UTF-8">PD94bWwgd.....WNlPg0K</Document>
<!-- Optional base64 encoded attachment test.pdf: -->
<Attachment name="test.pdf">
<Content>JVBERk....lbHQ=</Content>
</Attachment>
<!-- test="true" means the "test flag" is set: -->
<Settings test="true"/>
</uploadDocument>
</env:Body>
</env:Envelope>

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.

erb-out-invoice-callback-100.wsdl

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 use text/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 or UTF-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.