Your Page Title
English (United States)
Community

Articles in this section

Italy

Avatar
Konstantin Teufel
  • Updated
  • ~ minute read

General Fiscalization Information Italy

Scontrino Elettronico activation

To activate Scontrino Elettronico:

  1. Go to Hotel settings → Finance → Fiscalization settings.

    The Italy configuration card appears with an Enable fiscalization button.

    Fiscalization settings screen

    Click Enable fiscalization.

  2. The Tax credentials Scontrino form expands with fields for Username, Password, and PIN. It also shows read-only company information from your property settings.

    Tax credentials Scontrino form

  3. Enter your Tax credentials Scontrino:

    • User name — your Fisconline username
    • Password — your Fisconline password provided by the fiscal authority
    • PIN — your Fisconline PIN. It must be exactly 10 digits.
    Tax credentials entry form

  4. Review the Company information section.

    This data comes from your property settings and cannot be changed here. If anything is wrong, update it in Property settings before you continue.

  5. Click Activate fiscalization.

    A confirmation dialog appears. It warns that enabling fiscalization will start sending all new invoices to the Italian tax authorities. This may have financial or legal implications. Changing this setting later will also affect invoice reporting.

Activate fiscalization confirmation dialog

Click Activate fiscalization in the dialog to confirm.

Scontrino Elettronico credentials

To update your tax credentials after activation, go to Hotel settings → Finance → Fiscalization settings.

The Tax credentials Scontrino section shows your current credentials in masked form. Replace them with the new values and click Update credentials.

Update Scontrino credentials

Note: Your Fisconline password expires every 3 months. When you receive a new password from the fiscal authority, update it here. You can reset your password at the Fisconline portal.

Tax invoicing

Reporting transactions to the government has been required since January 2019 for:

  • B2B
  • B2C
  • B2G

Electronic invoice

The invoice flow works as follows:

  • Invoice is created.
Invoice creation
  • Select an invoice language.
Invoice language selection
  • Invoice is pending signature.
Invoice pending signature

Apaleo uses the Fonoa e-invoicing service to send each invoice to the SDI platform. The invoice lifecycle is:

  • Pending
  • Signed
  • Pending
  • Rendered

When the process finishes, the Apaleo UI shows the rendered invoice PDF.

Rendered invoice PDF

Scenarios of failed invoice

  • Invoice fails during signing

    • Pending
    • SigningFailed

    Note: There can be many different reasons for a signing failure. To see the exact reason for an invoice, go to the Fonoa Dashboard and check the internal user guide for more details.

  • Invoice fails during rendering
    • Pending
    • Signed
    • Pending
    • RenderingFailed

Receipts

When a Scontrino Elettronico is issued, the following file is rendered.

Receipt example 1
Receipt example 2
Receipt example 3

Retry mechanism

Sometimes an invoice can fail in Apaleo, but the tax authority still registers it with a specific number.

Invoice retry mechanism example

This can happen when the tax authority accepts the transaction but finds an error in the billing details, for example an incorrect Tax ID or Scontrino Elettronico value.

In this case, the next invoice retry uses the number already assigned by the tax authority portal, for example 00002666/A.

The result of a retry from the same folio looks like this:

Retry result from same folio

The invoice number stays the same as the first attempt. Because of this, the client should expect only one invoice in the tax authority portal.

Note: This is an automated process. Apaleo identifies that an invoice must be retried and handles it in the background. The user is not notified.

Country specific fields - Folio and Company

On the folio level, the following fields are relevant:

  • Codice Fiscale

    • Applies to both guests and companies.
    • This field validates the format, so only correctly formatted values are accepted.
    • Examples:

    Codice fiscale with wrong format

    Codice fiscale wrong format

    Codice fiscale with correct format

    Codice fiscale correct format

    Note: Codice Fiscale is not mandatory when Scontrino Elettronico is used. In the API, Codice Fiscale is called Personal Tax ID.

  • Codice Destinatario

    • Applies to companies only.
    • For companies with an Italian address, Codice Destinatario is optional.
    • The format is not validated.
    • The invoice can still fail if the value is wrong.
    • Back-end handling works as follows:
      • B2B invoice and company is non-Italian
        • Codice Destinatario is sent as XXXXXXX.
      • B2B invoice and company is Italian
        • When Codice Destinatario is provided:
          • It is sent with the value from the additionalTaxId field.
        • When Codice Destinatario is not provided:
          • It is sent as 0000000.
    Codice Destinatario example

Codice Destinatario exists on two levels:

  • Folio
  • Company

Deposit Flow

Basic flow of events

  • A reservation with a future arrival date exists in Confirmed status.
Confirmed reservation
Reservation details
  • There is a payment posted in advance.
