Italy Fiscalization Guide

Italy has two fiscalization systems, and FiscalAPI supports both:

System	Use case	Authority protocol
SDI / FatturaPA	B2B and B2G electronic invoicing	Sistema di Interscambio
Documento Commerciale (DC)	B2C retail POS receipts	SSW (Software Solution) via Agenzia delle Entrate

FiscalAPI routes transactions to the correct system based on your location's country_config. B2B invoices go through SDI, while B2C retail transactions go through the Documento Commerciale system.

SDI / FatturaPA (B2B / B2G invoicing)

Italy uses the Sistema di Interscambio (SDI) for electronic invoicing. All B2B and B2G invoices must be submitted in FatturaPA format (v1.2.2) through SDI. FiscalAPI handles XML generation, submission, and async notification processing.

How it works

Unlike Spain's synchronous submission, Italy's SDI flow is asynchronous:

You create a transaction via POST /v1/transactions
FiscalAPI generates FatturaPA XML and submits it to SDI
SDI returns a tracking number (IdentificativoSdI) -- your transaction enters pending status
SDI processes the invoice and sends async notifications to FiscalAPI's webhook
Your transaction status updates to delivered, rejected, or delivery_error

You can subscribe to webhooks to receive notifications when your transaction status changes.

FatturaPA format overview

FatturaPA is the mandatory XML format for Italian electronic invoicing. Each invoice includes:

Transmission header (FatturaElettronicaHeader) -- sender/receiver IDs, transmission format
Invoice body (FatturaElettronicaBody) -- invoice details, line items, totals, payment info

Two transmission formats are supported:

Format	Code	Use case
Public Administration	`FPA12`	Invoices to government entities (B2G)
Private	`FPR12`	B2B and B2C invoices

Document types (TipoDocumento)

FatturaPA uses document type codes (TD) to classify invoices. FiscalAPI maps transaction types automatically:

Transaction type	Document type
`sale`	TD01 (Fattura -- standard invoice)
`refund`	TD04 (Nota di credito -- credit note)
`void`	TD04 (Nota di credito -- credit note)

The full set of supported TD codes:

Code	Description
TD01	Fattura (standard invoice)
TD02	Acconto/anticipo su fattura (advance on invoice)
TD03	Acconto/anticipo su parcella (advance on fee note)
TD04	Nota di credito (credit note)
TD05	Nota di debito (debit note)
TD06	Parcella (fee note)
TD07	Fattura semplificata (simplified invoice)
TD08	Nota di credito semplificata (simplified credit note)
TD09	Nota di debito semplificata (simplified debit note)
TD11	Fattura per cessione intracomunitaria (intra-EU supply)
TD16	Integrazione fattura reverse charge interno (domestic reverse charge)
TD17	Integrazione/autofattura acquisto servizi dall'estero (foreign services)
TD18	Integrazione acquisto beni intracomunitari (intra-EU goods)
TD19	Integrazione/autofattura beni ex art.17 c.2 (goods per art.17)
TD20	Autofattura per regolarizzazione e integrazione (self-invoice)
TD21	Autofattura per splafonamento (ceiling breach self-invoice)
TD22	Estrazione beni da Deposito IVA (VAT warehouse extraction)
TD23	Estrazione beni da Deposito IVA con versamento IVA (VAT warehouse with payment)
TD24	Fattura differita art. 21 c.4 lett. a) (deferred invoice)
TD25	Fattura differita art. 21 c.4 lett. b) (deferred invoice)
TD26	Cessione beni ammortizzabili e passaggi interni (asset transfers)
TD27	Autoconsumo o cessioni gratuite senza rivalsa (self-consumption)

SDI submission flow

POST /v1/transactions
        │
        ▼
