Skip to main content

๐Ÿ‡ฎ๐Ÿ‡น Italy

This document describes all necessary configuration for a compliant setup in Italy.

Local mode support

Local mode is currently not supported. Activating local mode is done at your discretion and risk. We strongly recommend conducting thorough testing of local mode before going live to ensure it aligns with your expectations.

If you require support for local mode in compliance countries, please submit a JIRA development ticket, namely a request for change.

Attestation required before go-live in Italy

An attestation by a person (e.g. Auditing firm) duly registered in the Register of Auditors kept by the Ministry of Economy and Finance is required before go live in Italy. We recommend Deloitte for this (fees apply). The attestation process usually takes 3 months.

For more information regarding the attestation please check the following attachments:

Introductionโ€‹

Here are some concepts you need to familiarize yourself with before we go deeper into Italy's fiscalization:

  • Server RT: Server RT is a hardware device that registers all transactions conducted and reports it to local fiscal authorities. Therefore, all in store transactions are tracked by what we call Server RT, and accordingly each station is synced to that server. More about server RT can be found below.
  • Sistema Di Interscambio (SDI): Invoices are issued by the e-invoicing portal of Italy called SDI. This applies to all orders whether performed in-store or online.
  • Lottery: A feature introduced by Italian authorities to combat money laundry and create an incentive for use of a digital payment type.

Here is an overview of how the architecture and setup in Italy looks like:


About Server RTโ€‹

The Server RT records all the sales in the POS and transmits the sales data to the Italian Tax Authorities. There is one Server RT per store.

Every fiscal station that is created in EVA for that store transmits the sales data to the server RT. The receipt however are printed on non-fiscal printers, which often are the EPSON TM-30.

After day closing, the server RT prepares the file and submits the information to tax authorities. Worth mentioning that there is a grace period of 12 days in case of any errors during transmission from Server RT to tax authorities. In other words, this means that sales have to be reported to the tax authorities within 12 days of it being registered. In severe instances a manual option to copy the information from Server RT (sealed) on an external memory drive and then further upload it on the Invoices and Fees portal of the Italian tax authorities is always there.

Lastly, the Server RT is reachable via itโ€™s IP-address at any moment. When accessing the Server RT via the IP-address the following web interface example is shown. Within you'll be able to spot receipts, logs and transmitted files.


About SDIโ€‹

The Sistema Di Interscambio (SDI) is the electronic invoicing portal of Italy. It is mandatory to send all B2B invoices to the SDI. This is optional for consumer invoices.

The SDI instance is owned and maintained by us i.e. only accessible by New Black.

However, since our registered SDI is used by multiple customers, we've set up an SDI router that uses SDI transmitter codes. Those codes are unique and correspond with your VAT number. This eventually allows for a multi customer set up and therefore attainable via a setting for each customer. With this in-place any notifications from the SDI will be sent to the corresponding EVA customer environment.

However, for this to work out, we require a couple of things to be done on your side:

  • An API token (refer to the configurations section for steps to follow);
  • The VAT number of your Italian organization unit in the value of the Auditing:Italy:SDIService:TransmitterVatCode setting (more information on settings can be found here).

SDI invoicesโ€‹

  • An SDI reference is added on all PDF invoices.
  • Invoices are emailed to the customer whether the underlying transaction was performed in-store or online. Make sure the setting AutoSendCertifiedInvoice is set with a value true.
  • A receipt is automatically printed on endless aisle orders.
  • The "Documento Commerciale" (receipt) print is mandatory for carry out orders (POS print receipts behave accordingly regardless of what action the user takes on the print function prompt).
Configuration required

An extra step of configuration is required to activate the lottery feature. More on this can be found here.

About Lottery featureโ€‹

Italian residents can participate in the Italian Lottery with their personal tax code. The lottery applies only to digital payments and are for orders above 1 euro.

When the Auditing:Provider setting is set with a value ITALY a field where the user can input a lottery number would be made available on our apps (applies to card payments only).

We have 2 services pertaining to the lottery feature:

  • GetLotteryNumber

    • Accepts an OrderID and will return the current lottery number (if any).
  • SetLotteryNumber

    • Accepts both OrderID and a LotteryNumber
    • This service will also validate your input. The service will โ€œfailโ€ with an error based on applied validation rules (example: lottery numbers in Italy are a maximum of 8 characters long, this will be validated.)
Configuration required

An extra step of configuration is required to activate the lottery feature. More on this can be found here.

