VATREFUNDUPLOAD V1.00 VAT REFUND XML UPLOAD DEVELOPER GUIDE

Document History Version

Date

Author

Description

1.00

13/09/2016

AED

Initial release

VATRefundUpload-DevGuide-v1.00.docx

Page 1 / 22

Table of Contents 1 2 3 4 5

Introduction ..................................................................................................... 3 Overview ......................................................................................................... 4 Upload process ............................................................................................... 5 XML file generation guidelines ........................................................................ 6 Validations before, during and after XML file processing ................................ 8 5.1 5.2 5.3

6

Validations before XML file processing ............................................................................ 8 Validations during XML file processing ............................................................................ 8 Validations after XML file processing ............................................................................... 9

XML schema definition.................................................................................. 11 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 6.10 6.11 6.12

Element VATRefundUpload ........................................................................................... 11 Element Technical ......................................................................................................... 12 Element Applications..................................................................................................... 12 Element Application ...................................................................................................... 13 Element PurchaseInformation ....................................................................................... 15 Element EUSupplier...................................................................................................... 16 Element Address........................................................................................................... 17 Element GoodsDescription............................................................................................ 18 Element Transaction ..................................................................................................... 19 Element Deduction........................................................................................................ 20 Element ImportInformation ............................................................................................ 21 Element Supplier .......................................................................................................... 22

VATRefundUpload-DevGuide-v1.00.docx

Page 2 / 22

1 INTRODUCTION Since the version 8.0 of the VAT Refund system, the user has the ability to upload an XML file with his refund applications instead of creating them one by one in the VAT Refund web portal. Provided that this XML file is well formed and contains sufficient data, this reduces considerably the editing time spent on the web portal. This is particularly true when many applications or many acquisitions are involved. An XML schema definition ensures that all XML files are well formed and that the data they contain is most likely to be valid in the context of the directive 2008/9/EC. It is provided along with this document as an XSD file. This document has several objectives: ·

Provide a general understanding of the XML upload process.

·

Give advice to the XML developers in order to enable them to construct VAT Refund conform XML files. Although the XML file should be generated from some enterprise system or data repository, the XML developers need to adapt their system in order to respect the structure and content required by VAT Refund.

·

Describe all the available XML elements in depth. Despite these elements being already annotated in the XSD file, the document provides more information, including technical hints and examples.

This guide does not include general knowledge about XML development or XML schema definitions (XSD), which is considered as a prerequisite to be able to build a valid XML file for VAT Refund. Related information: -

XSD file available through a link in the online user guide

-

A sample XML file, which demonstrates most of the key aspects described in this document, available through a link in the online user guide.

-

Technical information for developers of XML solutions : EN : http://www.aed.public.lu/vatrefund/doc/en/uploaddev.html FR : http://www.aed.public.lu/vatrefund/doc/fr/uploaddev.html DE : http://www.aed.public.lu/vatrefund/doc/de/uploaddev.html

-

XML upload user guide and how to get access to the XML upload function in VAT Refund : EN: http://www.aed.public.lu/vatrefund/doc/en/upload.html FR: http://www.aed.public.lu/vatrefund/doc/fr/upload.html DE: http://www.aed.public.lu/vatrefund/doc/de/upload.html

-

VAT Refund portal online help : http://www.aed.public.lu/vatrefund/doc/

VATRefundUpload-DevGuide-v1.00.docx

Page 3 / 22

2 OVERVIEW The purpose of the XML upload feature is to create and pre-fill several refund applications in one single operation. XML upload does not imply automatic submission of the uploaded refund applications. The VAT Refund user remains responsible for the uploaded applications and still has to attach the invoice or importation documents and submit the application, one by one. The main characteristics of the XML upload are: ·

Multiple applications per file are supported.

·

Applications for different taxable persons can be mixed in the same file.

·

Some information is automatically determined by the VAT Refund system during upload and has not to be included in the XML file. For instance, the user uploading the XML file sets the representative of the uploaded refund applications.

·

It integrates seamlessly with the existing online creation process: once an XML file has been successfully uploaded, the corresponding applications can be viewed and even changed on the VAT Refund web portal. The uploaded applications are created with the initial status “In preparation”.

Further editing of the applications is possible, but unnecessary, since the XML schema allows defining all the required information directly in the XML file, except application attachments i.e. scanned invoices and importation documents, which have to be attached manually to each application. Uploading a new application instead of modifying manually some minor errors in an already uploaded application is strongly discouraged. The following limitations apply: ·