┌─────────────────┐
│ Generate XML    │  FatturaPA v1.2.2
│ (FatturaPA)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Submit to SDI   │  REST API with Bearer token
│                 │  Returns IdentificativoSdI
└────────┬────────┘
         │
         ▼
   Status: pending
         │
    ┌────┴────────────────┐
    │  SDI processes      │  (async, minutes to days)
    │  async              │
    └────┬────────────────┘
         │
    ┌────┼────────┐
    ▼    ▼        ▼
   RC   NS       MC
delivered rejected delivery_error

Key points:

SDI authentication uses channel credentials (channel ID, password, API token) -- not document-level signatures
The IdentificativoSdI returned by SDI is stored as the transaction's fiscal_id
Sandbox and production use different SDI endpoints; FiscalAPI routes automatically based on test_mode

Async notification lifecycle

After submission, SDI sends XML notifications to FiscalAPI's webhook endpoint. Each notification updates your transaction status:

Code	Name	Status	Description
RC	RicevutaConsegna	`delivered`	Invoice successfully delivered to the recipient
NS	NotificaScarto	`rejected`	Invoice has validation errors -- must be corrected and resubmitted
MC	NotificaMancataConsegna	`delivery_error`	SDI could not deliver to the recipient (e.g., recipient's channel is down)

Handling each notification

RC (Delivery receipt) -- Your invoice was delivered. No action needed. The transaction is complete.

NS (Rejection) -- SDI rejected the invoice due to validation errors. The notification includes an error list:

{
  "event": "fiscalization.completed",
  "status": "rejected",
  "transaction_id": "..."
}

You should correct the invoice data and create a new transaction.

MC (Failed delivery) -- SDI accepted the invoice but could not deliver it to the recipient. The invoice is still valid. SDI may retry delivery, or the recipient can retrieve it from their SDI portal.

Subscribing to status updates

Use FiscalAPI webhooks to receive notifications when SDI updates your transaction:

curl -X POST https://api.fiscalapi.com/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "url": "https://example.com/webhooks/fiscalapi",
    "events": ["fiscalization.completed", "fiscalization.dead_letter"],
    "description": "Italy SDI notifications"
  }'

Country config fields

The country_config object for Italian SDI locations:

Field	Type	Required	Description
`partita_iva`	string	Yes	VAT number, exactly 11 digits
`codice_fiscale`	string	Yes	Tax code, 11-16 alphanumeric characters
`formato_trasmissione`	string	Yes	`FPA12` (Public Administration) or `FPR12` (B2B/B2C)
`regime_fiscale`	string	Yes	Tax regime code, `RF01` through `RF19`
`api_credential_id`	string	No	Reference to stored SDI API credentials
`progressivo_invio`	string	No	Transmission sequence prefix (auto-generated if empty)

Tax regime codes

Common regime codes:

Code	Description
RF01	Regime ordinario (standard)
RF02	Contribuenti minimi
RF04	Agricoltura
RF19	Regime forfettario

Configuration example

B2B location

curl -X POST https://api.fiscalapi.com/v1/locations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "name": "Milan Office",
    "country": "IT",
    "address": "Via Montenapoleone 1, 20121 Milano",
    "tax_id": "12345678901",
    "country_config": {
      "partita_iva": "12345678901",
      "codice_fiscale": "RSSMRA85M01H501Z",
      "formato_trasmissione": "FPR12",
      "regime_fiscale": "RF01"
    }
  }'

Public Administration location

curl -X POST https://api.fiscalapi.com/v1/locations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "name": "Rome PA Office",
    "country": "IT",
    "address": "Via del Corso 1, 00186 Roma",
    "tax_id": "12345678901",
    "country_config": {
      "partita_iva": "12345678901",
      "codice_fiscale": "12345678901",
      "formato_trasmissione": "FPA12",
      "regime_fiscale": "RF01"
    }
  }'

Creating a transaction

Include Italy-specific metadata when creating transactions:

curl -X POST https://api.fiscalapi.com/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "location_id": "loc_abc123",
    "type": "sale",
    "amount": 12200,
    "currency": "EUR",
    "metadata": {
      "invoice_number": "FT-2026-001",
      "invoice_date": "2026-03-13",
      "codice_destinatario": "ABC1234",
      "buyer_denomination": "Buyer Corp SRL",
      "buyer_country": "IT"
    },
    "line_items": [
      {
        "description": "Consulting services",
        "quantity": 1,
        "unit_price": 10000,
        "vat_rate": 2200
      }
    ]
  }'

Transaction metadata fields

Field	Required	Default	Description
`invoice_number`	Yes	--	Your invoice number (mapped to `Numero` in FatturaPA)
`invoice_date`	No	Transaction creation date	Invoice date in `YYYY-MM-DD` format
`codice_destinatario`	No	`0000000`	Recipient's SDI channel code (7 characters)
`buyer_denomination`	No	--	Buyer's company name
`buyer_country`	No	`IT`	Buyer's country code (ISO 3166-1 alpha-2)

Validation rules

FiscalAPI enforces these rules for Italian SDI locations:

Rule	Detail
`partita_iva` required	Must be exactly 11 digits
`codice_fiscale` required	Must be 11-16 alphanumeric characters (uppercase)
`formato_trasmissione` required	Must be `FPA12` or `FPR12`
`regime_fiscale` required	Must match pattern `RF01` through `RF19`
`invoice_number` required	Must be present in transaction metadata

Error examples

Missing partita IVA:

{
  "error": "partita_iva is required"
}

Invalid formato trasmissione:

{
  "error": "formato_trasmissione must be FPA12 or FPR12"
}

Missing invoice number:

{
  "error": "invoice_number is required in metadata for Italian transactions"
}

Sandbox testing (SDI)

Use test_mode: true on your transactions to route to the SDI sandbox environment. The sandbox uses the same API contract but doesn't submit real invoices.

curl -X POST https://api.fiscalapi.com/v1/transactions \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "location_id": "loc_abc123",
    "type": "sale",
    "test_mode": true,
    "amount": 12200,
    "currency": "EUR",
    "metadata": {
      "invoice_number": "TEST-001"
    }
  }'

Documento Commerciale (B2C retail)

The Documento Commerciale (DC) is Italy's fiscal receipt system for retail POS transactions. It replaces the old paper "scontrino fiscale" with electronically transmitted receipts via the Agenzia delle Entrate (AdE).

FiscalAPI uses the Software Solution (SSW) approach, a fully software-based method introduced January 1, 2026 under Legislative Decree 1/2024. This eliminates the need for physical Registratore Telematico (RT) hardware at each POS.

How it works

The DC flow is asynchronous with polling:

You create a transaction via POST /v1/transactions with a DC-configured location
FiscalAPI generates the Documento Commerciale XML (DSW10 format) and seals it with an advanced electronic seal
The sealed document is submitted to the AdE SSW API as binary data
AdE returns an idPresaInCarico (intake ID) -- your transaction enters pending status
FiscalAPI polls AdE for the processing result
Your transaction status updates to success or failed

B2B vs B2C routing

FiscalAPI automatically routes transactions based on your location's country_config:

Config field	System	Use case
`formato_trasmissione: FPR12` or `FPA12`	SDI / FatturaPA	B2B and B2G invoicing
`system: dc`	Documento Commerciale / SSW	B2C retail receipts

A single merchant may have both SDI locations (for invoicing) and DC locations (for retail). Each location is configured independently.

DC location configuration

DC locations require additional fields in country_config:

Field	Type	Required	Description
`system`	string	Yes	Must be `"dc"` for Documento Commerciale
`partita_iva`	string	Yes	VAT number, exactly 11 digits
`codice_fiscale`	string	Yes	Tax code, 11-16 alphanumeric characters
`legal_name`	string	Yes	Business legal name
`cau_code`	string	Yes	Erogatore (provider) code, 4 alphanumeric characters
`pem_matricola`	string	Yes	Emission point ID (pattern: `XXXX-XXXXXX`, 11 characters)
`seal_certificate_id`	string	Yes	Reference to stored QTSP electronic seal certificate