Configurationโ€‹

In order to configure your store in Italy to be compliant, the following SDI API configurations are required:

SDI API KEYโ€‹

This is with regard to the explanation provided in the About SDI section.

The following steps will help you create the required API key:

Step 1โ€‹

Add a role and give it the functionalities Login and ExternalLogin only. Call the role whatever you want.

Step 2โ€‹

Head over to the API users chapter and Create API user with the same role name (recommended). Then under Permissions, assign the role you've just created in Step 1, and tag the Italian Organization unit(s).

Step 3โ€‹

Create API key, and once again select the Italian Organization unit(s), slide the Permanent key radio button On, then Save. Once that's done, a notification will be prompted stating 'Generated API key copied to the clipboard. Please store it in a safe location, as it cannot be retrieved later on.' i.e. don't go around doing something else now since the key cannot be retrieved later unless you repeat step 3 again.

Step 4โ€‹

Submit a ticket (Help & implementation) to support with that API key for us to do our part of updating the SDI router.

Settingsโ€‹

All settings below should be set on the most convenient level possible. In other words, if your organization structure has a country organization which houses all Italian stores, then that's where they should go.

SettingValueOrganization unitDescription
Auditing:ProviderITALYITALY - On Country levelSets the certified aspects
UseInvoiceOutputFacadetrueRoot level or container levelAttaches the Certified Invoice PDF when emailing the Invoice from POS &/or Companion App. This setting enables the use of the CertifiedInvoice stencil with destination Mail
Auditing:UseInvoiceCloningtrueRoot level or container levelUsed to toggle automatic creation of clones, for unique sequence numbers, on and off (experimental)
Auditing:DailyConsolidation:MailToYour email address input hereContainer or store levelThe email address where the consolidation report is to be sent to.
Auditing:Italy:SDIService:CertificateBlobIDThis will be provided by usContainer level (Italy)-
Auditing:Italy:SDIService:CertificatePasswordThis will be provided by usContainer level (Italy)-
Auditing:Italy:SDIService:TransmitterCountryCodeITContainer level (Italy)The country code that will be transmitted to the SDI.
Auditing:Italy:SDIService:TransmitterVatCodeYour organizations VAT number (Example: 09599600963)Container level (Italy)The VAT code of the company which submits the invoice data to the SDI. This is the VAT number of your organization.
Auditing:Italy:SDIService:UrlInsert URL of the SDIContainer level (Italy)The URL of the SDI.
Auditing:Italy:SDIService:ErrorHandlerEmailAddressxContainer level (Italy)The email address that will receive errors from the SDI if errors occur.
Auditing:Italy:RtServer:Urlhttps:// (insert IP address)Store levelThe IP Address of the in store server RT. Please include https://
Auditing:Italy:RtServer:UsernameYour server RT username hereStore levelThe username of the server RT. *Most of the time this would be Epson.
Auditing:Italy:RtServer:PasswordYour server RT password hereStore levelThe password of the in store Server RT
Auditing:Italy:UseSentineltrueStore levelThis is Live Guard specific. More about Live Guard here
Auditing:EnforceTransactionValidationtrueContainer level (Italy)Make sure that the auditing configuration is correctly setup before allowing transactions.
Auditing:InvoiceDeliveryInStoreDirectlytrue-This will prompt all orders with at least one delivery line to directly send the customer an invoice after the payment has been done. The invoice will then be sent to the RT server and exported to the SDI directly afterwards.
Checking missed configuration(s)

Once you're done with all configuration steps. Make sure to run the service: AuditingValidateConfiguration which should return any step(s) that you may have missed or possibly undocumented.

Async Signingโ€‹

note

This is an experimental setting that should only be used in cases where the RT servers are hosted outside the physical stores in a server farm, cannot be fixed in the short term, and upon New Black's advisory. Ensure a consistently working connection to the RT server at all times. If not handled correctly, there are risks of being non-compliant.

Set UseAsyncSigning to true. This takes place on a store level .

This setting addresses and comes into effect in scenarios where calls to the RT server fail. Adding this setting allows for performing asynchronous calls to the RT server during the checkout process. Note: If call(s) to the RT server still fails, a reattempt will be done with the following intervals: 1 minute, then after 2 minutes, then after 3 minutes, then after 4 minutes, then after 5 minutes, then after 10 minutes, and so on, up to 25 times. i.e. attempts will be made to perform the synchronization for approximately 2 hours.