Advance payment
  • This logic applies when the reservation arrival date is from the next day onward, except when arrival and departure are in two different months.
  • Transactions are read from the folio.
  • GET /finance/v1/folios/{id}
  • Sum all transaction gross amounts by VAT type, for example:
    • 25% — 850 EUR
    • 5% — 150 EUR
    • 0% — 30 EUR
  • Check the paid prepayment amount and calculate the percentage of the paid amount for all VAT types except 0% and Without.
    • Total amount = 1000
    • 500 / 1000 = 50%
  • Calculate this percentage for each VAT type:
    • 25% - 850 × 50% = 425
    • 5% - 150 × 50% = 75
  • A new Folio #2 is created with the same data as Folio #1.
New folio created
  • The payment is automatically moved from Folio #1 to Folio #2.
Payment moved to new folio
  • Post the calculated deposit charges using the sub-account created for deposit charges.
Deposit charges posted
{
  "id": "HRPRP-DEP5",
  "propertyId": "HRPRP",
  "code": "DEP5",
  "name": "Deposit 5%",
  "type": "Other"
},
{
  "id": "HRPRP-DEP25",
  "propertyId": "HRPRP",
  "code": "DEP25",
  "name": "Deposit 25%",
  "type": "Other"
},
{
  "id": "HRPRP-DEPCR",
  "propertyId": "HRPRP",
  "code": "DEPCR",
  "name": "Deposit Credit",
  "type": "Other"
}
  • A deposit invoice is created from Folio #2.
Deposit invoice created
Deposit invoice details
  • When the invoice is generated, a Deposit Credit transaction is posted to offset the paid deposit for the total gross amount.
{
  "id": "HRPRP-DEPCR",
  "propertyId": "HRPRP",
  "code": "DEPCR",
  "name": "Deposit Credit",
  "type": "Other"
}
{
  "serviceType": "Other",
  "vatType": "Without",
  "subAccountId": "HRPRP-DEPCR",
  "name": "Deposit Credit",
  "amount": {
    "amount": -500,
    "currency": "EUR"
  },
  "receipt": "5018/600/5009"
}
Deposit credit transaction
  • When the reservation is checked in, the deposit movement happens in two steps:
    1. Deposit Credit is refunded and moved to a new folio, for example Folio #3.
    2. The same charges from the deposit invoice are posted again with reversed signs.
Deposit credit refunded
Reversed deposit charges
  • The reference for the deposit invoice is stored in the Receipt field.
Body: {"serviceType":"Other","vatType":"Normal","subAccountId":"HRPRP-DEP5","name":"Deposit 25%","quantity":1,"amount":{"amount":-425,"currency":"EUR"},"receipt":"5018/600/5009"}
Body: {"serviceType":"Other","vatType":"Normal","subAccountId":"HRPRP-DEP25","name":"Deposit 25%","quantity":1,"amount":{"amount":-75,"currency":"EUR"},"receipt":"5018/600/5009"}
  • When an invoice is generated with deposit charges that include this reference, the final invoice shows the link to the deposit invoice. If more than one payment exists, the final invoice can reference more than one deposit invoice.
Final invoice with deposit reference

Required Fields for Billing Address

On the folio level, the following fields are required or relevant for billing:

  • Codice Fiscale

    • This field validates the format, so only correctly formatted values are accepted.
    • Examples:

    Codice fiscale with wrong format

    Codice fiscale wrong format billing address

    Codice fiscale with correct format

    Codice fiscale correct format billing address

    Note: Codice Fiscale is not mandatory when Scontrino Elettronico is used. In the API, it is called Personal Tax ID.

  • Codice Destinatario

    • For a company with an Italian address, Codice Destinatario is optional.
    • The format is not validated.
    • The invoice can fail if the value is wrong.
    • Back-end handling works as follows:
      • B2B invoice and company is non-Italian
        • Codice Destinatario is sent as XXXXXXX.
      • B2B invoice and company is Italian
        • When Codice Destinatario is provided:
          • It is sent with the value from the additionalTaxId field.
        • When Codice Destinatario is not provided:
          • It is sent as 0000000.

    Codice Destinatario exists on two levels:

    • Folio
    Codice Destinatario on folio
    • Company
    Codice Destinatario on company

Unfiscalized Folios Screen

This app gives users full visibility into invoices that failed fiscalization and need review or corrected data before they can be sent again.

The screen has two tabs:

Folios with failed invoices

  • The date picker shows the reservation check-out date.
  • The list shows all folios where:
    • Folio status is not closedWithInvoice
    • And an invoice has already failed during the generation process

Other open folios

  • The date picker shows the reservation check-out date.
  • The list shows all folios where:
    • Folio status is not closedWithInvoice
    • And a payment has been posted
    • And no invoice was created from the folio
  • Show checked-out reservations only checkbox
    • This shows all checked-out reservations that do not have an invoice.

Outgoing Invoice Book

  • To complete the monthly VAT register, a report is needed from Apaleo.
  • This report breaks down each scontrino elettronico and each invoice by VAT rate.
  • These documents can be split into a maximum of 3 lines because only 3 VAT rates are used: for example 22%, 10%, and 0%.
  • The report helps track all transactions included in the reported invoice.
  • Only invoices with the status Rendered are shown.
  • Example

```

Related articles