Configuration example

curl -X POST https://api.fiscalapi.com/v1/locations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "name": "Rome Retail Store",
    "country": "IT",
    "address": "Via del Corso 100, 00186 Roma",
    "tax_id": "01234567890",
    "country_config": {
      "system": "dc",
      "partita_iva": "01234567890",
      "codice_fiscale": "01234567890",
      "legal_name": "Negozio Roma SRL",
      "cau_code": "AB12",
      "pem_matricola": "AB12-000001",
      "seal_certificate_id": "cert_seal_abc123"
    }
  }'

DC transaction metadata

DC transactions use different metadata fields than SDI invoices:

Field	Required	Description
`cash_amount`	Conditional	Cash payment amount (required if payment includes cash)
`electronic_amount`	Conditional	Electronic payment amount (required if payment includes card/transfer)
`ticket_amount`	No	Ticket/voucher payment amount
`ticket_count`	No	Number of tickets used
`lottery_code`	No	Customer's lottery code (0-16 characters)
`instant_lottery_qr`	No	Instant lottery QR code (0-64 characters)
`customer_codice_fiscale`	No	Customer's tax code (only if requested by customer)

For returns and cancellations:

Field	Required	Description
`is_return`	Yes (for returns)	Set to `true` for a return (reso)
`is_cancellation`	Yes (for cancellations)	Set to `true` for a cancellation (annullo)
`original_matricola`	Yes (for returns/cancellations)	PEM matricola of original transaction
`original_date`	Yes (for returns/cancellations)	Date of original transaction (ISO format)
`original_number`	Yes (for returns/cancellations)	Progressive number of original transaction (NNNN-NNNN)

Creating a DC transaction

curl -X POST https://api.fiscalapi.com/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "location_id": "loc_dc_roma",
    "timestamp": "2026-03-15T14:30:00Z",
    "items": [
      {
        "description": "Cappuccino",
        "quantity": 2,
        "unit_price": 1.50,
        "tax_rate": 10.00,
        "tax_amount": 0.30,
        "total_amount": 3.30
      },
      {
        "description": "Cornetto",
        "quantity": 2,
        "unit_price": 1.20,
        "tax_rate": 4.00,
        "tax_amount": 0.10,
        "total_amount": 2.50
      }
    ],
    "pretax_amount": 5.40,
    "tax_amount": 0.40,
    "total_amount": 5.80,
    "currency": "EUR",
    "payment_method": "card",
    "metadata": {
      "electronic_amount": 5.80
    }
  }'

Creating a DC return

curl -X POST https://api.fiscalapi.com/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "location_id": "loc_dc_roma",
    "timestamp": "2026-03-15T15:00:00Z",
    "items": [
      {
        "description": "Cornetto (reso)",
        "quantity": 1,
        "unit_price": 1.20,
        "tax_rate": 4.00,
        "tax_amount": 0.05,
        "total_amount": 1.25
      }
    ],
    "pretax_amount": 1.20,
    "tax_amount": 0.05,
    "total_amount": 1.25,
    "currency": "EUR",
    "payment_method": "card",
    "metadata": {
      "is_return": true,
      "electronic_amount": 1.25,
      "original_matricola": "AB12-000001",
      "original_date": "2026-03-15",
      "original_number": "0001-0042"
    }
  }'

DC VAT rates

Italy uses these VAT rates for retail transactions:

Rate	Application
22%	Standard rate (most goods and services)
10%	Reduced (tourism, some food, renovations)
5%	Reduced (certain food items, social services)
4%	Super-reduced (basic necessities: bread, milk)

For non-IVA operations, use Natura codes instead of a VAT rate:

Code	Meaning
N1	Excluded per Art. 15, D.P.R. 633/1972
N2	Non-subject to VAT
N3	Non-taxable
N4	Exempt
N5	Margin scheme (regime del margine)
N6	Other non-IVA operations

SSW submission flow

POST /v1/transactions
        │
        ▼
┌──────────────────┐
│ Generate XML     │  DSW10 format
│ (Doc. Commerciale)│
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Seal with eIDAS  │  QTSP advanced electronic seal
│ certificate      │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ POST /corrispettivi│  Binary octet-stream
│ to AdE SSW API   │  Returns idPresaInCarico
└────────┬─────────┘
         │
         ▼
   Status: pending
         │
    ┌────┴──────────────────────┐
    │  Poll /corrispettivi/     │
    │  {id}/stato               │
    └────┬──────────────────────┘
         │
    ┌────┼──────────┐
    ▼    ▼          ▼
 PRONTA  IN_ELAB.  NON_DISP.
    │
    ▼
 GET /esito
    │
  ┌─┴──┐
  ▼    ▼
success failed

SSW error codes

When AdE rejects a submission, the response includes error codes:

Code	Description	Retriable
0100	File non conforme (non-compliant file)	No
0200	Errore di validazione (validation error)	No
0403	Non autorizzato (not authorized)	No
0429	Limite di frequenza superato (rate limit exceeded)	Yes
0500	Errore interno del server (internal server error)	Yes

FiscalAPI automatically translates Italian error descriptions to English in the transaction's error_message field.

DC internal architecture

For detailed DC architecture, XML schema specification, SSW API endpoints, PEM lifecycle management, and sealing strategy, see the Italy Documento Commerciale architecture doc.

Sandbox testing (DC)

Use a test-mode API key (fsk_test_...) to route DC transactions to the AdE sandbox environment:

curl -X POST https://api.fiscalapi.com/v1/transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fsk_test_abc123def456..." \
  -d '{
    "location_id": "loc_dc_roma",
    "timestamp": "2026-03-15T14:30:00Z",
    "items": [
      {
        "description": "Test item",
        "quantity": 1,
        "unit_price": 10.00,
        "tax_rate": 22.00,
        "tax_amount": 2.20,
        "total_amount": 12.20
      }
    ],
    "pretax_amount": 10.00,
    "tax_amount": 2.20,
    "total_amount": 12.20,
    "currency": "EUR",
    "payment_method": "cash",
    "metadata": {
      "cash_amount": 12.20
    }
  }'

SDI / FatturaPA (B2B / B2G invoicing)​

How it works​

FatturaPA format overview​

Document types (TipoDocumento)​

SDI submission flow​

Async notification lifecycle​

Handling each notification​

Subscribing to status updates​

Country config fields​

Tax regime codes​

Configuration example​

B2B location​

Public Administration location​

Creating a transaction​

Transaction metadata fields​

Validation rules​

Error examples​

Sandbox testing (SDI)​

Documento Commerciale (B2C retail)​

How it works​

B2B vs B2C routing​

DC location configuration​

Configuration example​

DC transaction metadata​

Creating a DC transaction​

Creating a DC return​

DC VAT rates​

SSW submission flow​

SSW error codes​

DC internal architecture​

Sandbox testing (DC)​

SDI / FatturaPA (B2B / B2G invoicing)

How it works

FatturaPA format overview

Document types (TipoDocumento)

SDI submission flow

Async notification lifecycle

Handling each notification

Subscribing to status updates

Country config fields

Tax regime codes

Configuration example

B2B location

Public Administration location

Creating a transaction

Transaction metadata fields

Validation rules

Error examples

Sandbox testing (SDI)

Documento Commerciale (B2C retail)

How it works

B2B vs B2C routing

DC location configuration

Configuration example

DC transaction metadata

Creating a DC transaction

Creating a DC return

DC VAT rates

SSW submission flow

SSW error codes

DC internal architecture

Sandbox testing (DC)