It is not possible to create a corrective application via the XML upload feature. Corrections to a previously submitted application have to be created online in the VAT Refund portal, as they keep the initial application reference number (each uploaded application gets a new application number).

·

Pro-rata rate adjustments cannot be created via XML upload.

VATRefundUpload-DevGuide-v1.00.docx

Page 4 / 22

3 UPLOAD PROCESS The overall upload process is detailed hereafter: 1. An XML file is generated by using the appropriate tool (see section 4 for an explanation on XML file generation). The file must contain the applications that the user wants to create in the VAT Refund system. 2. The user logs in the VAT Refund web portal. 3. Provided that he has access to the XML upload feature, the user clicks on the “XML import” menu. The list of all XML files that have been previously uploaded appears. 4. The user clicks on the “Upload XML file” button to open the XML upload form. 5. He browses to the location where the XML file resides and selects it. Then he clicks on the “Upload” button at the bottom of the form. 6. The upload begins. Since this operation may take some time, it is performed in the background. The user has to check periodically the status of the file in the aforementioned list by refreshing the webpage. Please allow at least 10 seconds between refreshes of the webpage. 7. The final status can be one of these: “Success”, “XML error” or “Business error”. For a description of errors and the proposed corrective actions, see section 5. In the case of success, the user can review each newly created application in his dashboard of “Refund applications”, in the “In preparation” tab. Eventually sorting by creation date helps identifying the newly created applications. 8. He completes them by uploading the application attachments, if any. 9. The user submits the applications.

VATRefundUpload-DevGuide-v1.00.docx

Page 5 / 22

4 XML FILE GENERATION GUIDELINES This section gives some guidelines on how to generate an XML file for VAT Refund. Usually, the data comes from an existing system such as an accounting tool. An extension must be developed to export this data to an XML file that conforms to the XML schema definition described in this document. It is the responsibility of the developer to generate valid XML files. It is recommended to test a sufficient number of generated files before uploading them into the VAT Refund system. To do so, the developer has the choice between several XML validation tools. Some are full-featured professional XML editors and some are for free. Ideally, the developer includes final integrated validation of the generated XML file against the XSD. A “trial and error” approach is not allowed and the system will ultimately block the upload of new files or the creation of additional applications, based on the number of previously failed uploads and other criteria. A usage reliability indicator is displayed as a hint (the initial value is 100% and decreases; the upload is blocked at 0%). This document and the related XSD file include all information needed to build a valid XML file passing the upload process. Here are some other important recommendations: ·

All XML files must be encoded in UTF-8.

·

There must be only one XML root element, . Then, all data is grouped into logical elements e.g. , and . These elements may be nested, as an application contains purchases which in turn contain a supplier.

·

The order of elements is important. In particular, under each element, the elements come first, before any . Purchases and imports cannot be mixed.

·

Optional elements should be omitted if no data is available, instead of filling them with blanks.

·

The values allowed for the element are the same that are available in the drop-down list of VAT files i.e. companies that the connected user can see, in the VAT Refund portal. They are made of his own VAT files and also the VAT files he may have access to by mandate. In the last case, the user is considered to act as an agent for that specific company, and the system automatically determines which mandate is involved and retrieves all mandate-related information to perform checks on mandate validity and imposed bank account.

·

Use the provided XML schema definition extensively. It is strongly

VATRefundUpload-DevGuide-v1.00.docx

Page 6 / 22

recommended to include an automatic validation against the schema as last step in the generation process. The schema can also be used to generate safe code that maps your data to the right XML elements and attributes. For example in Java, you can use JAXB schema compiler (XJC) to generate JAXB-annotated Java classes. ·

The sample XML file, VATRefundUpload-Sample.xml, gives a good understanding of the XML structure and of the various data formats that are used. The recommended development way should take the XML schema as starting point and not to start modifying the sample XML file to meet the user’s needs.

VATRefundUpload-DevGuide-v1.00.docx

Page 7 / 22

5 VALIDATIONS

BEFORE, DURING AND AFTER

XML

FILE

PROCESSING 5.1

Validations before XML file processing

This is essentially the validation of the uploaded XML file against the XML schema presented in this document. If this check fails, the XML file is not uploaded and the reliability indicator will be decreased considerably leading to a fast blocking of the XML upload function. 5.2

Validations during XML file processing

In addition to the already mentioned XML schema validation, the following preliminary checks are done during upload of the XML file. If such an error occurs, the file is entirely refused and no refund application is created. All these errors have an impact on the reliability indicator and the upload function will be automatically blocked once the reliability indicator has dropped to zero. To avoid this, it is recommended to check the validation rules prior to generating the XML files. The following errors may occur during XML file processing: ·