If this still fails, the call will land in the error queue, and you must republish the message manually from there. The type of this error in the error queue is called AsyncSigningMessage. Further, with this setting enabled, the auto-print functionality is disabled, allowing for more time to attempt connecting to the RT server before a print job request is attempted. We have also added monitors on our side in case any calls continue to fail.

The sales data generated by this setting will not include RT data. Instead, it will display the EVA invoice number, which will serve as a reference back to the RT number eventually. However, the EVA invoice number alone is not compliant; manual matching is required.

Companyโ€‹

When configuring your Italian organization unit(s), a company needs to be attached. If there isnโ€™t an Italian company present yet, a new one can be created within Admin Suite under the Companies chapter. The following fields need be filled:

  • Name
  • VatNumber - Don't add the "IT" prefix
  • RegistrationNumber
  • Address (VisitorAddress)
    • Street
    • HouseNumber
    • ZipCode
    • City
    • CountryID

Organization unitโ€‹

Once a company is in place, you need to attach it to an organization unit(s).

Make sure the following fields are filled when creating an organization unit:

  • Name
  • BackendID (store number)
  • Address
    • Street
    • ZipCode
    • City
    • CountryID
  • CompanyID
note

It is crucial that you have the CompanyID field filled when creating the organization unit. You can retrieve this ID from the Italian company you created/have. This is the legal entity under which this OU/store is operating and will be referred to when filling in the details on the invoices and receipts.

Setting up stationsโ€‹

Requirements prior to setting up stations in EVA
  • Ensure that your Server RT setup is already in place otherwsie, any created stations will not be synced to the Server RT.
  • Ensure that your Watchtower is up and running and that all auditing settings are configured otherwise, your stations would not be synced to the Server RT.

You can find steps on adding a new station here.

When creating a station, make sure the following fields are filled in:

  • Station name.
  • The checkmark This station is a fiscal station and will be used for transactions needs to be checked.
  • FiscalSystemID
    • This needs to be exactly 8 characters where the last 4 characters need to be numbers.
    • Donโ€™t use any special characters in the FiscalSystemID.
mandatory configs
  • All payment types must have a category, otherwise the payment can't be correctly mapped, and Ship Orders would fail.
  • In Italy printing receipts is mandatory hence, please ensure that a thermal printer station is configured and properly functioning to avoid any downtime.

Further, stations are known as Tills in the Server RT, and Tills can only be created or deleted from the Server RT. Once created, updating is not possible. Therefore, if any changes need to be made on an existing Till, please delete it and re-add it with the desired changes.

Tasksโ€‹

Reconciliation reportโ€‹


In order to create a reconciliation report and spot any differences between the reported server RT turnover and EVA's reported turnover at financial period closure, the following task can be set up from Admin 1.0 under Management โ†’ Tasks:

The task is called system:DailyConsolidationReportTask, once set up, the task will run every day at 23:55. It will consolidate all ledgers of DailyTotalsConsolidation and place them in an Excel called report.xslx and email that file to you.

The report will fetch all the information from the store and split that information into three types of transactions that are known to Server RT. Those are:

  • Sales
  • Refunds
  • Void

Reports are attached to the financial period in Admin Suite for the sake of historical reference. As soon as EVA detects a difference between EVA's reported turnover and the Server RT, a record of that would be included in the emailed report.

The email will be sent to the address specified in the setting called Auditing:DailyConsolidation:MailTo. You will also need SMTP settings, and a Stencil with the following configuration:

  • Type: Template
  • Organization: Leave empty
  • Name: DailyConsilidation
  • Country: None
  • Language: Empty
  • Layout: None
  • Destination: Email
  • Content: As you wish

Reboot RT server taskโ€‹


Recommendation

Configuring this task is recommended if you are using a server RT farm. The reboot is a recommendation from Epson to overcome a memory issue that could cause in-operable RT servers.

The task is called: EVA.Auditing.Tasks.DailyRtServerRebootTask and since the Server RT does not transmit data between 3am and 5am, it is recommended to schedule the task to run via a Cron job between those hours. For example at 4 am with the corresponding cron job: 0 3 * * *

The task is scheduled using an organization unit ID. This could be either the ID of the container OU or the individual store OU. If a container is chosen, the reboot will be done for each individual OU store within. Further, if for some reason one stores fails to reboot, the reboot task for other OU's will not be impacted.

Starting task manually

It is possible to start the task manually if needed. This can be done by navigating to the Scheduled tasks chapter and clicking the Execute button of the task itself.

