Skip to content
Guide API Spec
Section navigation

Italy — E-INVOICE IT (Unified API)

In Italy, fiskaly supports sending B2B and B2C e-invoices, and receiving B2B e-invoices. We currently support the Standard Invoice (Fattura, TD01). Support for the Simplified Invoice (Fattura semplificata, TD07) is coming soon.

E-invoicing is mandatory and regulated by the Agenzia delle Entrate (Revenue Agency). Both B2B and B2C invoices must be exchanged via SDI (Sistema di Interscambio — Exchange System) in the FatturaPA (Electronic Invoice) XML format and have been legally required since January 2019. Invoices must also be preserved long-term through certified archiving (conservazione a norma).

This page covers the Italy-specific requirements that complement the General Step-by-Step Integration, for onboarding a Taxpayer for e-invoicing.

fiskaly handles both directions of the SDI exchange, and the two work differently:

📤

Sending — B2B and B2C

fiskaly generates the FatturaPA and submits it to SDI, which validates and forwards it to the recipient asynchronously. No network registration is required. Business and consumer recipients each take different fields.

📥

Receiving — B2B only

Optional, and enabled per Taxpayer. Requires a one-time registration to receive invoices from your suppliers.

On top of both directions, every invoice you send and receive is automatically archived for you. This means certified long-term preservation (conservazione a norma) for the legally required 10 years, with no setup on your side.

🗄️

Archiving

How e-invoices are preserved and how to retrieve the FatturaPA XML and preservation receipt via the API.

Prerequisites

Section titled “Prerequisites”

These apply to any Taxpayer you onboard for e-invoicing in Italy — whether you send, receive, or both. Make sure you have the following Taxpayer information ready before proceeding.

Italy-specific registration data — submitted under content.fiscalization.registration:

  • company_id — Numero Registro Imprese (Business Register number)
  • office — province code of the Camera di Commercio that issued the REA number, e.g. MI, RM
  • entry — REA number (6 or 7 digits)
  • legal_form — legal form of the entity (e.g. LIMITED_LIABILITY_COMPANY, JOINT_STOCK_COMPANY)
  • capital — registered share capital in EUR (e.g. "10000.00")
  • shareholder_status — SOLE_SHAREHOLDER or MULTIPLE_SHAREHOLDERS
  • liquidation_status — IN_LIQUIDATION or NOT_IN_LIQUIDATION
  • tax_regime — optional, ORDINARY (default) or FLAT_RATE_SCHEME (Regime Forfettario)

Standard Taxpayer fields — part of the Taxpayer itself (shared with SIGN IT if you use it):

  • content.name — registered legal name of the company or individual
  • content.address — registered legal address
  • content.address.region — Provincia (Province code, e.g. MI, RM); required on the Taxpayer and validated at commissioning

Sending e-invoices: recipient requirements

Section titled “Sending e-invoices: recipient requirements”

To send an e-invoice, you specify its recipient and their routing details — right on the invoice record. When you create the invoice (TRANSACTION::INVOICE) with createRecord, add the recipient to its recipients array. Which fields you set depends on who you are invoicing:

🏢

Business recipients (B2B)

Routed by the recipient's SDI destination code, or by PEC if they have no SDI inbox.

🧑

Consumer recipients (B2C)

Italian residents are identified by codice fiscale; consumers abroad by a foreign identifier.

Every recipient carries invoicing.type = SDI. What changes between the three cases is the identification, the destination code, and whether a PEC is involved:

BusinessConsumer in ItalyConsumer abroad
typeBUSINESSCONSUMERCONSUMER
identificationVAT — validatedTAX — codice fiscale, validatedany type; not validated
invoicing.destination_codethe recipient’s 7-character code, or "0000000", or "XXXXXXX""0000000""XXXXXXX"
invoicing.pecrequired with "0000000"optionalnot used
address.regionrequired when the address is in Italyrequirednot required
namecompany namegender, forename, surnamegender, forename, surname

Business recipients (B2B)

Section titled “Business recipients (B2B)”

Each business recipient is a BUSINESS with a populated invoicing block, as the General Step-by-Step Integration explains. Beyond the standard details every e-invoice requires (recipient name, address, tax identification, invoice lines, and so on), Italy adds the SDI routing fields above.

Which values destination_code and pec take depends on the recipient:

Scenariodestination_codepec
Recipient has a registered SDI inboxtheir 7-character code (e.g. ABC1234)optional
Recipient is not registered with SDI"0000000"required
Recipient is outside Italy"XXXXXXX"not used

Consumer recipients (B2C)

Section titled “Consumer recipients (B2C)”

When your customer is a private individual rather than a business, set recipients[].type to CONSUMER. The invoice goes through SDI as a FatturaPA (TD01) document, like a B2B invoice.

Consumers have no SDI inbox, so routing works differently. How you identify the consumer depends on whether they are resident in Italy:

  • Resident in Italy — identified by their codice fiscale, routed with destination code "0000000".
  • Outside Italy — no codice fiscale exists, so a foreign identifier takes its place and the invoice is routed with "XXXXXXX".

Beyond the fields in the table above, a consumer recipient always carries name.gender, name.forename, and name.surname, plus the consumer’s address.

Consumers resident in Italy

Section titled “Consumers resident in Italy”

Send the codice fiscale as a TAX identification (16 characters), the residence address including region (Provincia), and destination code "0000000". A pec may be added but is not required.

Consumers outside Italy

Section titled “Consumers outside Italy”

A consumer who isn’t resident in Italy has no codice fiscale, so send a foreign identifier in its place — typically a foreign tax or VAT number.