File size exceeded The size of the XML file must be less than 8 Mbytes.

·

File reference duplicated The file has already been uploaded. All file references (indicated in the header of the XML file) must be unique per legal entity of the user who uploads the file. This is to ensure that the same XML file can only be uploaded once. For correcting an uploaded file, a new XML file with another reference has to be generated. The file reference is independent of the filename.

·

Access denied to taxable person The user must be allowed to create applications for all the taxable persons specified in the XML file (in the elements), either through one of his own VAT files or through a received mandate.

·

Taxable person not established The taxable person must be established in Luxembourg.

·

Currency invalid for Member State The currency specified in the element must have legal tender in the Member State of refund for the given period of refund.

·

Bank account not valid as taxable person or representative The IBAN is mandatory. Three cases can be distinguished: 1) If the user acts as taxpayer, the IBAN indicated in the XML file has to

VATRefundUpload-DevGuide-v1.00.docx

Page 8 / 22

be part of the list of bank accounts of his company profile in VAT Refund with the type 'Own account'. 2) If the user acts as representative and the bank account is not imposed by the mandate, the IBAN indicated in the XML file has to be part of the list of bank accounts indicated in his company profile with the type 'Own account' (if the refund is to be paid to the agent's account) or 'Account of the principal' (if the refund is to be paid to the client). 3) If the user acts as representative and the bank account is imposed by the mandate, an IBAN has to be indicated anyway, although the IBAN imposed by the mandate will prevail. The IBAN indicated in the XML file will only be used if the mandate has been changed until upload of the XML file in order to fit in one of the previous cases. It is recommended to use the IBAN imposed by the mandate or an IBAN indicated in the representative's company profile of the type 'Own account' or 'Account of the principal'. ·

Limit of applications exceeded The administration does not want the user to create too many refund applications without having the intention to submit these. So, the number of refund applications created by a user is limited. If after preloading a refund application, the user finds additional errors, it is recommended to manually correct these through the portal instead of generating a new XML file to upload. The administration does not provide any information on the maximum number except that it is high enough to allow normal and reasonable use to any established taxable person and to any representative.

The user has to check the error reason in the list of uploads and correct the XML file accordingly. A newly generated XML file containing a different file reference can be uploaded after correction. 5.3

Validations after XML file processing

Even if the XML file has been uploaded successfully, it does not guarantee that the applications can be submitted, as the VAT Refund business rules have to be respected as well. The following additional validations are performed by VAT Refund during submission of the application and are not covered by the XML schema definition. Most of these validation rules are common sense, but they need to be respected in order to be able to submit the application. The following validation errors may occur after successful upload of an XML file. Validation rules when submitting the applications: Member State of refund - the state is not member of the European Union during the whole period. [AV1050] Refund period - the end date is before the begin date. [AV1120]

VATRefundUpload-DevGuide-v1.00.docx

Page 9 / 22

Refund period - the period cannot exceed one calendar year. [AV1125] Currency - the currency is not in use by the Member State of refund during the whole period. If the Member State changed the currency during the refund period, you have to split the application. [AV1350]

Validation rules concerning the acquisition/import: Reference number - the format of the VAT identification number is invalid [TV0080] (Please note that all identification numbers in the XML file have a mandatory "issuedBy" attribute to indicate the country issuing the identification number. Thus, the number itself must not contain the country code.) Reference number - the reference number of the supplier is mandatory for a detailed invoice [TV1330] Reference number - the VAT identification number does not belong to the Member State of refund. [TV0090] (this rule applies only to non-simplified invoices with suppliers identified by a VAT identification number) Acquisitions - some purchases from the same supplier have the same invoice number. Merge all purchases from a supplier with the same number and indicate all concerned goods codes. [TV1225] (this rule applies only to suppliers with VAT identification numbers) Invoice/import date - the date is in the future. [TV1170] Invoice/import date - the date is situated after the refund period or outside the civil year of the refund period. [TV0050] Invoice/import date - the refund country is not a Member State at this date. [TV0010] Country - for a simplified invoice, the supplier's country has to be the Member State of refund. [TV0070] Taxable amount - the amount is mandatory and the format must be valid. [TV0120] VAT amount - the amount is mandatory and the format must be valid. [TV0110] VAT amount - the absolute value cannot be greater than the taxable amount. [TV0150] Deductible VAT amount - the absolute value cannot be greater than the VAT amount. [TV0140] Nature of the goods and services supplied - the list must not contain duplicate codes. [TV0180] Nature of the goods and services supplied - for Goods code "10" without sub-code, the description and language are mandatory. [TV1210]

VATRefundUpload-DevGuide-v1.00.docx

Page 10 / 22

6 XML SCHEMA DEFINITION This description of the XML schema does not necessarily repeat the format and limitations of each field indicated already in the XSD file. 6.1

Element VATRefundUpload

The XML root element is a grouping element for: ·

Global information about the entire XML file;

·

Technical information about the software used to generate the XML file;

·

All the refund applications to create using this XML file.

Of all file-related elements, the element is certainly the most important. It is mandatory, must be unique and must not contain an empty string. It serves two different purposes: 1. On the VAT Refund side, it is used to uniquely identify an uploaded file; 2. On the user side, it may be used as an alternative identifier to the file name and also to convey extra information about the file e.g. its creation date. For this reason, no particular format is imposed by the XML schema. The only restrictions are that it must be less than 30 characters and it must not contain special characters. Blank spaces (‘ ‘) are allowed. The element must correspond to the version of the XML schema. It is currently fixed to ‘1.00’. The element is described in the next section.

VATRefundUpload-DevGuide-v1.00.docx

Page 11 / 22

6.2

Element Technical

The element provides useful information about the software used to generate the XML files: the software name, vendor and version as well as contact information, basically the name and email of the person (or company) that provides support for the software. It is important to understand that this contact is for technical support for XML-related issues only and not for the VAT Refund applications themselves. If an in-house software is used instead of a commercial vendor’s, these elements have to be filled in as well with sufficient detail to be able to know how the XML file has been generated and who to contact. 6.3

Element Applications

The element is a grouping element for all VAT Refund applications. It must appear only once. Nested inside it, a sequence of elements defines the applications to create.

VATRefundUpload-DevGuide-v1.00.docx

Page 12 / 22

6.4

Element Application

The first element under an element is , which contains the taxable person’s VAT number. This is the numeric part only i.e. without the leading ISO 3166 alpha 2 country code. The country code is required however, in the "issuedBy" attribute. VATRefundUpload-DevGuide-v1.00.docx

Page 13 / 22

Since it is always a Luxembourg VAT number, the format of the element is restricted to 8 digits and the value of the attribute is fixed to ‘LU’. The second element is the , which is made of two subelements: ·

: start date of the refund period, in the format YYYY-MM-DD.

·

: end date of the refund period, in the same format.

The third element is the , which can be any Member State of the European Union except ‘LU’. Then, the indicates the currency to use for all amounts. Only one currency per application is allowed. The next element is , which identifies the bank account that will be used to receive payment of the refunded amount (if eligible). The right IBAN has to be proposed depending on the case as described in chapter 5.2-Validations during XML file processing. Finally, the purchases and imports are listed in sequence at the end of the element. First are all the purchases, then all the imports. It is worth noting, that there is no grouping element such as : the describing the first purchase immediately follows the element. If there is no purchase, an follows instead. An XML file without any nor is valid, although not useful. Such an XML file would create an application without purchases or imports.

VATRefundUpload-DevGuide-v1.00.docx

Page 14 / 22

6.5

Element PurchaseInformation

The invoice is either simplified or not (same meaning as in the VAT Refund portal – there are also business constraints linked to a simplified invoice which are out of scope of this document). If it is, the element must contain ‘true’. The element is mandatory and must explicitly contain either ‘true’ or ‘false’. There is no default value. The provided value has implications on other elements: for a simplified invoice, the supplier's country () has to be equal to the Member State of refund and the reference number of the supplier () is not mandatory. For a non-simplified invoice, the reference number of the supplier () is mandatory. Following the element is the VATRefundUpload-DevGuide-v1.00.docx

Page 15 / 22

element, which is mandatory. Then, the element contains the date of the invoice, in the format YYYY-MM-DD. 6.6

Element EUSupplier

An contains all the information needed to know who the supplier of the purchased goods and services is. First, its (i.e. its identification number) may be provided. This element is optional if the invoice is simplified, otherwise it is mandatory. The supplier is usually identified by its VAT identification number (). Only for Germany, the supplier may alternatively be identified by its national tax identification number (), in case the intra-community VAT identification number of the supplier is not known. Please note that all identification numbers have a mandatory "issuedBy" attribute to indicate the country issuing the identification number. Thus, the number itself does not contain the country code, whereas on the VAT Refund portal, the country and the number are concatenated in a single field that represents the entire identification number, for the user’s ease of data input. The name of the supplier follows in the element being a free text. Then the address completes the information about the supplier. The is a complex element (i.e. made of several sub-elements) and is described in the next section. Also note that suppliers do not need to be created in the user’s address book in VATRefundUpload-DevGuide-v1.00.docx

Page 16 / 22

order to be used in an uploaded XML file. Conversely, the suppliers used in XML files are not added automatically to the user's address book. The address book is only useful to create refund applications manually. 6.7 Element Address

The element contains a sequence of text sub-elements: ·

The (optional);

·

The (optional);

·

The (optional);

·

The (mandatory);

·

The (optional);

·

The (mandatory). For a simplified invoice, the country of the supplier’s address must be equal to the application’s refund country.

VATRefundUpload-DevGuide-v1.00.docx

Page 17 / 22

6.8 Element GoodsDescription

After the element, the description of the purchased goods and services must be provided. This is the purpose of the element, which describes the goods. As there may be different kinds of goods grouped in one purchase, the element may be repeated as many times as needed. The goods code is mandatory. The element contains the standardised code identifying the goods uniquely. The allowed codes are exactly the same as in the drop-down list of goods on the VAT Refund portal. They are also listed in the XML schema, as shown in this excerpt: Code that identifies the type of goods and services uniquely. Valid entries are: - 1 -- Fuel - 1.1 -- Fuel for means of transport with a mass greater than 3 500 kg, other than means of transport for paying passengers - 1.1.1 -- Petrol - 1.1.2 -- Diesel - 1.1.3 -- LPG - 1.1.4 -- Natural Gas - 1.1.5 -- Bio fuel [...]

Despite the codes being numbers (optionally followed by other numbers called VATRefundUpload-DevGuide-v1.00.docx

Page 18 / 22

sub-codes, separated by dots ‘.’), the format of the element is a string. Some controls apply: 1. The code must be valid i.e. equal to one of the codes defined in the XML schema. 2. All goods codes may be extended by a free-text description (). For code ‘10’ (without sub-code), this description must be provided. When the element is provided, it must be qualified with a "language" attribute containing the standard code of an official language in the EU. The list of valid language codes is also specified in the XML schema. 3. A goods code may appear only once inside a purchase (or an import).(An XML with duplicate goods codes can be uploaded, but the applications cannot be submitted in the VAT refund portal – see chapter 5.3-Validations after XML file processing, rule TV0180). 6.9

Element Transaction

The element contains information about the transaction i.e. the amounts that have been effectively paid: ·

The specified on the invoice (or on the importation document in the case of imports) is the amount charged by the supplier of the goods excluding VAT, also known as the net price;

·

The , which is the amount of VAT paid by the customer and added to the taxable amount to make up the gross price.

As for all monetary amounts, their value must be a decimal number with up to 2 digits in the fractional part. The decimal separator must be a dot (“.”). The currency is not specified per purchase, because it is implicit: it is indeed the same as the one provided in the element. (All amounts of an application have to be of the same currency – the VAT Refund portal online help explains how to treat currency changes during the refund period.)

VATRefundUpload-DevGuide-v1.00.docx

Page 19 / 22

6.10 Element Deduction

The element contains information about the deductible VAT amount claimed for refund. ·

The element (mandatory) fixes the ratio between the turnover subject to VAT and the global turnover. It can be an integer value between 1 and 100. A value of 0 is not allowed.

·

The element itself (mandatory), which is usually equal to the formula: × 100 It is important to remember that the deductible VAT amount is the VAT amount after the deductible proportion rate and other legal constraints have been applied. In most cases, the deductible VAT amount is equal to the VAT amount on the purchase, except where only part of the goods purchased is deductible. In the latter case, the VAT amount claimed cannot exceed the deductible part. Detailed information about the deductible proportion rate is available in the VAT Refund portal online help.

VATRefundUpload-DevGuide-v1.00.docx

Page 20 / 22

6.11 Element ImportInformation

The element is very similar to the element. Only the differences will be explained below. An import can be identified either by a reference number or other reference information, depending on the importation document. If a reference number is present, it must be enclosed in a element, which is limited in size (18 characters) and cannot contain special characters. Otherwise, a element must be provided instead, which is less restrictive since it allows up to 255 characters. The element represents the date specified on the importation document. A element replaces the element used for purchases and is described in the next section. All other elements (, VATRefundUpload-DevGuide-v1.00.docx

Page 21 / 22

and ) are the same. 6.12 Element Supplier

The element is a simplified version of the element since it contains only two sub-elements, both mandatory: ·

The element, which contains the supplier’s name (free text);

·

The element, which has already been described in section 6.7.

There is no supplier identification number as for purchases.

***

VATRefundUpload-DevGuide-v1.00.docx

Page 22 / 22