> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDI sending invoices guide

> Generate and issue electronic invoices through Italy's SDI system

> [!WARNING]
>
> **The SDI Italy app is being retired.** New integrations should use the [Italy app](https://docs.invopop.com/apps/italy.md), which reaches SDI through Invopop's own accredited channel. See the [issuing invoices](https://docs.invopop.com/guides/it-sdi-invoicing.md) guide.

## Introduction

Electronic invoicing is mandatory for all businesses in Italy. The *Sistema di Interscambio* (SDI) serves as the Italian government's central hub for transmitting, validating, and delivering all electronic invoices throughout the country.

The SDI system operates using a standardized XML format called FatturaPA, which ensures all invoices contain the required information and comply with the strict validation rules established by the Italian tax authority (*Agenzia delle Entrate*). To ensure proper routing of invoices to the correct recipient, the SDI system uses a unique identifier called a Recipient Code, which is assigned to each registered SDI provider.

Invopop simplifies SDI integration by allowing you to work with [GOBL](https://docs.gobl.org) format instead of XML, providing synchronous validation before submission, and offering a simple API integration with automatic handling of SDI notifications and status updates. For receiving invoices through SDI, see our companion guide: [Italy - SDI: Receiving Invoices](https://docs.invopop.com/guides/it-sdi-receiving.md).

| - | Sandbox | Live |
| - | - | - |
| **Responses** | Simulated by A-Cube (no real SDI sandbox) | Real SDI responses |
| **Configuration** | Simulated response type must be set | — |
| **Archiving** | A-Cube test environment (no legal validity) | Certified preservation |

## Setup

**1. Connect the SDI Italy app**

1. Navigate to **Configuration** → **Apps**
2. Locate **SDI Italy** in the app discovery list
3. Tap **Connect** to activate

![Connect SDI Italy app](https://mintcdn.com/invopop/-KQ2_uysex-mWyqz/assets/guides/it-sdi-connect.png?fit=max\&auto=format\&n=-KQ2_uysex-mWyqz\&q=85\&s=eeeb23ddd753bf29985b095001f0edcf)

The initial connection requires no configuration for sending invoices.

**2. Configure sending workflow**

> [!NOTE]
>
> SDI does not have a sandbox environment. When `sandbox` mode is selected, Invopop's third-party submission service, [A-Cube](https://www.acubeapi.com), simulates a response from SDI.

> [card] [SDI send invoice workflow](https://console.invopop.com/redirect/workflows/new?template=it-sdi-send)
>
> Add to my workspace →

> [tab] Workflow

> [tab] Code
>
> Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.
>
> ```json SDI issue invoice workflow theme={"system"}
> {
>     "name": "SDI issue invoice",
>     "description": "Issue an invoice through SDI",
>     "schema": "bill/invoice",
>     "steps": [
>         {
>             "id": "1a692ae0-cd12-11ef-998c-e97f18c9212e",
>             "name": "Set state",
>             "provider": "silo.state",
>             "summary": "Set state to `processing`{.state .processing}",
>             "config": {
>                 "state": "processing"
>             }
>         },
>         {
>             "id": "1855b430-cd12-11ef-998c-e97f18c9212e",
>             "name": "Sign envelope",
>             "provider": "silo.close"
>         },
>         {
>             "id": "2042f860-cd12-11ef-998c-e97f18c9212e",
>             "name": "Send invoice to SDI",
>             "provider": "sdi-it.send",
>             "summary": "Sandbox · Accepted by PA (Notifica esito)",
>             "config": {
>                 "environment": "sandbox",
>                 "response": "NE"
>             }
>         },
>         {
>             "id": "c1067e58-7b8b-11f1-8b0e-92000767c8b7",
>             "name": "Archive document for legal preservation",
>             "provider": "sdi-it.archive.store",
>             "summary": "Preserve invoice and store its receipt",
>             "config": {
>                 "environment": "sandbox"
>             }
>         },
>         {
>             "id": "236965b0-cd12-11ef-998c-e97f18c9212e",
>             "name": "Generate PDF",
>             "provider": "pdf",
>             "summary": "Italian · A4",
>             "config": {
>                 "date_format": "%Y-%m-%d",
>                 "locale": "it",
>                 "logo_height": 40
>             }
>         },
>         {
>             "id": "2b6db450-cd12-11ef-998c-e97f18c9212e",
>             "name": "Set state",
>             "provider": "silo.state",
>             "summary": "Set state to `sent`{.state .sent}",
>             "config": {
>                 "state": "sent"
>             }
>         }
>     ],
>     "rescue": [
>         {
>             "id": "2d5d7660-cd12-11ef-998c-e97f18c9212e",
>             "name": "Set state",
>             "provider": "silo.state",
>             "summary": "Set state to `error`{.state .error}",
>             "config": {
>                 "state": "error"
>             }
>         }
>     ]
> }
> ```

## Sending invoices

Invopop uses the [GOBL FatturaPA](https://github.com/invopop/gobl.fatturapa) library to process conversions. When creating invoices for SDI, you need to:

1. Set the `regime` field to `IT` in your GOBL invoice
2. Add the [`it-sdi-v1`](https://docs.gobl.org/addons/it-sdi-v1) addon to enable Italian-specific validations and extensions

Detailed information about the SDI-specific extensions and validations can be found in:

* [Italy SDI FatturaPA v1.x Addon Documentation](https://docs.gobl.org/addons/it-sdi-v1)
* [Italy Tax Regime Documentation](https://docs.gobl.org/regimes/it)

Example invoices are provided below, or you can use the [GOBL Builder](https://build.gobl.org) to create custom invoices.

### How the Send step works

This step generates the FatturaPA XML and sends it to SDI through our integration partner. Upon successful completion, the XML file is attached to the invoice entry. The SDI service usually responds within seconds but may take up to 24 hours. While waiting, this step remains in a `QUEUED` state.

When the Send step completes, it returns one of three results:

* `OK` if successful
* `KO` for unrecoverable errors
* `SKIP` if the invoice was already sent

### Archiving (conservazione a norma)

Italian law requires issued electronic invoices to be preserved long-term through a certified archiving process known as *conservazione a norma*. Keeping a copy of the XML on your own systems is not enough — preservation must follow the rules set by the Italian authorities, which Invopop handles through its integration partner A-Cube.

Archiving is built into the standard Italy templates, so no extra setup is needed:

* The party registration workflow includes a step that enables archiving for the supplier. It requires the party to have a valid Italian tax ID. Re-running it on an already-enabled supplier reports `SKIP`.
* The send invoice workflow includes an archive step after the Send step. It preserves the exact FatturaPA file transmitted to SDI and attaches the preservation receipt to the invoice entry as `archive-receipt.pdf` and `archive-receipt.xml`, along with an indexed `archive-uuid` metadata field identifying the archived document.
* The **SDI import invoices** workflow from the [receiving guide](https://docs.invopop.com/guides/it-sdi-receiving.md) includes the same archive step after the Import step, so the invoices you receive are preserved too, recorded as received.

Preservation is asynchronous: the archive step stays `QUEUED` until the receipt is ready, then completes with `OK`. The receipt normally arrives within minutes but can take hours; the step keeps checking, less often as time goes on, and gives up only after several hours. If the preservation service fails partway through, the step retries from where it stopped without uploading the document again. Re-running it on an already-archived invoice reports `SKIP`, with nothing fetched or attached again.

## Example invoices

> [accordion] B2B Invoice
>
> In this example, we're issuing a standard B2B invoice from an Italian supplier to another Italian business customer.
>
> Notice:
>
> * both supplier and customer have their Partita IVA (VAT number) and Codice Fiscale properly specified,
> * the minimal version contains only essential fields; `gobl build` handles all calculations,
> * when running `gobl build`, the system automatically calculates totals, applies IVA rates, and normalizes the document according to SDI requirements,
> * the built version shows all calculated fields including tax breakdowns, line totals, payment terms, and final amounts,
> * the [`it-sdi-v1`](https://docs.gobl.org/addons/it-sdi-v1) addon validates the document structure for B2B transactions, and,
> * the invoice will be transmitted through the SDI system and delivered to the customer's designated channel.
>
> ```json SDI B2B Invoice theme={"system"}
> {
>   "$schema": "https://gobl.org/draft-0/bill/invoice",
>   "$regime": "IT",
>   "$addons": [
>     "it-sdi-v1"
>   ],
>   "series": "SAMPLE",
>   "code": "002",
>   "issue_date": "2023-05-21",
>   "currency": "EUR",
>   "tax": {
>     "prices_include": "VAT"
>   },
>   "supplier": {
>     "name": "Hotel California",
>     "tax_id": {
>       "country": "IT",
>       "code": "12345678903"
>     },
>     "addresses": [
>       {
>         "num": "102",
>         "street": "Via California",
>         "locality": "Palermo",
>         "region": "PA",
>         "code": "33213",
>         "country": "IT"
>       }
>     ],
>     "registration": {
>       "capital": "50000.00",
>       "currency": "EUR",
>       "office": "RM",
>       "entry": "123456"
>     },
>     "ext": {
>       "it-sdi-fiscal-regime": "RF01"
>     }
>   },
>   "customer": {
>     "name": "Mela S.r.l.",
>     "tax_id": {
>       "country": "IT",
>       "code": "13029381004"
>     },
>     "inboxes": [
>       {
>         "key": "it-sdi-code",
>         "code": "M5UXCR5"
>       }
>     ],
>     "addresses": [
>       {
>         "num": "23",
>         "street": "Via dei Mille",
>         "locality": "Firenze",
>         "region": "FI",
>         "code": "00100",
>         "country": "IT"
>       }
>     ]
>   },
>   "lines": [
>     {
>       "quantity": "1",
>       "item": {
>         "name": "Tassa di Soggiorno",
>         "price": "1.00"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "exempt",
>           "ext": {
>             "it-sdi-exempt": "N4"
>           }
>         }
>       ]
>     },
>     {
>       "quantity": "1",
>       "item": {
>         "name": "Camera Matrimoniale",
>         "price": "125.00"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "intermediate"
>         }
>       ]
>     }
>   ]
> }
>
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"type": "standard",
> 	"series": "SAMPLE",
> 	"code": "002",
> 	"issue_date": "2023-05-21",
> 	"currency": "EUR",
> 	"tax": {
> 		"prices_include": "VAT",
> 		"ext": {
> 			"it-sdi-document-type": "TD01",
> 			"it-sdi-format": "FPR12"
> 		}
> 	},
> 	"supplier": {
> 		"name": "Hotel California",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "12345678903"
> 		},
> 		"addresses": [
> 			{
> 				"num": "102",
> 				"street": "Via California",
> 				"locality": "Palermo",
> 				"region": "PA",
> 				"code": "33213",
> 				"country": "IT"
> 			}
> 		],
> 		"registration": {
> 			"capital": "50000.00",
> 			"currency": "EUR",
> 			"office": "RM",
> 			"entry": "123456"
> 		},
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF01"
> 		}
> 	},
> 	"customer": {
> 		"name": "Mela S.r.l.",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "13029381004"
> 		},
> 		"inboxes": [
> 			{
> 				"key": "it-sdi-code",
> 				"code": "M5UXCR5"
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "23",
> 				"street": "Via dei Mille",
> 				"locality": "Firenze",
> 				"region": "FI",
> 				"code": "00100",
> 				"country": "IT"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "1",
> 			"item": {
> 				"name": "Tassa di Soggiorno",
> 				"price": "1.00"
> 			},
> 			"sum": "1.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "exempt",
> 					"ext": {
> 						"it-sdi-exempt": "N4"
> 					}
> 				}
> 			],
> 			"total": "1.00"
> 		},
> 		{
> 			"i": 2,
> 			"quantity": "1",
> 			"item": {
> 				"name": "Camera Matrimoniale",
> 				"price": "125.00"
> 			},
> 			"sum": "125.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "intermediate",
> 					"percent": "10.0%"
> 				}
> 			],
> 			"total": "125.00"
> 		}
> 	],
> 	"totals": {
> 		"sum": "126.00",
> 		"tax_included": "11.36",
> 		"total": "114.64",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "exempt",
> 							"ext": {
> 								"it-sdi-exempt": "N4"
> 							},
> 							"base": "1.00",
> 							"amount": "0.00"
> 						},
> 						{
> 							"key": "standard",
> 							"base": "113.64",
> 							"percent": "10.0%",
> 							"amount": "11.36"
> 						}
> 					],
> 					"amount": "11.36"
> 				}
> 			],
> 			"sum": "11.36"
> 		},
> 		"tax": "11.36",
> 		"total_with_tax": "126.00",
> 		"payable": "126.00"
> 	}
> }
> ```

> [accordion] B2G Invoice
>
> In this example, we're issuing a B2G invoice from an Italian supplier to the Italian government.
>
> Notice:
>
> * both supplier and customer have their Partita IVA (VAT number) and Codice Fiscale properly specified,
> * the minimal version contains only essential fields; `gobl build` handles all calculations,
> * when running `gobl build`, the system automatically calculates totals, applies IVA rates, and normalizes the document according to SDI requirements,
> * the built version shows all calculated fields including tax breakdowns, line totals, payment terms, and final amounts,
> * the [`it-sdi-v1`](https://docs.gobl.org/addons/it-sdi-v1) addon validates the document structure for B2G transactions, and,
> * the invoice will be transmitted through the SDI system and delivered to the customer's designated channel.
>
> ```json SDI B2G Invoice theme={"system"}
> {
>   "$schema": "https://gobl.org/draft-0/bill/invoice",
>   "$regime": "IT",
>   "$addons": ["it-sdi-v1"],
>   "$tags": ["b2g"],
>   "series": "PA",
>   "code": "2026-001",
>   "issue_date": "2026-05-08",
>   "currency": "EUR",
>   "supplier": {
>     "name": "Esempio Fornitore SRL",
>     "tax_id": {
>       "country": "IT",
>       "code": "12345678903"
>     },
>     "ext": {
>       "it-sdi-fiscal-regime": "RF01"
>     },
>     "addresses": [
>       {
>         "num": "10",
>         "street": "Via Roma",
>         "locality": "Milano",
>         "region": "MI",
>         "code": "20121",
>         "country": "IT"
>       }
>     ],
>     "emails": [
>       {"addr": "amministrazione@esempio-fornitore.it"}
>     ]
>   },
>   "customer": {
>     "name": "Comune di Roma",
>     "tax_id": {
>       "country": "IT",
>       "code": "02438750586"
>     },
>     "addresses": [
>       {
>         "num": "1",
>         "street": "Piazza del Campidoglio",
>         "locality": "Roma",
>         "region": "RM",
>         "code": "00186",
>         "country": "IT"
>       }
>     ],
>     "inboxes": [
>       {
>         "key": "it-sdi-code",
>         "code": "UF9DN8"
>       }
>     ]
>   },
>   "lines": [
>     {
>       "quantity": "20",
>       "item": {
>         "name": "Servizi di consulenza informatica",
>         "price": "150.00",
>         "unit": "h"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "standard"
>         }
>       ]
>     },
>     {
>       "quantity": "1",
>       "item": {
>         "name": "Licenza software annuale",
>         "price": "1200.00"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "standard"
>         }
>       ]
>     }
>   ],
>   "payment": {
>     "instructions": {
>       "key": "credit-transfer",
>       "ext": {
>         "it-sdi-payment-means": "MP05"
>       },
>       "credit_transfer": [
>         {
>           "iban": "IT60X0542811101000000123456",
>           "name": "Banca Esempio SpA",
>           "bic": "BPMOIT22XXX"
>         }
>       ]
>     },
>     "terms": {
>       "due_dates": [
>         {
>           "date": "2026-06-07",
>           "percent": "100%"
>         }
>       ]
>     }
>   },
>   "notes": [
>     {
>       "key": "general",
>       "text": "Fattura emessa verso Pubblica Amministrazione tramite SDI. CIG: Z1A2B3C4D5 - CUP: F81B12000000001"
>     }
>   ]
> }
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"$tags": [
> 		"b2g"
> 	],
> 	"type": "standard",
> 	"series": "PA",
> 	"code": "2026-001",
> 	"issue_date": "2026-05-08",
> 	"currency": "EUR",
> 	"tax": {
> 		"ext": {
> 			"it-sdi-document-type": "TD01",
> 			"it-sdi-format": "FPA12"
> 		}
> 	},
> 	"supplier": {
> 		"name": "Esempio Fornitore SRL",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "12345678903"
> 		},
> 		"addresses": [
> 			{
> 				"num": "10",
> 				"street": "Via Roma",
> 				"locality": "Milano",
> 				"region": "MI",
> 				"code": "20121",
> 				"country": "IT"
> 			}
> 		],
> 		"emails": [
> 			{
> 				"addr": "amministrazione@esempio-fornitore.it"
> 			}
> 		],
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF01"
> 		}
> 	},
> 	"customer": {
> 		"name": "Comune di Roma",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "02438750586"
> 		},
> 		"inboxes": [
> 			{
> 				"key": "it-sdi-code",
> 				"code": "UF9DN8"
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "1",
> 				"street": "Piazza del Campidoglio",
> 				"locality": "Roma",
> 				"region": "RM",
> 				"code": "00186",
> 				"country": "IT"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "20",
> 			"item": {
> 				"name": "Servizi di consulenza informatica",
> 				"price": "150.00",
> 				"unit": "h"
> 			},
> 			"sum": "3000.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "general",
> 					"percent": "22.0%"
> 				}
> 			],
> 			"total": "3000.00"
> 		},
> 		{
> 			"i": 2,
> 			"quantity": "1",
> 			"item": {
> 				"name": "Licenza software annuale",
> 				"price": "1200.00"
> 			},
> 			"sum": "1200.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "general",
> 					"percent": "22.0%"
> 				}
> 			],
> 			"total": "1200.00"
> 		}
> 	],
> 	"payment": {
> 		"terms": {
> 			"due_dates": [
> 				{
> 					"date": "2026-06-07",
> 					"amount": "5124.00",
> 					"percent": "100%"
> 				}
> 			]
> 		},
> 		"instructions": {
> 			"key": "credit-transfer",
> 			"credit_transfer": [
> 				{
> 					"iban": "IT60X0542811101000000123456",
> 					"bic": "BPMOIT22XXX",
> 					"name": "Banca Esempio SpA"
> 				}
> 			],
> 			"ext": {
> 				"it-sdi-payment-means": "MP05"
> 			}
> 		}
> 	},
> 	"totals": {
> 		"sum": "4200.00",
> 		"total": "4200.00",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "standard",
> 							"base": "4200.00",
> 							"percent": "22.0%",
> 							"amount": "924.00"
> 						}
> 					],
> 					"amount": "924.00"
> 				}
> 			],
> 			"sum": "924.00"
> 		},
> 		"tax": "924.00",
> 		"total_with_tax": "5124.00",
> 		"payable": "5124.00"
> 	},
> 	"notes": [
> 		{
> 			"key": "general",
> 			"text": "Fattura emessa verso Pubblica Amministrazione tramite SDI. CIG: Z1A2B3C4D5 - CUP: F81B12000000001"
> 		}
> 	]
> }
> ```

> [accordion] Simplified Invoice (Fattura Semplificata)
>
> In this example, we're issuing a simplified invoice for a €49.00 restaurant bill to a private customer identified only by their codice fiscale.
>
> Notice:
>
> * `$tags` includes `simplified`, so `gobl build` sets the format to `FSM10` and the document type to `TD07`,
> * the customer has no name or address: an Italian `tax_id` without a code, plus their codice fiscale as an `it-fiscal-code` identity,
> * prices include VAT, and the total with VAT must stay within €400, which the [`it-sdi-v1`](https://docs.gobl.org/addons/it-sdi-v1) addon checks before the invoice is sent, and,
> * see [Simplified invoices](https://docs.invopop.com/guides/it-sdi-invoicing.md#simplified-invoices) for what else the format allows.
>
> ```json SDI Simplified Invoice theme={"system"}
> {
>   "$schema": "https://gobl.org/draft-0/bill/invoice",
>   "$regime": "IT",
>   "$addons": [
>     "it-sdi-v1"
>   ],
>   "$tags": [
>     "simplified"
>   ],
>   "series": "SAMPLE",
>   "code": "003",
>   "issue_date": "2026-10-01",
>   "currency": "EUR",
>   "tax": {
>     "prices_include": "VAT"
>   },
>   "supplier": {
>     "name": "Hotel California",
>     "tax_id": {
>       "country": "IT",
>       "code": "12345678903"
>     },
>     "addresses": [
>       {
>         "num": "102",
>         "street": "Via California",
>         "locality": "Palermo",
>         "region": "PA",
>         "code": "33213",
>         "country": "IT"
>       }
>     ],
>     "ext": {
>       "it-sdi-fiscal-regime": "RF01"
>     }
>   },
>   "customer": {
>     "tax_id": {
>       "country": "IT"
>     },
>     "identities": [
>       {
>         "key": "it-fiscal-code",
>         "code": "RSSGNN60R30H501U"
>       }
>     ]
>   },
>   "lines": [
>     {
>       "quantity": "2",
>       "item": {
>         "name": "Menu di lavoro",
>         "price": "18.50"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "intermediate"
>         }
>       ]
>     },
>     {
>       "quantity": "2",
>       "item": {
>         "name": "Vino della casa",
>         "price": "6.00"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "general"
>         }
>       ]
>     }
>   ]
> }
>
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"$tags": [
> 		"simplified"
> 	],
> 	"type": "standard",
> 	"series": "SAMPLE",
> 	"code": "003",
> 	"issue_date": "2026-10-01",
> 	"currency": "EUR",
> 	"tax": {
> 		"prices_include": "VAT",
> 		"ext": {
> 			"it-sdi-document-type": "TD07",
> 			"it-sdi-format": "FSM10"
> 		}
> 	},
> 	"supplier": {
> 		"name": "Hotel California",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "12345678903"
> 		},
> 		"addresses": [
> 			{
> 				"num": "102",
> 				"street": "Via California",
> 				"locality": "Palermo",
> 				"region": "PA",
> 				"code": "33213",
> 				"country": "IT"
> 			}
> 		],
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF01"
> 		}
> 	},
> 	"customer": {
> 		"tax_id": {
> 			"country": "IT"
> 		},
> 		"identities": [
> 			{
> 				"key": "it-fiscal-code",
> 				"code": "RSSGNN60R30H501U"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "2",
> 			"item": {
> 				"name": "Menu di lavoro",
> 				"price": "18.50"
> 			},
> 			"sum": "37.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "intermediate",
> 					"percent": "10.0%"
> 				}
> 			],
> 			"total": "37.00"
> 		},
> 		{
> 			"i": 2,
> 			"quantity": "2",
> 			"item": {
> 				"name": "Vino della casa",
> 				"price": "6.00"
> 			},
> 			"sum": "12.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "general",
> 					"percent": "22.0%"
> 				}
> 			],
> 			"total": "12.00"
> 		}
> 	],
> 	"totals": {
> 		"sum": "49.00",
> 		"tax_included": "5.53",
> 		"total": "43.47",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "standard",
> 							"base": "33.64",
> 							"percent": "10.0%",
> 							"amount": "3.36"
> 						},
> 						{
> 							"key": "standard",
> 							"base": "9.84",
> 							"percent": "22.0%",
> 							"amount": "2.16"
> 						}
> 					],
> 					"amount": "5.53"
> 				}
> 			],
> 			"sum": "5.53"
> 		},
> 		"tax": "5.53",
> 		"total_with_tax": "49.00",
> 		"payable": "49.00"
> 	}
> }
> ```

> [accordion] Stamp Duty Invoice (Marca da Bollo)
>
> This example matches the **B2B invoice** above but adds a **€2.00 Marca da bollo** (stamp duty) as a document-level charge.
>
> **Flat-rate scheme (*forfettario*):** taxpayers using the *regime forfettario* do **not** charge VAT on their invoices. When the document total goes **above €77.47**, they must account for **imposta di bollo**—typically by adding a **€2.00** stamp duty line, as in this sample. (Thresholds and rules can change; confirm with your adviser or the Agenzia delle Entrate if in doubt.)
>
> Notice:
>
> * the `charges` array includes an entry with `"key": "stamp-duty"`, amount `"2.00"`, and reason `Imposta di bollo`,
> * the minimal version is otherwise the same as the B2B example; `gobl build` recalculates totals including the charge,
> * the built version shows `totals.charge` and a higher `payable` / `total_with_tax` than the plain B2B invoice,
> * the [`it-sdi-v1`](https://docs.gobl.org/addons/it-sdi-v1) addon continues to validate the document for SDI transmission.
>
> ```json SDI Stamp duty invoice (Marca da Bollo) theme={"system"}
> {
>   "$schema": "https://gobl.org/draft-0/bill/invoice",
>   "$regime": "IT",
>   "$addons": [
>     "it-sdi-v1"
>   ],
>   "series": "SAMPLE",
>   "code": "002",
>   "issue_date": "2023-05-21",
>   "currency": "EUR",
>   "tax": {
>     "prices_include": "VAT"
>   },
>   "supplier": {
>     "name": "Hotel California",
>     "tax_id": {
>       "country": "IT",
>       "code": "12345678903"
>     },
>     "addresses": [
>       {
>         "num": "102",
>         "street": "Via California",
>         "locality": "Palermo",
>         "region": "PA",
>         "code": "33213",
>         "country": "IT"
>       }
>     ],
>     "registration": {
>       "capital": "50000.00",
>       "currency": "EUR",
>       "office": "RM",
>       "entry": "123456"
>     },
>     "ext": {
>       "it-sdi-fiscal-regime": "RF01"
>     }
>   },
>   "customer": {
>     "name": "Mela S.r.l.",
>     "tax_id": {
>       "country": "IT",
>       "code": "13029381004"
>     },
>     "inboxes": [
>       {
>         "key": "it-sdi-code",
>         "code": "M5UXCR5"
>       }
>     ],
>     "addresses": [
>       {
>         "num": "23",
>         "street": "Via dei Mille",
>         "locality": "Firenze",
>         "region": "FI",
>         "code": "00100",
>         "country": "IT"
>       }
>     ]
>   },
>   "lines": [
>     {
>       "quantity": "1",
>       "item": {
>         "name": "Tassa di Soggiorno",
>         "price": "1.00"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "exempt",
>           "ext": {
>             "it-sdi-exempt": "N4"
>           }
>         }
>       ]
>     },
>     {
>       "quantity": "1",
>       "item": {
>         "name": "Camera Matrimoniale",
>         "price": "125.00"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "intermediate"
>         }
>       ]
>     }
>   ],
>   "charges": [
>     {
>       "key": "stamp-duty",
>       "i": 1,
>       "amount": "2.00",
>       "reason": "Imposta di bollo"
>     }
>   ]
> }
>
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"type": "standard",
> 	"series": "SAMPLE",
> 	"code": "002",
> 	"issue_date": "2023-05-21",
> 	"currency": "EUR",
> 	"tax": {
> 		"prices_include": "VAT",
> 		"ext": {
> 			"it-sdi-document-type": "TD01",
> 			"it-sdi-format": "FPR12"
> 		}
> 	},
> 	"supplier": {
> 		"name": "Hotel California",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "12345678903"
> 		},
> 		"addresses": [
> 			{
> 				"num": "102",
> 				"street": "Via California",
> 				"locality": "Palermo",
> 				"region": "PA",
> 				"code": "33213",
> 				"country": "IT"
> 			}
> 		],
> 		"registration": {
> 			"capital": "50000.00",
> 			"currency": "EUR",
> 			"office": "RM",
> 			"entry": "123456"
> 		},
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF01"
> 		}
> 	},
> 	"customer": {
> 		"name": "Mela S.r.l.",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "13029381004"
> 		},
> 		"inboxes": [
> 			{
> 				"key": "it-sdi-code",
> 				"code": "M5UXCR5"
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "23",
> 				"street": "Via dei Mille",
> 				"locality": "Firenze",
> 				"region": "FI",
> 				"code": "00100",
> 				"country": "IT"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "1",
> 			"item": {
> 				"name": "Tassa di Soggiorno",
> 				"price": "1.00"
> 			},
> 			"sum": "1.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "exempt",
> 					"ext": {
> 						"it-sdi-exempt": "N4"
> 					}
> 				}
> 			],
> 			"total": "1.00"
> 		},
> 		{
> 			"i": 2,
> 			"quantity": "1",
> 			"item": {
> 				"name": "Camera Matrimoniale",
> 				"price": "125.00"
> 			},
> 			"sum": "125.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "intermediate",
> 					"percent": "10.0%"
> 				}
> 			],
> 			"total": "125.00"
> 		}
> 	],
> 	"charges": [
> 		{
> 			"i": 1,
> 			"key": "stamp-duty",
> 			"reason": "Imposta di bollo",
> 			"amount": "2.00"
> 		}
> 	],
> 	"totals": {
> 		"sum": "126.00",
> 		"charge": "2.00",
> 		"tax_included": "11.36",
> 		"total": "116.64",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "exempt",
> 							"ext": {
> 								"it-sdi-exempt": "N4"
> 							},
> 							"base": "1.00",
> 							"amount": "0.00"
> 						},
> 						{
> 							"key": "standard",
> 							"base": "113.64",
> 							"percent": "10.0%",
> 							"amount": "11.36"
> 						}
> 					],
> 					"amount": "11.36"
> 				}
> 			],
> 			"sum": "11.36"
> 		},
> 		"tax": "11.36",
> 		"total_with_tax": "128.00",
> 		"payable": "128.00"
> 	}
> }
> ```

> [accordion] B2B Invoice with Additional Fields
>
> In this example, we're issuing a comprehensive B2B invoice with additional optional fields such as ordering information, payment details, and document references.
>
> Notice:
>
> * this invoice demonstrates advanced SDI features like CIG/CUP codes, payment methods, and bank details,
> * the minimal version includes ordering and payment details; `gobl build` calculates all totals,
> * when running `gobl build`, the system validates all additional fields according to SDI specifications and calculates totals,
> * the built version shows the complete document with all calculated fields, tax breakdowns, and properly formatted additional information,
> * additional fields like `ordering`, `payment`, and document references are important for public administration invoices (B2G), and,
> * the addon ensures all optional fields are properly validated and formatted for SDI transmission.
>
> ```json SDI B2B Invoice with additional fields theme={"system"}
> {
>   "$schema": "https://gobl.org/draft-0/bill/invoice",
>   "$regime": "IT",
>   "$addons": [
>     "it-sdi-v1"
>   ],
>   "$tags": [
>     "freelance"
>   ],
>   "series": "SAMPLE",
>   "code": "001",
>   "issue_date": "2023-03-02",
>   "currency": "EUR",
>   "supplier": {
>     "name": "MªF. Services",
>     "tax_id": {
>       "country": "IT",
>       "code": "12345678903"
>     },
>     "people": [
>       {
>         "name": {
>           "given": "GIANCARLO",
>           "surname": "ROSSI"
>         }
>       }
>     ],
>     "addresses": [
>       {
>         "num": "1",
>         "street": "VIALE DELLA LIBERTÀ",
>         "locality": "ROMA",
>         "region": "RM",
>         "code": "00100",
>         "country": "IT"
>       }
>     ],
>     "emails": [
>       {
>         "addr": "billing@example.com"
>       }
>     ],
>     "telephones": [
>       {
>         "num": "999999999"
>       }
>     ],
>     "registration": {
>       "capital": "50000.00",
>       "currency": "EUR",
>       "office": "RM",
>       "entry": "123456"
>     },
>     "ext": {
>       "it-sdi-fiscal-regime": "RF02"
>     }
>   },
>   "customer": {
>     "name": "MARIO LEONI",
>     "tax_id": {
>       "country": "IT",
>       "code": "09876543217"
>     },
>     "people": [
>       {
>         "name": {
>           "prefix": "Dott.",
>           "given": "MARIO",
>           "surname": "LEONI"
>         }
>       }
>     ],
>     "inboxes": [
>       {
>         "key": "it-sdi-code",
>         "code": "M5UXCR5"
>       }
>     ],
>     "addresses": [
>       {
>         "num": "1",
>         "street": "VIALE DELI LAVORATORI",
>         "locality": "ROMA",
>         "region": "RM",
>         "code": "00100",
>         "country": "IT"
>       }
>     ],
>     "emails": [
>       {
>         "addr": "mario@example.com"
>       }
>     ]
>   },
>   "lines": [
>     {
>       "quantity": "20",
>       "item": {
>         "name": "Development of accounting software",
>         "price": "10.00",
>         "unit": "h"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "standard"
>         }
>       ]
>     }
>   ],
>   "payment": {
>     "instructions": {
>       "key": "credit-transfer",
>       "credit_transfer": [
>         {
>           "iban": "IT60X0542811101000000123456",
>           "name": "MªF. Services"
>         }
>       ]
>     },
>     "terms": {
>       "due_dates": [
>         {
>           "date": "2023-09-01",
>           "percent": "100%"
>         }
>       ]
>     }
>   }
> }
>
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"$tags": [
> 		"freelance"
> 	],
> 	"type": "standard",
> 	"series": "SAMPLE",
> 	"code": "001",
> 	"issue_date": "2023-03-02",
> 	"currency": "EUR",
> 	"tax": {
> 		"ext": {
> 			"it-sdi-document-type": "TD06",
> 			"it-sdi-format": "FPR12"
> 		}
> 	},
> 	"supplier": {
> 		"name": "MªF. Services",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "12345678903"
> 		},
> 		"people": [
> 			{
> 				"name": {
> 					"given": "GIANCARLO",
> 					"surname": "ROSSI"
> 				}
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "1",
> 				"street": "VIALE DELLA LIBERTÀ",
> 				"locality": "ROMA",
> 				"region": "RM",
> 				"code": "00100",
> 				"country": "IT"
> 			}
> 		],
> 		"emails": [
> 			{
> 				"addr": "billing@example.com"
> 			}
> 		],
> 		"telephones": [
> 			{
> 				"num": "999999999"
> 			}
> 		],
> 		"registration": {
> 			"capital": "50000.00",
> 			"currency": "EUR",
> 			"office": "RM",
> 			"entry": "123456"
> 		},
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF02"
> 		}
> 	},
> 	"customer": {
> 		"name": "MARIO LEONI",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "09876543217"
> 		},
> 		"people": [
> 			{
> 				"name": {
> 					"prefix": "Dott.",
> 					"given": "MARIO",
> 					"surname": "LEONI"
> 				}
> 			}
> 		],
> 		"inboxes": [
> 			{
> 				"key": "it-sdi-code",
> 				"code": "M5UXCR5"
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "1",
> 				"street": "VIALE DELI LAVORATORI",
> 				"locality": "ROMA",
> 				"region": "RM",
> 				"code": "00100",
> 				"country": "IT"
> 			}
> 		],
> 		"emails": [
> 			{
> 				"addr": "mario@example.com"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "20",
> 			"item": {
> 				"name": "Development of accounting software",
> 				"price": "10.00",
> 				"unit": "h"
> 			},
> 			"sum": "200.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "general",
> 					"percent": "22.0%"
> 				}
> 			],
> 			"total": "200.00"
> 		}
> 	],
> 	"payment": {
> 		"terms": {
> 			"due_dates": [
> 				{
> 					"date": "2023-09-01",
> 					"amount": "244.00",
> 					"percent": "100%"
> 				}
> 			]
> 		},
> 		"instructions": {
> 			"key": "credit-transfer",
> 			"credit_transfer": [
> 				{
> 					"iban": "IT60X0542811101000000123456",
> 					"name": "MªF. Services"
> 				}
> 			],
> 			"ext": {
> 				"it-sdi-payment-means": "MP05"
> 			}
> 		}
> 	},
> 	"totals": {
> 		"sum": "200.00",
> 		"total": "200.00",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "standard",
> 							"base": "200.00",
> 							"percent": "22.0%",
> 							"amount": "44.00"
> 						}
> 					],
> 					"amount": "44.00"
> 				}
> 			],
> 			"sum": "44.00"
> 		},
> 		"tax": "44.00",
> 		"total_with_tax": "244.00",
> 		"payable": "244.00"
> 	}
> }
> ```

> [accordion] VAT Exempt Invoice
>
> In this example, we're issuing an invoice for goods or services that are exempt from VAT (IVA).
>
> Notice:
>
> * the line item includes a tax with `"key": "exempt"` indicating this is a VAT-exempt transaction,
> * the minimal version omits the exemption code extension (`it-sdi-exempt`), which will be automatically added during `gobl build`,
> * when running `gobl build`, the system calculates totals with zero VAT and validates the exemption structure,
> * the built version shows the complete document with the exemption code extension (e.g., `"it-sdi-exempt": "N4"`) applied to the tax rate,
> * exemption codes must comply with SDI requirements—consult the [complete list of exemption reasons](https://docs.gobl.org/addons/it-sdi-v1#it-sdi-exempt) in the GOBL documentation,
> * common exemption codes include N4 (exempt), N3.1 (exports), N3.2 (intra-community supplies), and N6.x (reverse charge scenarios), and,
> * the SDI validates that exempt invoices include proper exemption codes before transmission.
>
> ```json SDI Exempt Invoice theme={"system"}
>
> {
>     "$schema": "https://gobl.org/draft-0/bill/invoice",
>     "$regime": "IT",
>     "$addons": [
>         "it-sdi-v1"
>     ],
>     "code": "INVOICE-001",
>     "supplier": {
>         "name": "Example IT Supplier S.r.l.",
>         "tax_id": {
>             "country": "IT",
>             "code": "12345678903"
>         },
>         "addresses": [
>             {
>                 "street": "Via Roma, 123",
>                 "locality": "Milan",
>                 "code": "20121",
>                 "country": "IT"
>             }
>         ],
>         "emails": [
>             {
>                 "addr": "info@supplier.it"
>             }
>         ]
>     },
>     "customer": {
>         "name": "Example IT Customer S.p.A.",
>         "tax_id": {
>             "country": "IT",
>             "code": "13029381004"
>         },
>         "addresses": [
>             {
>                 "street": "Via Dante, 456",
>                 "locality": "Rome",
>                 "code": "00100",
>                 "country": "IT"
>             }
>         ]
>     },
>     "lines": [
>         {
>             "quantity": "10",
>             "item": {
>                 "name": "Tax Exempt Service",
>                 "price": "100.00"
>             },
>             "taxes": [
>                 {
>                     "cat": "VAT",
>                     "key": "exempt"
>                 }
>             ]
>         }
>     ]
> }
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"type": "standard",
> 	"code": "INVOICE-001",
> 	"issue_date": "2026-07-08",
> 	"currency": "EUR",
> 	"tax": {
> 		"ext": {
> 			"it-sdi-document-type": "TD01",
> 			"it-sdi-format": "FPR12"
> 		}
> 	},
> 	"supplier": {
> 		"name": "Example IT Supplier S.r.l.",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "12345678903"
> 		},
> 		"addresses": [
> 			{
> 				"street": "Via Roma, 123",
> 				"locality": "Milan",
> 				"code": "20121",
> 				"country": "IT"
> 			}
> 		],
> 		"emails": [
> 			{
> 				"addr": "info@supplier.it"
> 			}
> 		],
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF01"
> 		}
> 	},
> 	"customer": {
> 		"name": "Example IT Customer S.p.A.",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "13029381004"
> 		},
> 		"addresses": [
> 			{
> 				"street": "Via Dante, 456",
> 				"locality": "Rome",
> 				"code": "00100",
> 				"country": "IT"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "10",
> 			"item": {
> 				"name": "Tax Exempt Service",
> 				"price": "100.00"
> 			},
> 			"sum": "1000.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "exempt",
> 					"ext": {
> 						"it-sdi-exempt": "N4"
> 					}
> 				}
> 			],
> 			"total": "1000.00"
> 		}
> 	],
> 	"totals": {
> 		"sum": "1000.00",
> 		"total": "1000.00",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "exempt",
> 							"ext": {
> 								"it-sdi-exempt": "N4"
> 							},
> 							"base": "1000.00",
> 							"amount": "0.00"
> 						}
> 					],
> 					"amount": "0.00"
> 				}
> 			],
> 			"sum": "0.00"
> 		},
> 		"tax": "0.00",
> 		"total_with_tax": "1000.00",
> 		"payable": "1000.00"
> 	}
> }
> ```

> [accordion] Credit Note
>
> In this example, we're issuing a credit note (nota di credito) to correct or refund a previously issued invoice.
>
> Notice:
>
> * the `type` field is set to `credit-note` to indicate this is a corrective document,
> * the `preceding` field references the original invoice being corrected,
> * the minimal version contains only essential correction details; `gobl build` calculates negative amounts,
> * when running `gobl build`, the system automatically calculates negative totals, IVA refunds, validates the credit note structure, and applies SDI rules,
> * the built version shows all calculated fields including negative amounts for the refund and proper tax adjustments,
> * credit notes must be properly linked to the original invoice and transmitted through SDI, and,
> * the SDI system validates the credit note format before accepting and forwarding it to the recipient.
>
> ```json SDI Credit Note theme={"system"}
> {
>   "$schema": "https://gobl.org/draft-0/bill/invoice",
>   "$regime": "IT",
>   "$addons": [
>     "it-sdi-v1"
>   ],
>   "$tags": [
>     "freelance"
>   ],
>   "type": "credit-note",
>   "series": "CN",
>   "code": "001",
>   "issue_date": "2024-10-09",
>   "currency": "EUR",
>   "preceding": [
>     {
>       "uuid": "0190c0ec-8109-756b-a4f0-88c4b542ab6e",
>       "type": "standard",
>       "issue_date": "2023-03-02",
>       "series": "SAMPLE",
>       "code": "001"
>     }
>   ],
>   "supplier": {
>     "name": "MªF. Services",
>     "tax_id": {
>       "country": "IT",
>       "code": "12345678903"
>     },
>     "people": [
>       {
>         "name": {
>           "given": "GIANCARLO",
>           "surname": "ROSSI"
>         }
>       }
>     ],
>     "addresses": [
>       {
>         "num": "1",
>         "street": "VIALE DELLA LIBERTÀ",
>         "locality": "ROMA",
>         "region": "RM",
>         "code": "00100",
>         "country": "IT"
>       }
>     ],
>     "registration": {
>       "capital": "50000.00",
>       "currency": "EUR",
>       "office": "RM",
>       "entry": "123456"
>     },
>     "ext": {
>       "it-sdi-fiscal-regime": "RF02"
>     }
>   },
>   "customer": {
>     "name": "MARIO LEONI",
>     "tax_id": {
>       "country": "IT",
>       "code": "09876543217"
>     },
>     "people": [
>       {
>         "name": {
>           "prefix": "Dott.",
>           "given": "MARIO",
>           "surname": "LEONI"
>         }
>       }
>     ],
>     "inboxes": [
>       {
>         "key": "it-sdi-code",
>         "code": "M5UXCR5"
>       }
>     ],
>     "addresses": [
>       {
>         "num": "1",
>         "street": "VIALE DELI LAVORATORI",
>         "locality": "ROMA",
>         "region": "RM",
>         "code": "00100",
>         "country": "IT"
>       }
>     ],
>     "emails": [
>       {
>         "addr": "mario@example.com"
>       }
>     ]
>   },
>   "lines": [
>     {
>       "quantity": "20",
>       "item": {
>         "name": "Development of accounting software",
>         "price": "10.00",
>         "unit": "h"
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "standard"
>         }
>       ]
>     }
>   ],
>   "payment": {
>     "instructions": {
>       "key": "credit-transfer",
>       "credit_transfer": [
>         {
>           "iban": "IT60X0542811101000000123456",
>           "name": "MªF. Services"
>         }
>       ]
>     }
>   }
> }
>
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"$tags": [
> 		"freelance"
> 	],
> 	"type": "credit-note",
> 	"series": "CN",
> 	"code": "001",
> 	"issue_date": "2024-10-09",
> 	"currency": "EUR",
> 	"preceding": [
> 		{
> 			"uuid": "0190c0ec-8109-756b-a4f0-88c4b542ab6e",
> 			"type": "standard",
> 			"issue_date": "2023-03-02",
> 			"series": "SAMPLE",
> 			"code": "001"
> 		}
> 	],
> 	"tax": {
> 		"ext": {
> 			"it-sdi-document-type": "TD04",
> 			"it-sdi-format": "FPR12"
> 		}
> 	},
> 	"supplier": {
> 		"name": "MªF. Services",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "12345678903"
> 		},
> 		"people": [
> 			{
> 				"name": {
> 					"given": "GIANCARLO",
> 					"surname": "ROSSI"
> 				}
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "1",
> 				"street": "VIALE DELLA LIBERTÀ",
> 				"locality": "ROMA",
> 				"region": "RM",
> 				"code": "00100",
> 				"country": "IT"
> 			}
> 		],
> 		"registration": {
> 			"capital": "50000.00",
> 			"currency": "EUR",
> 			"office": "RM",
> 			"entry": "123456"
> 		},
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF02"
> 		}
> 	},
> 	"customer": {
> 		"name": "MARIO LEONI",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "09876543217"
> 		},
> 		"people": [
> 			{
> 				"name": {
> 					"prefix": "Dott.",
> 					"given": "MARIO",
> 					"surname": "LEONI"
> 				}
> 			}
> 		],
> 		"inboxes": [
> 			{
> 				"key": "it-sdi-code",
> 				"code": "M5UXCR5"
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "1",
> 				"street": "VIALE DELI LAVORATORI",
> 				"locality": "ROMA",
> 				"region": "RM",
> 				"code": "00100",
> 				"country": "IT"
> 			}
> 		],
> 		"emails": [
> 			{
> 				"addr": "mario@example.com"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "20",
> 			"item": {
> 				"name": "Development of accounting software",
> 				"price": "10.00",
> 				"unit": "h"
> 			},
> 			"sum": "200.00",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "general",
> 					"percent": "22.0%"
> 				}
> 			],
> 			"total": "200.00"
> 		}
> 	],
> 	"payment": {
> 		"instructions": {
> 			"key": "credit-transfer",
> 			"credit_transfer": [
> 				{
> 					"iban": "IT60X0542811101000000123456",
> 					"name": "MªF. Services"
> 				}
> 			],
> 			"ext": {
> 				"it-sdi-payment-means": "MP05"
> 			}
> 		}
> 	},
> 	"totals": {
> 		"sum": "200.00",
> 		"total": "200.00",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "standard",
> 							"base": "200.00",
> 							"percent": "22.0%",
> 							"amount": "44.00"
> 						}
> 					],
> 					"amount": "44.00"
> 				}
> 			],
> 			"sum": "44.00"
> 		},
> 		"tax": "44.00",
> 		"total_with_tax": "244.00",
> 		"payable": "244.00"
> 	}
> }
> ```

> [accordion] Invoice after a documento commerciale
>
> In this example, a retail sale was first recorded with a [Smart Receipt](https://docs.invopop.com/guides/it-ticket.md) (*documento commerciale*) and the customer later asked for an invoice. The invoice is an ordinary SDI invoice that references the receipt issued for the same sale.
>
> Notice:
>
> * the line item carries an `attributes` entry with `type` `N.DOC.COMM`, the receipt's AdE document number in `text`, its progressive number in `amount`, and the receipt date in `date`,
> * the `it-sdi-v1` addon converts each item attribute into an `AltriDatiGestionali` block: `type` becomes `TipoDato`, `text` becomes `RiferimentoTesto`, `amount` becomes `RiferimentoNumero`, and `date` becomes `RiferimentoData`, which is the layout the AdE describes for invoices preceded by a receipt,
> * `type` is limited to 10 ASCII characters and `text` to 60 characters, and `amount` is rendered with at least two decimals, so `7816` arrives at SDI as `7816.00`,
> * the receipt's document number is the `ade-ref` stamp the Smart Receipts app adds to the receipt's header after the AdE accepts it,
> * `issue_date` is the day of the sale, because FatturaPA's `Data` comes from `issue_date` (`op_date` is not written to the XML), and without further tags `gobl build` sets the document type to `TD01`,
> * the Smart Receipt itself is not changed by this invoice, and your own VAT records must remove the invoiced amount from that day's *corrispettivi*. See [Invoice requested after a receipt](https://docs.invopop.com/guides/it-ticket.md#invoice-requested-after-a-receipt) for the full sequence.
>
> ```json SDI invoice after a documento commerciale theme={"system"}
> {
>   "$schema": "https://gobl.org/draft-0/bill/invoice",
>   "$regime": "IT",
>   "$addons": [
>     "it-sdi-v1"
>   ],
>   "series": "SAMPLE",
>   "code": "003",
>   "issue_date": "2025-05-22",
>   "op_date": "2025-05-20",
>   "currency": "EUR",
>   "tax": {
>     "prices_include": "VAT"
>   },
>   "supplier": {
>     "name": "Cleaning SRL",
>     "tax_id": {
>       "country": "IT",
>       "code": "74230430451"
>     },
>     "addresses": [
>       {
>         "num": "12",
>         "street": "Via Roma",
>         "locality": "Milano",
>         "region": "MI",
>         "code": "20121",
>         "country": "IT"
>       }
>     ],
>     "ext": {
>       "it-sdi-fiscal-regime": "RF01"
>     }
>   },
>   "customer": {
>     "name": "Mela S.r.l.",
>     "tax_id": {
>       "country": "IT",
>       "code": "13029381004"
>     },
>     "inboxes": [
>       {
>         "key": "it-sdi-code",
>         "code": "M5UXCR5"
>       }
>     ],
>     "addresses": [
>       {
>         "num": "23",
>         "street": "Via dei Mille",
>         "locality": "Firenze",
>         "region": "FI",
>         "code": "50123",
>         "country": "IT"
>       }
>     ]
>   },
>   "lines": [
>     {
>       "quantity": "3",
>       "item": {
>         "name": "Cleaning products",
>         "price": "137.50",
>         "attributes": [
>           {
>             "type": "N.DOC.COMM",
>             "text": "ACUBE2025/0000-7816",
>             "amount": "7816",
>             "date": "2025-05-20"
>           }
>         ]
>       },
>       "taxes": [
>         {
>           "cat": "VAT",
>           "rate": "standard"
>         }
>       ]
>     }
>   ]
> }
> ```
>
> ```json Built version theme={"system"}
> {
> 	"$schema": "https://gobl.org/draft-0/bill/invoice",
> 	"$regime": "IT",
> 	"$addons": [
> 		"it-sdi-v1"
> 	],
> 	"type": "standard",
> 	"series": "SAMPLE",
> 	"code": "003",
> 	"issue_date": "2025-05-22",
> 	"op_date": "2025-05-20",
> 	"currency": "EUR",
> 	"tax": {
> 		"prices_include": "VAT",
> 		"ext": {
> 			"it-sdi-document-type": "TD01",
> 			"it-sdi-format": "FPR12"
> 		}
> 	},
> 	"supplier": {
> 		"name": "Cleaning SRL",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "74230430451"
> 		},
> 		"addresses": [
> 			{
> 				"num": "12",
> 				"street": "Via Roma",
> 				"locality": "Milano",
> 				"region": "MI",
> 				"code": "20121",
> 				"country": "IT"
> 			}
> 		],
> 		"ext": {
> 			"it-sdi-fiscal-regime": "RF01"
> 		}
> 	},
> 	"customer": {
> 		"name": "Mela S.r.l.",
> 		"tax_id": {
> 			"country": "IT",
> 			"code": "13029381004"
> 		},
> 		"inboxes": [
> 			{
> 				"key": "it-sdi-code",
> 				"code": "M5UXCR5"
> 			}
> 		],
> 		"addresses": [
> 			{
> 				"num": "23",
> 				"street": "Via dei Mille",
> 				"locality": "Firenze",
> 				"region": "FI",
> 				"code": "50123",
> 				"country": "IT"
> 			}
> 		]
> 	},
> 	"lines": [
> 		{
> 			"i": 1,
> 			"quantity": "3",
> 			"item": {
> 				"name": "Cleaning products",
> 				"attributes": [
> 					{
> 						"type": "N.DOC.COMM",
> 						"text": "ACUBE2025/0000-7816",
> 						"amount": "7816",
> 						"date": "2025-05-20"
> 					}
> 				],
> 				"price": "137.50"
> 			},
> 			"sum": "412.50",
> 			"taxes": [
> 				{
> 					"cat": "VAT",
> 					"key": "standard",
> 					"rate": "general",
> 					"percent": "22.0%"
> 				}
> 			],
> 			"total": "412.50"
> 		}
> 	],
> 	"totals": {
> 		"sum": "412.50",
> 		"tax_included": "74.39",
> 		"total": "338.11",
> 		"taxes": {
> 			"categories": [
> 				{
> 					"code": "VAT",
> 					"rates": [
> 						{
> 							"key": "standard",
> 							"base": "338.11",
> 							"percent": "22.0%",
> 							"amount": "74.39"
> 						}
> 					],
> 					"amount": "74.39"
> 				}
> 			],
> 			"sum": "74.39"
> 		},
> 		"tax": "74.39",
> 		"total_with_tax": "412.50",
> 		"payable": "412.50"
> 	}
> }
> ```

## Technical details

> [accordion] SDI Response Codes and Statuses
>
> When the SDI step processes a document, it returns detailed status codes that provide information about the response from SDI:
>
> | Code | Description |
> | - | - |
> | `rejected` | **Notifica di scarto (NS)** SDI has rejected the invoice because it contains errors. |
> | `delivered` | **Ricevuta consegna (RC)** SDI has successfully delivered a B2B invoice to the recipient. |
> | `delivered-pa` | **Ricevuta consegna (RC)**  SDI has successfully delivered an invoice to a Public Administration (PA). |
> | `not-delivered` | **Mancata consegna (MC)** SDI could not deliver the invoice to the recipient. It is available to them on the AdE portal and you must tell them, see [MC in the status guide](https://docs.invopop.com/guides/it-sdi-status.md#business-invoices). |
> | `not-delivered` | **Attestazione trasmissione con impossibilità di recapito (AT)** SDI couldn't deliver an invoice to PA after 10 days. |
> | `accepted-pa` | **Notifica esito (NE)** A PA has decided to accept an invoice (outcome EC01). |
> | `rejected-pa` | **Notifica esito (NE)**  A PA has decided to reject an invoice (outcome EC02). |
> | `deadline-terms` | **Notifica decorrenza termini (DT)**  A PA didn't reply with acceptance or rejection within 15 days. SDI closes the process and the PA can no longer reject the invoice, see [DT in the status guide](https://docs.invopop.com/guides/it-sdi-status.md#public-administration-invoices). |
> | `invoice-error` | An error occurred during the acquisition of a notification. |
> | `sent` | The invoice has been submitted to SDI and is awaiting a response. |
> | `not-received` | The invoice was not received by the recipient. |
>
> Some SDI notifications (File metadati - MT, Esito committente - EC, Scarto esito committente - SE) don't directly change the code of the invoice.
>
> These codes map to different step results as follows:
>
> * **OK Result**: `delivered`, `not-delivered`, `not-received`, `accepted-pa`, `deadline-terms`
> * **KO Result**: `rejected`, `rejected-pa`, `invoice-error`
> * **QUEUED Result**: `sent`, `delivered-pa`
>
> When a step returns `QUEUED`, the workflow will check again later for updates from SDI.

## FAQ

> [accordion] How do I configure my workspace for Italian invoicing?
>
> Install the [Italy app](https://docs.invopop.com/apps/italy.md) for structured invoicing through SDI, or the Smart Receipts app for B2C-only AdE CF receipts. Run invoices through a workflow with the **Send invoice to SDI** step — see the [issuing guide](https://docs.invopop.com/guides/it-sdi-invoicing.md).

> [accordion] How do I issue a documento commerciale (scontrino)?
>
> Retail receipts (*documento commerciale*, commonly called *scontrino*) are not SDI invoices — they are reported to the tax authority as *corrispettivi* through a separate channel. Use the [Smart Receipts Italy app](https://docs.invopop.com/apps/smart-receipts-italy.md) for those, and see the [Smart Receipts issuing guide](https://docs.invopop.com/guides/it-ticket.md).

> [accordion] Where do I find Italy-specific GOBL documentation?
>
> See the [Italy tax regime in GOBL](https://docs.gobl.org/regimes/it) for tax categories, codice fiscale rules, and SDI-specific extensions. The [`it-sdi-v1`](https://docs.gobl.org/addons/it-sdi-v1) addon documents required FatturaPA fields.

> [accordion] Why is my invoice processing taking so long?
>
> The **Send invoice to SDI** step completes as soon as SDI accepts the file — it doesn't wait for SDI's verdict. What takes time is SDI's own processing: a rejection usually arrives within minutes, but delivery confirmations can take up to 5 days. Each verdict is recorded against the invoice as a status entry, so nothing is stuck while you wait. See the [status guide](https://docs.invopop.com/guides/it-sdi-status.md) for the full lifecycle.

> [accordion] How do I know if my invoice was delivered successfully?
>
> SDI confirms delivery with an `RC` (*ricevuta di consegna*) notification, recorded on the invoice as a status entry with the GOBL status `acknowledged`. A rejection arrives as `NS` with status `error`. Every notification and what it means is covered in the [status guide](https://docs.invopop.com/guides/it-sdi-status.md).

> [accordion] How do I test different SDI outcomes in the sandbox?
>
> Set a reserved *codice destinatario* on the customer — for example `SIMNS00` to simulate a rejection. The sandbox simulates SDI end to end and feeds back the notifications a real exchange would produce; any ordinary code resolves to a successful delivery. The full list of reserved codes is in the [issuing guide](https://docs.invopop.com/guides/it-sdi-invoicing.md#testing-in-the-sandbox).

> [accordion] How do I add codice fiscale and Partita IVA?
>
> Both Italian tax identifiers have their own place on a party. The *partita IVA* (VAT number) goes in `tax_id`, and the *codice fiscale* goes in `identities` under the key `it-fiscal-code`. A party may carry both.
>
> An Italian supplier always needs a *partita IVA*. An Italian customer needs at least one of the two — which one depends on who they are, covered in the [issuing guide](https://docs.invopop.com/guides/it-sdi-invoicing.md#identifying-the-customer).
>
> Here's an example showing both identifiers on a supplier:
>
> ```json Supplier with Partita IVA and Codice Fiscale theme={"system"}
> {
>     "supplier": {
>         "name": "MªF. Services",
>         "tax_id": {
>             "country": "IT",
>             "code": "12345678903"
>         },
>         "identities": [
>             {
>                 "key": "it-fiscal-code",
>                 "code": "MRTMTT91D08F205J"
>             }
>         ]
>     }
> }
> ```

> [accordion] How do I invoice a customer outside Italy?
>
> Send it through SDI as usual — an Italian supplier reports the invoice there whoever the customer is. SDI has no way to deliver outside Italy, though, so it won't reach the customer that way: send them their copy yourself, normally as a PDF. It's the same invoice travelling by two routes, and only the FatturaPA file is the legal one.

> [accordion] What if the customer has no tax ID at all?
>
> An Italian customer needs either a *partita IVA* or a *codice fiscale*. A customer outside Italy needs neither — their country is enough, so leave the code out rather than inventing a placeholder. See [identifying the customer](https://docs.invopop.com/guides/it-sdi-invoicing.md#identifying-the-customer).

> [accordion] How do I reference a receipt (documento commerciale) in an SDI invoice?
>
> Add an item attribute to the invoice line with `type` `N.DOC.COMM` and the receipt's identifier in `text`, its progressive number in `amount` and its date in `date`. The `it-sdi-v1` addon writes each item attribute as an `AltriDatiGestionali` block (`TipoDato`, `RiferimentoTesto`, `RiferimentoNumero`, `RiferimentoData`). The `type` is limited to 10 ASCII characters. See the "Invoice after a documento commerciale" example in the [issuing guide](https://docs.invopop.com/guides/it-sdi-invoicing.md#example-invoices).

More available in our [Italy FAQ](https://docs.invopop.com/faq/italy.md) section

***

> [accordion] 🇮🇹 Invopop resources for Italy
>
> | | |
> | - | - |
> | Compliance | [Invoicing compliance in Italy](https://docs.invopop.com/compliance/italy.md)   [Compliance timeline](https://docs.invopop.com/timelines/italy.md) |
> | Apps | [Italy](https://docs.invopop.com/apps/italy.md)  [SDI Italy](https://docs.invopop.com/apps/sdi-italy.md)  [Smart Receipts Italy](https://docs.invopop.com/apps/smart-receipts-italy.md) |
> | Guides | SDI — [Issuing invoices](https://docs.invopop.com/guides/it-sdi-invoicing.md) · [Status](https://docs.invopop.com/guides/it-sdi-status.md) · [Receiving invoices](https://docs.invopop.com/guides/it-sdi-reception.md) · [Archiving](https://docs.invopop.com/guides/it-sdi-archiving.md)  [SDI sending guide (legacy)](https://docs.invopop.com/guides/it-sdi-sending.md)  [SDI receiving guide (legacy)](https://docs.invopop.com/guides/it-sdi-receiving.md)  [Smart Receipts supplier registration](https://docs.invopop.com/guides/it-ticket-supplier.md)  [Smart Receipts issuing guide](https://docs.invopop.com/guides/it-ticket.md) |
> | FAQ | [Italy FAQ](https://docs.invopop.com/faq/italy.md) |
> | GOBL | [Italy Tax Regime](https://docs.gobl.org/regimes/it)   [Italy SDI FatturaPA Addon](https://docs.gobl.org/addons/it-sdi-v1)   [Italy AdE Ticket Addon](https://docs.gobl.org/addons/it-ticket-v1) |
> | GitHub | [gobl.fatturapa](https://github.com/invopop/gobl.fatturapa) |

> [card] [Participate in our community](https://community.invopop.com)
>
> Ask and answer questions about invoicing in Italy →


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.