E-Invoicing for Italy: API References

Introduction

Italy has a mandatory B2B and B2C e-invoicing system in place, with all invoices required to be submitted through the Sistema di Interscambio (SDI) platform. This system is central to Italy's e-invoicing framework, and invoices must be in the FatturaPA format, which uses XML. The SDI ensures compliance with tax regulations by providing a secure and standardized method for transmitting invoices. Since 2022, cross-border invoices must also be reported through SDI, although foreign recipients are not required to use the platform. They must receive invoices in mutually agreed formats (e.g., PDF, EDI), and the Italian recipient must then recreate the invoice in the FatturaPA format for submission.

Mandatory B2G and B2B e-invoicing: All B2B invoices must be submitted via SDI, starting from 2022 for cross-border transactions.
Invoice Format: FatturaPA XML format is mandatory, with rare usage of CIUS-IT for cross-border transactions.
Cross-Border Invoicing: Cross-border invoices must be reported via SDI; however, the foreign recipient does not need to use SDI.
Invoice Archiving: Invoices must be stored for 10 years with stringent rules, including the appointment of a “Conservation Manager”.
E-Ordering: Italy has expanded e-invoicing into the e-ordering domain for public healthcare entities through the NSO platform.

POST/it/einvoice/onboard

Onboard to Peppol

This endpoint allows you to onboard into the Peppol Network using Flick as your Access Point. Peppol (Pan-European Public Procurement Online) facilitates the standardized exchange of e-invoices and business documents, ensuring compliance and interoperability between participants.

Request Body

Name
registered_name
Type
string: mandatory (limit: 300 chars)
Description
Registred Name of Supplier’s business
Name
identifiers
Type
array: mandatory
Description
For all VAT-registered businesses in Italy, the Identification Number (IT:CUUO) is mandatory.
Name
IT:CUUO
Type
string: mandatory if applicable
Description
Name
city
Type
string: optional (limit: 50 chars)
Description
Registered City of the supplier.
Name
street
Type
string: optional (limit: 150 chars)
Description
Street details of the supplier. If not available, provide 'NA'.
Name
county
Type
string: optional (limit: 150 chars)
Description
County details of the supplier. If not available, provide 'NA'.
Name
country
Type
string: ISO 3166-1 alpha-2 country code
Description
Country of the supplier. DE in case of .
Name
contact_number
Type
string: optional (limit: 20 chars)
Description
The telephone number of the Supplier (e.g., office, mobile, fax).

Sample Request

POST

/it/einvoice/onboard

curl 
  --url https://sandbox-api.flick.network/it/einvoice/onboard \
  --header 'x-flick-auth-key: {token}' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "registered_name": "TestCompany",
    "identifiers": [
      {
        "scheme": "IT:CUUO",
        "id": "SCSCSCS"
      }
    ],
    "city": "Rome",
    "street": "Via Esempio 25",
    "county": "Lazio",
    "country": "IT",
    "contact_number": "+39-06-9876543"
  }'

Sample Response

200

Success

{
  "status": "success",
  "message": "Successfully Onboarded to Peppol",
  "data": {
    "supplier_uuid": "f4b173a9-9f0f-4850-b682-762290885fee"
  }
}

POST/it/einvoice/generate/invoice

Submit an Invoice

To Generate a new E-Invoice Document & share it through Peppol, this endpoint can be used along with the Supplier UUID to which it belongs to. Specify transport_mode for proper delivery of the document.

Request Body

Name
ID
Type
string: mandatory (limit: 50 chars)
Description
Unique Invoice Reference Number. This should be made in sequence.
Name
DocumentType
Type
string: mandatory (limit: 50 chars)
Description
Specifies the type of document. For example, Invoice, CreditNote or DebitNote.
Name
IssueDate
Type
date: mandatory, schema: YYYY-MM-DD
Description
Date on which the invoice was issued.
Name
DocumentCurrencyCode
Type
string: mandatory (3 chars)
Description
Currency in which the invoice was issued. Default value: EUR.
Name
CustomerParty
Type
object: mandatory
Description
Information about the customer to whom the invoice is issued.
Name
RegisteredName
Type
string: mandatory (limit: 300 chars)
Description
Name of the Customer/Receiving company.
Name
address
Type
object: mandatory
Description
Address details of the customer.
Name
Street
Type
string: mandatory (limit: 150 chars)
Description
Street details of the customer. If not available, provide NA.
Name
ZipCode
Type
string: mandatory (limit: 10 chars)
Description
ZIP code of the customer's address.
Name
City
Type
string: mandatory (limit: 50 chars)
Description
City of the customer's address.
Name
Country
Type
string: ISO 3166-1 alpha-2 country code
Description
Country of the customer. Use FI for Italy.
Name
Identifiers
Type
array: mandatory
Description
List of public identifiers for the customer.
Name
Scheme
Type
string: mandatory
Description
Scheme type of the identifier, e.g., IT:CUUO.
Name
ID
Type
string: mandatory (limit: 50 chars)
Description
The identifier value for the given scheme.
Name
InvoiceLines
Type
array: mandatory
Description
Details of the line items in the invoice.
Name
Description
Type
string: mandatory (limit: 300 chars)
Description
Description of the purchased goods or services.
Name
PriceAmount
Type
number: mandatory
Description
Amount excluding VAT for the line item.
Name
TaxType
Type
object: mandatory
Description
Tax details for the line item.
Name
TaxRate
Type
number: mandatory
Description
The VAT percentage applicable to the line item.
Name
TaxType
Type
enum: mandatory
Description
Tax category. For example, standard or reduced.
Name
TaxCountry
Type
string: ISO 3166-1 alpha-2 country code
Description
Country for which the tax is applied. Use FI for Italy.
Name
TotalIncludingVat
Type
number: mandatory
Description
Total amount of the invoice, including VAT.