Checkout optionsโ€‹

When it comes to lottery and SDI invoices, a checkout configuration is required in order to have your frontend App(s) display the respective tiles during checkout.

In the Checkout options chapter of Admin Suite, a default checkout option called Italy needs to be activated.


Click the Italy checkout option, edit the field Organization unit set by specifying your Italian container OU or a single OU. The choice here is based on your organization structure setup for Italy.


After clicking Update, you'll now see two new tiles on your frontend App(s) namely, Lottery number and Electronic invoice.

Here is how it looks like on POS:

IPad Pro screen

Auditing Validate Configuration error(s)

Not performing this checkout option configuration will result in a thrown error when running the AuditingValidateConfiguration service.


Instant lottery code featureโ€‹

Server RT firmware update required

In order to use this feature, the server RT firmware must first be updated to version 5 or higher. The transaction flow will break if this lottery feature is turned on without being on the specified minimum version requirement.

To encourage the lottery initiative, the Italian authorities have launched a feature where an instant lottery code is generated to the beneficiary/customer without the prerequisite requirement of providing one at time of purchase. In such instance, the lottery code is generated in the form of a QR-code and is printed on the customer receipt itself. The customer can then use the App provided by the Italian tax authorities to scan the QR-code and check the draw results.

To start using this feature set the setting Auditing:Italy:RtServer:UseNewLotterySystem to true (default value is false) on organization unit or container level (as applicable to your setup).

Eligibility

The lottery initiative applies only to orders above 1 euro, paid using a digital payment method i.e. no changes to the existing eligibility terms.

Stencil for Certified invoicesโ€‹

For configuration and more details about Certified Invoices please refer to the general concepts section under Certified invoice stencil for thermal &/or PDF . A separate stencil is required to set up the email in which a certified invoice would be attached to. Configurations for such stencil can be found under Email invoice stencil.

Sample PDF and thermal receipts

Endless Aisleโ€‹

Endless Aisle transactions conducted via EVA are compliant in Italy. The flow is slightly different depending on whether the underlying Endless Aisle transaction being performed is B2C or B2B.

Invoice chainsโ€‹

With Italian compliancy configurations, EVA will always issue a receipt. Next to that, an invoice PDF will also be issued, but only in certain cases. Those cases are as follows:

Further, to ensure having separate invoice chains, the issued receipts and invoices (if applicable) will have a dedicated chronological invoice number, one that is on store level.

B2C Customer (No Fiscal ID)โ€‹


When a B2C customer is added to the order and the transaction is Endless Aisle, a Documento Commerciale (thermal receipt) is issued from the thermal printer and the transaction is registered on the stores Server RT.

If the products cannot be fulfilled by the warehouse, a credit note will be issued. This will be in PDF format and will be emailed to the customer. The credit note will then be registered on the same server RT as the one where the Endless Aisle sales was made from. The Server RT reference will be displayed at the bottom of the credit note.

B2C Customer (with Fiscal ID)โ€‹


When a B2C customer with a Fiscal ID is added to the order and the transaction is Endless Aisle, a Documento Commerciale (thermal receipt) is issued from the thermal printer and the transaction is registered on the stores Server RT. Next to the thermal receipt an invoice is issued to the SDI. The SDI invoice will contain a reference to the thermal receipt to avoid any double invoicing instances.

If the products can't be fulfilled by the warehouse, a credit note will be issued. This will be in PDF format and will be emailed to the customer. The credit note will then be registered on the same server RT as the one where the Endless Aisle sales was made from. The Server RT reference will be displayed at the bottom of the credit note.

The credit note will also be sent to the SDI to credit the original invoice, and once again will contain the same reference to the receipt to avoid any double invoicing instances.

B2B customer (with VAT)โ€‹


When a B2B customer (with VAT) is added to the order, and the transaction is Endless Aisle, a Documento Commerciale (thermal receipt) is issued from the thermal printer and the transaction is registered on the stores Server RT. Next to the thermal receipt an invoice is issued to the SDI. The SDI invoice will contain a reference to the thermal receipt to avoid any double invoicing instances.

If the products can't be fulfilled by the warehouse, a credit note will be issued. This will be in PDF format and will be emailed to the customer. The credit note will then be registered on the same server RT as the one where the Endless Aisle sales was made from. The Server RT reference will be displayed at the bottom of the credit note.

The credit note will also be sent to the SDI to credit the original invoice, and once again will contain the same reference to the receipt to avoid any double invoicing instances.