FieldValue
recipients[].identificationrequired; VAT, TAX, PASSPORT, DOCUMENT, or OTHER — whichever fits the identifier you hold
recipients[].address.countrythe consumer’s country as an ISO 3166-1 alpha-2 code
recipients[].address.code"00000" — FatturaPA only accepts a 5-digit postal code
recipients[].invoicing.destination_code"XXXXXXX"

The identifier travels to SDI as the IdCodice; neither fiskaly nor SDI checks it for validity once the address country is not Italy. region is not required for a non-Italian address.

For a consumer resident in Italy, SDI files the original invoice in their reserved area on the AdE portal (Fatture e Corrispettivi).

When the customer needs an invoice instead of a receipt

Section titled “When the customer needs an invoice instead of a receipt”

Italy reports the two documents through separate channels — the receipt through corrispettivi, the invoice through SDI — and nothing links them automatically.

Capture the request before the sale is closed. When the customer tells you they need a fattura, issue a TRANSACTION::INVOICE in place of a TRANSACTION::RECEIPT. Asking “do you need an invoice?” as part of checkout is the flow fiskaly supports end to end today, whether the customer asks before or during the sale.

Handling SDI responses

Section titled “Handling SDI responses”

Unlike a synchronous API call, the SDI outcome is asynchronous. After you create the invoice (TRANSACTION::INVOICE) with createRecord, poll or listen for updates on the E_INVOICE::TRANSMISSION Record to learn whether SDI accepted it.

All three Records reach their final state together:

RecordFinal state
E_INVOICE::TRANSMISSIONCOMPLETED or FAILED, mode=FINISHED
TRANSACTION::INVOICECOMPLETED or FAILED, mode=FINISHED
INTENTION::TRANSACTIONCOMPLETED or FAILED, mode=FINISHED

On failure, the SDI rejection reason is available in logs[].message on all three Records. For more details, see How to check the status of an e-invoice on our Support page.

Error stages

Section titled “Error stages”

Errors can occur at three distinct stages, each with different behavior:

StageWhenBehavior
UAPI validation (synchronous)Invalid payload4xx returned immediately — no Record is created. Fix the payload and retry on the same INTENTION::TRANSACTION.
Pre-SDI validation (asynchronous)Invoice rejected before reaching SDIFull chain reaches state=FAILED — a new chain is required to retry.
SDI rejection (asynchronous)SDI returns NSFull chain reaches state=FAILED — a new chain is required to retry.

Failures and resubmission

Section titled “Failures and resubmission”

If SDI returns NS (Notifica di Scarto), the invoice is legally non-existent:

  1. Read logs[].message on any of the three Records to get the SDI rejection reason.
  2. Create a new INTENTION::TRANSACTION and a new TRANSACTION::INVOICE with corrected data.
  3. The same document.number may be reused within 5 days of the NS rejection.
  4. The failed chain remains FAILED permanently — it is kept for audit purposes.

Receiving e-invoices

Section titled “Receiving e-invoices”

An E_INVOICE_SERVICE System can both send and receive e-invoices. Receiving is optional — a send-only Taxpayer can skip this section.

Two separate, independent things are involved:

  • Readiness to receive — fiskaly sets this up automatically when you commission the System.
  • SDI recipient-code registration (manual, done by you) — in your Agenzia delle Entrate (AdE) portal, set fiskaly’s SDI recipient code JKKZDGR as your company’s SDI destination, so SDI routes your inbound invoices to fiskaly.

The commissioning response shows compliance.state as TRANSMISSION_ONLY. It then moves to TRANSMISSION_RECEPTION automatically once the Taxpayer’s registration completes — which it normally does, regardless of whether you’ve done the AdE registration or plan to receive.

Call retrieveSystem at any time to read the current compliance.state, which reflects only readiness — not the AdE registration:

  • TRANSMISSION_RECEPTION — fiskaly has set the System up to receive.
  • TRANSMISSION_ONLY — that setup hasn’t completed.

There is nothing extra to set up for routing: fiskaly automatically matches each incoming invoice to the right Taxpayer using its tax ID — which is also why each tax ID must belong to a single registered Taxpayer. You don’t need to configure or store a separate routing code.

When an invoice arrives

Section titled “When an invoice arrives”

When an invoice is sent to you through SDI, fiskaly receives it automatically:

  • the inbound delivery triggers a webhook
  • a reception record is created for the invoice
  • the signed XML, PDF, and metadata are stored against the record
  • duplicate deliveries are deduplicated

In practice, the first invoice that reaches you this way is also your confirmation that receiving is set up correctly.

Archiving

Section titled “Archiving”

Italian law requires e-invoices to be preserved long-term through certified digital archiving (conservazione a norma): they must be kept for at least 10 years and stored so they remain immutable, authentic, and easily retrievable, with digital signatures and timestamps (marca temporale). Keeping your own copy of the XML is not enough — fiskaly handles this for you.

For Italy, archiving is automatic and always on: every invoice you send and every invoice you receive through SDI is legally preserved, with no extra setup or API call on your side. It only relies on the Taxpayer’s Italian tax ID, which is already part of onboarding. Each preserved invoice gets a preservation receipt as proof of conservazione a norma. Preservation usually completes within seconds; the receipt itself can take a few minutes to be issued, after which fiskaly attaches it automatically — nothing is required on your side.

Retrieve an e-invoice’s artifacts from its record with retrieveRecord, selecting the artifact through a query parameter:

  • compliance-artifact — the legally authoritative document. For Italy, the SDI-validated FatturaPA XML.
  • archive-artifact — the preservation receipt attesting legal preservation (conservazione a norma), available as a human-readable PDF and a signed XML for audit or legal use.