Sample Request

POST

/it/einvoice/generate/invoice

curl --url https://sandbox-api.flick.network/it/einvoice/generate/invoice \
  --header 'x-flick-auth-key: {token}' \
  --header 'supplier_uuid: {supplier_uuid}' \
  --header 'transport_mode: peppol' \
  --header 'Content-Type: application/json' \
  --data '
    {
      "ID": "INV-11",
      "DocumentType": "Invoice",
      "IssueDate": "2024-12-01",
      "DocumentCurrencyCode": "EUR",
      "CustomerParty": {
        "RegisteredName": "Test Inc.",
        "address": {
          "Street": "Street Name 987",
          "ZipCode": "9999AA",
          "City": "City Test",
          "Country": "IT"
        },
        "Identifiers": [
          {
            "Scheme": "IT:CUUO",
            "ID": "SCSCSCS"
          }
        ]
      },
      "InvoiceLines": [
        {
          "Description": "Test Item",
          "InvoicedQuantity": 2,
          "PriceAmount": 100,
          "TaxType": {
            "TaxRate": 19,
            "TaxType": "standard",
            "TaxCountry": "IT"
          }
        }
      ],
      "TotalIncludingVat": 238.00
    }'

Sample Response

200

Success

{
  "status": "success",
  "data": {
    "DocumentID": "52d08f40-a2a0-450b-857f-2e1dd865064c",
    "DeliveryStatus": "Scheduled"
  }
}

GET/it/einvoice/get-document/{uuid}

Get Document Details

This API endpoint allows users to get details of a document by querying with UUID.

GET Request Parameters

Name
uuid
Type
string
Description
UUID of the document

Sample Request

POST

/it/einvoice/get-document/{uuid}

curl 
  --url https://sandbox-api.flick.network/it/einvoice/get-document/{uuid} \

  --header 'x-flick-auth-key: {token}' \
  --header 'supplier_uuid: {supplier_uuid}'

Sample Response

200

Success

{
  "uuid": "52d08f40-a2a0-450b-857f-2e1dd865064c",
  "ID": "INV-11",
  "DocumentType": "Invoice",
  "IssueDate": "2024-12-01",
  "DocumentCurrencyCode": "EUR",
  "CustomerParty": {
    "RegisteredName": "Test Inc.",
    "address": {
      "Street": "Street Name 987",
      "ZipCode": "9999AA",
      "City": "City Test",
      "Country": "IT"
    },
    "Identifiers": [
      {
        "Scheme": "IT:CUUO",
        "ID": "SCSCSCS"
      }
    ]
  },
  "InvoiceLines": [
    {
      "Description": "Test Item",
      "InvoicedQuantity": 2,
      "PriceAmount": 100,
      "TaxType": {
        "TaxRate": 19,
        "TaxType": "standard",
        "TaxCountry": "IT"
      }
    }
  ],
  "TotalIncludingVat": 238.00
}

GET/it/einvoice/delivery-status/{uuid}

Get Delivery Status

This API endpoint allows users to query the status of delivery of a document through Peppol.

GET Request Parameters

Name
uuid
Type
string
Description
UUID of the document

Sample Request

POST

/it/einvoice/delivery-status/{uuid}

curl 
  --url https://sandbox-api.flick.network/it/einvoice/delivery-status/{uuid} \

  --header 'x-flick-auth-key: {token}' \
  --header 'supplier_uuid: {supplier_uuid}'

Sample Response

200

Success

{
  "DocumentID": "52d08f40-a2a0-450b-857f-2e1dd865064c",
  "DeliveryStatus": "Delivered"
}

WEBHOOKEVENT LISTEN TO BE LISTENED

Received Document

You can listen to this webhook to get new documents issued against the supplier.

Request Body

Name
Event
Type
string
Description
Type of Event that happend.
Name
EventType
Type
string
Description
Type of Event Type that happend.
Name
EventGroup
Type
string
Description
Type of Event group that it belongs.
Name
uuid
Type
string
Description
UUID of the document
Name
DocumentId
Type
string
Description
Internal Document ID
Name
Status
Type
string
Description
Current status of the document

Sample Request

POST

{
  "Event": "DocumentReceived",
  "EventType": "PeppolReceived",
  "EventGroup": "Invoice",
  "uuid": "52d08f40-a2a0-450b-857f-2e1dd865064c",
  "DocumentId": "INV-123",
  "Status": "Delivered"
}