> ## 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. # Italy issuing invoices guide > Issue electronic invoices through Italy's SDI system over Invopop's accredited channel. export const itImportStatusWorkflow = { "name": "Import invoice status", "description": "Record an SDI notification about an invoice you sent", "schema": "bill/status", "steps": [{ "id": "92d923d7-0d5a-4ee2-a7f9-f9fbd89f1650", "name": "Import status from SDI", "provider": "gov-it.sdi.import.status", "summary": "Turn the SDI notification into a status entry" }], "rescue": [] }; export const itSendInvoiceWorkflow = { "name": "Send invoice to SDI", "description": "Issue an invoice through Italy's SDI system", "schema": "bill/invoice", "steps": [{ "id": "019ed592-0763-79c1-9ca1-a2f7795e2b16", "name": "Add sequential code", "provider": "sequence.enumerate", "summary": "Dynamic · SDI · 000001", "config": { "name": "SDI", "padding": 6, "start": 1 } }, { "id": "019ed592-0763-793f-8fbe-bc977455d784", "name": "Sign envelope", "provider": "silo.close" }, { "id": "019ed592-0763-7ce4-beb0-2c95c77399d3", "name": "Send invoice to SDI", "provider": "gov-it.sdi.send.invoice", "summary": "Submit the FatturaPA document to SDI" }], "rescue": [{ "id": "019ed592-0763-7426-9bbf-6ed466d5749f", "name": "Set state", "provider": "silo.state", "summary": "Set state to `error`{.state .error}", "config": { "state": "error" } }] }; export const WorkflowDiagram = ({workflow}) => { const stateColors = { processing: "yellow", sent: "blue", received: "blue", registered: "green", completed: "green", error: "red" }; const StateChip = ({state, label}) => {label.charAt(0).toUpperCase() + label.slice(1)} ; const providerIcons = { "silo.state": "https://silo.invopop.com/images/status.svg", "silo.close": "https://silo.invopop.com/images/check-badge.svg", "silo.if": "https://assets.invopop.com/apps/silo/if.svg", "silo.folder": "https://silo.invopop.com/images/folder.svg", "silo.modify": "https://silo.invopop.com/images/modify.svg", "silo.correct": "https://silo.invopop.com/images/replace.svg", "silo.sleep": "https://assets.invopop.com/icons/sleep.svg", silo: "https://assets.invopop.com/apps/silo/icon.svg", "sequence.enumerate": "https://sequence.invopop.com/images/enumerate.svg", "transform.job.create": "https://transform.invopop.com/images/jobs.svg", webhook: "https://webhook.invopop.com/icon.svg", lookup: "https://lookup.invopop.com/icon.png", dropbox: "https://dropbox.invopop.com/icon.png", pdf: "https://pdf.invopop.com/file-pdf.svg", peppol: "https://assets.invopop.com/apps/peppol/icon.svg", ubl: "https://assets.invopop.com/apps/ubl/logo.svg", cii: "https://assets.invopop.com/apps/cii/logo.svg", "gov-dk": "https://assets.invopop.com/flags/dk.svg", "gov-fi": "https://assets.invopop.com/flags/fi.svg", "gov-fr": "https://assets.invopop.com/flags/fr.svg", "chorus-pro": "https://assets.invopop.com/apps/chroruspro/icon.svg", "gov-es": "https://assets.invopop.com/apps/gov-es/icon.svg", "gov-es.sii": "https://assets.invopop.com/apps/sii/icon.svg", "gov-es.ticketbai": "https://assets.invopop.com/apps/ticketbai/icon.svg", "gov-es.facturae": "https://assets.invopop.com/apps/facturae/icon.svg", verifactu: "https://assets.invopop.com/apps/verifactu/icon.svg", "gov-pl": "https://assets.invopop.com/apps/ksef/icon.svg", "gov-sa": "https://assets.invopop.com/apps/zatca/icon.svg", "gov-ar": "https://assets.invopop.com/apps/arca/icon.svg", "at-pt": "https://assets.invopop.com/apps/at-pt/icon.svg", "sat-mx": "https://assets.invopop.com/apps/sat-mexico/icon.svg", "sw-sapien": "https://assets.invopop.com/apps/sw-sapien/icon.svg", "sdi-it": "https://assets.invopop.com/apps/sdi-italy/icon.svg", "ticket-it": "https://assets.invopop.com/apps/agenzia-entrate/icon.svg", "nfe-br": "https://assets.invopop.com/apps/notas-fiscais-eletronicas-brazil/icon.svg", chargebee: "https://assets.invopop.com/apps/chargebee/icon.svg", stripe: "https://assets.invopop.com/apps/stripe/icon.svg", email: "https://assets.invopop.com/apps/email/icon.svg", cron: "https://assets.invopop.com/apps/cron/icon.svg", ilyda: "https://assets.invopop.com/apps/ilyda/icon.svg", invoicexpress: "https://assets.invopop.com/apps/invoicexpress/icon.svg", plemsi: "https://assets.invopop.com/flags/co.svg" }; const iconFor = provider => { const parts = (provider || "").split("."); for (let i = parts.length; i > 0; i--) { const url = providerIcons[parts.slice(0, i).join(".")]; if (url) return url; } return null; }; const StepIcon = ({provider}) => { const url = iconFor(provider); return {url ? : null} ; }; const renderSummary = summary => { const nodes = []; const re = /`([^`]+)`(\{[^}]*\})?/g; let last = 0; let m; let k = 0; while ((m = re.exec(summary)) !== null) { if (m.index > last) nodes.push(summary.slice(last, m.index)); const attrs = m[2] || ""; if (attrs.indexOf(".state") >= 0) { const state = (attrs.match(/\.state\s+\.([\w-]+)/) || [])[1] || m[1]; nodes.push(); } else if (attrs) { nodes.push( {m[1]} ); } else { nodes.push( {m[1]} ); } last = m.index + m[0].length; } if (last < summary.length) nodes.push(summary.slice(last)); return nodes; }; const NoteRow = ({text}) =>
{"// " + text}
; const renderSteps = (steps, counter) => (steps || []).map(step => { counter.n += 1; const n = counter.n; const branches = (step.next || []).filter(b => b.steps && b.steps.length > 0); return
{step.notes ? : null}
{n}
{step.name} {step.summary ? {renderSummary(step.summary)} : null}
{branches.length > 0 ?
{branches.map((branch, bi) =>
{branch.code || branch.status}
{renderSteps(branch.steps, counter)}
)}
: null}
; }); const counter = { n: 0 }; const wf = workflow || ({}); return
{renderSteps(wf.steps, counter)} {wf.rescue && wf.rescue.length > 0 ?
{renderSteps(wf.rescue, counter)}
: null}
; }; ## Introduction Electronic invoicing is mandatory for essentially every VAT-registered business in Italy. The *Sistema di Interscambio* (SDI) is the tax authority's central hub: it validates every invoice and delivers it to the buyer. The legal invoice is the cleared FatturaPA XML file. Invopop converts your [GOBL](https://docs.gobl.org) invoice into FatturaPA and transmits it over **its own accredited SDICoop channel**, registered with the tax authority in Invopop's name. Nothing sits between your workspace and SDI. Companion guides: [Status](/guides/it-sdi-status) for what SDI reports back about an invoice, [Receiving invoices](/guides/it-sdi-reception), and [Archiving](/guides/it-sdi-archiving). | - | Sandbox | Live | | ------------------ | ------------------------------------------------- | ------------------------------------------ | | **SDI exchange** | Simulated end to end, nothing leaves the platform | Real SDI over Invopop's accredited channel | | **Outcome** | You choose it, using a reserved recipient code | Decided by SDI and the recipient | | **Archiving** | Test preservation, no legal validity | Certified preservation | | **Legal validity** | None | The invoice is legally filed with SDI | The Italy app sends your invoices to the appropriate environment based on whether your current workspace is Sandbox or Live. ## Setup All of the following steps must be carried out from the [Invopop Console](https://console.invopop.com). 1. Navigate to **Configuration** → **Apps** 2. Find **Italy** in the app discovery list 3. Click **Connect** to activate The initial connection requires no configuration for sending invoices. This workflow numbers the invoice, seals the envelope, and submits it to SDI. Add to my workspace → Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view. ```json Example send invoice workflow theme={"system"} { "name": "Send invoice to SDI", "description": "Issue an invoice through Italy's SDI system", "schema": "bill/invoice", "steps": [ { "id": "019ed592-0763-79c1-9ca1-a2f7795e2b16", "name": "Add sequential code", "provider": "sequence.enumerate", "summary": "Dynamic · SDI · 000001", "config": { "name": "SDI", "padding": 6, "start": 1 } }, { "id": "019ed592-0763-793f-8fbe-bc977455d784", "name": "Sign envelope", "provider": "silo.close" }, { "id": "019ed592-0763-7ce4-beb0-2c95c77399d3", "name": "Send invoice to SDI", "provider": "gov-it.sdi.send.invoice", "summary": "Submit the FatturaPA document to SDI" } ], "rescue": [ { "id": "019ed592-0763-7426-9bbf-6ed466d5749f", "name": "Set state", "provider": "silo.state", "summary": "Set state to `error`{.state .error}", "config": { "state": "error" } } ] } ``` This workflow runs on each notification SDI sends about an invoice you issued, and records it as a status entry. Select it in the Italy app's configuration so incoming notifications run it automatically. Add to my workspace → ```json Example import invoice status workflow theme={"system"} { "name": "Import invoice status", "description": "Record an SDI notification about an invoice you sent", "schema": "bill/status", "steps": [ { "id": "92d923d7-0d5a-4ee2-a7f9-f9fbd89f1650", "name": "Import status from SDI", "provider": "gov-it.sdi.import.status", "summary": "Turn the SDI notification into a status entry" } ], "rescue": [] } ``` Add whatever your integration needs after the import step — calling a webhook, notifying your systems, or moving the invoice itself. ## 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 The step generates the FatturaPA XML, submits it to SDI, and attaches the transmitted file to the invoice entry. It completes as soon as SDI accepts the file for processing — it does **not** wait for SDI to decide what happens next, so a verdict that takes days never holds your workflow open. The step returns: * `OK` when SDI accepted the file. The result carries SDI's identifier for the submission (`sdi_id`), which every later notification about this invoice shares. * `KO` when the invoice couldn't be converted or SDI refused the submission outright. Acceptance is not delivery. An accepted file can still be rejected minutes later, and that arrives as a status. Invoices addressed to a public administration (`FPA12`) are not yet supported: they require a qualified electronic signature. Sending one raises a clear error rather than being rejected by SDI later. ## Invoice statuses SDI's verdict on an invoice arrives after the send step has finished, as a notification recorded against the invoice: delivered, rejected, undeliverable, or — for public administrations — accepted or refused by the buyer. Each notification and what it means for the invoice is covered in the [Status](/guides/it-sdi-status) guide. ## Archiving (conservazione a norma) Italian law requires issued electronic invoices to be preserved long-term through a certified process. Add the **Archive document** step after the send step to preserve each invoice as you issue it. See the [Archiving](/guides/it-sdi-archiving) guide for the full setup. ## Testing in the sandbox There is no public SDI test environment you can point a workflow at. In sandbox, the app plays SDI's part itself: it accepts the file, then feeds the status notifications a real exchange would produce back through the same intake the live channel uses. Your workflow cannot tell the difference, and nothing leaves the platform. ### Choosing the outcome You choose which outcome to rehearse by setting a reserved *codice destinatario* on the customer. In GOBL that is an inbox with the key `it-sdi-code`: ```json theme={"system"} { "customer": { "name": "Test Customer SRL", "tax_id": { "country": "IT", "code": "12345678903" }, "inboxes": [ { "key": "it-sdi-code", "code": "SIMNS00" } ] } } ``` | Recipient code | Simulated outcome | | --------------------- | ------------------------------------------------------------- | | *(any ordinary code)* | `RC` — delivered to the recipient | | `SIMNS00` | `NS` — SDI rejected the invoice | | `SIMMC00` | `MC` — accepted, but undeliverable | | `SIMAT00` | `AT` — delivery impossible, attestation issued | | `SIMDT00` | `RC`, then `DT` — delivered, then the response window expired | | `SIMEC1` | `RC`, then `NE`/`EC01` — delivered, then accepted | | `SIMEC2` | `RC`, then `NE`/`EC02` — delivered, then rejected | The codes are sized to real FatturaPA recipient-code lengths, so they pass validation. Any code not in this list — including a real customer's — resolves to a successful delivery. The sandbox simulates SDI's *responses*, not its validation. In practice this distinction rarely matters: the [`it-sdi-v1`](https://docs.gobl.org/addons/it-sdi-v1) addon validates invoices against the same rules SDI applies, so an invoice that builds cleanly should only rarely be rejected live — though edge cases can still slip through. ### Receiving your own invoices Send a sandbox invoice to a company you have [registered for reception](/guides/it-sdi-reception) and the app also loops it back to you as an inbound delivery, running your import workflow exactly as a live delivery would. This is the only way to receive an invoice in sandbox, and a convenient way to exercise sending and receiving in a single run. ## Example invoices 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" } } ``` 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" } ] } ``` 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" } } ``` 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" } } ``` 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" } } ``` 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" } } ``` ## FAQ Install the [Italy app](/apps/italy) 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](/guides/it-sdi-invoicing). 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](/apps/smart-receipts-italy) for those, and see the [Smart Receipts issuing guide](/guides/it-ticket). 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. 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](/guides/it-sdi-status) for the full lifecycle. 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](/guides/it-sdi-status). 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](/guides/it-sdi-invoicing#testing-in-the-sandbox). Invopop handles both Italian tax identification numbers in the supplier and customer sections of invoices: * **Partita IVA** (VAT number): Automatically extracted from the `tax_id/code` field. * **Codice Fiscale** (fiscal code): Must be specified as an identity with the key `it-fiscal-code`. Here's an example showing both identifiers in a supplier object: ```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" } ] } } ``` More available in our [Italy FAQ](/faq/italy) section *** | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Compliance | [Invoicing compliance in Italy](/compliance/italy)
[Compliance timeline](/timelines/italy) | | Apps | [Italy](/apps/italy)
[SDI Italy](/apps/sdi-italy)
[Smart Receipts Italy](/apps/smart-receipts-italy) | | Guides | SDI — [Issuing invoices](/guides/it-sdi-invoicing) · [Status](/guides/it-sdi-status) · [Receiving invoices](/guides/it-sdi-reception) · [Archiving](/guides/it-sdi-archiving)
[SDI sending guide (legacy)](/guides/it-sdi-sending)
[SDI receiving guide (legacy)](/guides/it-sdi-receiving)
[Smart Receipts supplier registration](/guides/it-ticket-supplier)
[Smart Receipts issuing guide](/guides/it-ticket) | | FAQ | [Italy FAQ](/faq/italy) | | 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) | Ask and answer questions about invoicing in Italy →