# Documentazione

Fattura.dev è il modo più semplice per inviare fatture elettroniche dai pagamenti Stripe. Trasforma ogni pagamento in una fattura in formato FatturaPA e la trasmette al Sistema di Interscambio (SdI) dell'Agenzia delle Entrate. Non c'è codice da scrivere: colleghi Stripe, inserisci la partita IVA e da quel momento è automatico.

## Avvio rapido

1. **Crea l'account** su [fattura.dev/accedi](/accedi) con Google o con la tua email.
2. **Collega Stripe.** Con un clic dove disponibile, oppure incollando una chiave API con restrizioni (sola lettura, più la creazione del webhook).
3. **Inserisci la partita IVA.** Denominazione e indirizzo vengono letti dal registro IVA europeo (VIES); scegli il regime fiscale e salva.

Le prime 10 fatture sono gratuite e non serve la carta.

## Quali incassi diventano un documento

| Evento Stripe | Cosa emettiamo |
|---|---|
| `invoice.paid` (Billing, abbonamenti, fatture Stripe) | Fattura `TD01` |
| `checkout.session.completed` in modalità `payment` | Fattura `TD01` |
| `charge.succeeded` senza Checkout né fattura Stripe (PaymentIntent diretto) | Fattura `TD01` |
| `charge.refunded` | Nota di credito `TD04` per l'importo rimborsato |
| `credit_note.created` (parte non rimborsata tramite Stripe) | Nota di credito `TD04` |

Ogni oggetto Stripe produce al massimo un documento: se Stripe riconsegna lo stesso evento non succede nulla. La data della fattura è il giorno dell'incasso, nel fuso orario italiano, e l'invio parte subito, ben dentro i 12 giorni previsti per la fattura immediata.

## I dati del cliente: dove li leggiamo

Per ogni dato usiamo il primo valore che troviamo, in quest'ordine: correzioni che hai inserito nella dashboard, dati dell'evento (fattura Stripe o sessione di Checkout), oggetto Customer.

| Dato in fattura | Dove lo leggiamo su Stripe |
|---|---|
| Denominazione | `business_name`, poi `name` |
| Partita IVA | Tax ID di tipo `eu_vat` (o altro `*_vat`); in alternativa metadata `partita_iva` |
| Codice fiscale | Tax ID di tipo `it_cf`; in alternativa campo personalizzato o metadata `codice_fiscale` |
| Indirizzo, CAP, comune, provincia, paese | Indirizzo di fatturazione (`address`) |
| Codice destinatario | Campo personalizzato o metadata `codice_destinatario` (anche `sdi`) |
| PEC | Campo personalizzato o metadata `pec` |

I nomi di campi e metadata non distinguono maiuscole, spazi e trattini bassi: `Codice Fiscale`, `codice_fiscale` e `codicefiscale` sono equivalenti.

Se il codice destinatario manca usiamo `0000000`: la fattura è valida e il cliente la trova nella propria area riservata dell'Agenzia delle Entrate. Per i clienti esteri usiamo `XXXXXXX`.

## Checkout: raccogli i dati giusti

Tre opzioni nella creazione della sessione bastano a raccogliere tutto ciò che serve:

```js
const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: [{ price: "price_123", quantity: 1 }],

  // Indirizzo di fatturazione: obbligatorio in ogni fattura.
  billing_address_collection: "required",

  // Partita IVA per i clienti con partita IVA.
  tax_id_collection: { enabled: true },

  // Codice fiscale per i privati che vogliono la fattura; codice destinatario per le aziende.
  custom_fields: [
    {
      key: "codice_fiscale",
      label: { type: "custom", custom: "Codice fiscale (se vuoi la fattura)" },
      type: "text",
      optional: true,
    },
    {
      key: "codice_destinatario",
      label: { type: "custom", custom: "Codice destinatario SdI" },
      type: "text",
      optional: true,
    },
  ],

  success_url: "https://esempio.it/grazie",
});
```

Con Stripe Billing o con le fatture Stripe, salva gli stessi dati sul Customer: indirizzo, Tax ID e, se servono, i metadata `codice_fiscale` e `codice_destinatario`.

Se a un incasso mancano dati obbligatori, il documento resta in stato **Mancano dati**: ti avvisiamo per email, completi i campi nella dashboard e parte. La correzione viene ricordata per i prossimi incassi dello stesso cliente.

## Clienti privati

Per le vendite online a privati la fattura non è obbligatoria, se non è richiesta dal cliente al più tardi al momento dell'acquisto. Per questo l'impostazione predefinita è: **emettiamo la fattura ai privati solo se forniscono il codice fiscale**. Gli altri incassi da privati compaiono in dashboard come *Non emessa*.

Puoi scegliere invece di fatturare sempre: in quel caso gli incassi da privati senza codice fiscale restano in attesa finché non lo inserisci. La certificazione dei corrispettivi per le vendite non fatturate resta a tuo carico: chiedi al tuo commercialista quale regime si applica alla tua attività.

## IVA: le regole applicate

L'importo incassato su Stripe è sempre il totale della fattura. Da quel totale scorporiamo l'IVA.

| Venditore | Cliente | Trattamento |
|---|---|---|
| Ordinario | Italia | IVA all'aliquota indicata da Stripe (Stripe Tax o tax rate); se Stripe non la indica, la tua aliquota predefinita (22%) |
| Ordinario | Azienda UE con partita IVA, servizi | Natura `N2.1`, dicitura «Inversione contabile» |
| Ordinario | Azienda UE con partita IVA, beni | Natura `N3.2`, non imponibile |
| Ordinario | Privato UE, senza IVA estera applicata da Stripe | IVA italiana |
| Ordinario | Privato UE, con IVA del paese di destinazione (OSS) | Nessuna fattura elettronica: documento *Non emessa* |
| Ordinario | Extra UE, servizi | Natura `N2.1`, dicitura «Operazione non soggetta» |
| Ordinario | Extra UE, beni | Natura `N3.1`, non imponibile |
| Forfettario | Italia e privati esteri | Natura `N2.2` con la dicitura di legge del regime forfettario |
| Forfettario | Azienda estera con partita IVA, servizi | Natura `N2.1` |

Quello che non sappiamo decidere con certezza non lo indoviniamo: ad esempio una vendita italiana a cui Stripe ha applicato IVA 0% resta in attesa di una tua verifica.

## Imposta di bollo

Sulle fatture senza IVA (nature `N2.1`, `N2.2`, `N4`) di importo superiore a 77,47 € indichiamo il bollo virtuale da 2 €. Il bollo non viene addebitato al cliente: resta a tuo carico e lo versi ogni trimestre dal portale *Fatture e Corrispettivi* dell'Agenzia delle Entrate, che lo calcola da solo.

## Rimborsi e note di credito

Quando rimborsi un pagamento su Stripe, anche in parte, emettiamo una nota di credito `TD04` collegata alla fattura originale, con le stesse aliquote in proporzione. Se la fattura originale non era stata emessa, non emettiamo nemmeno la nota di credito.

## Numerazione

Le fatture emesse da Fattura.dev usano una serie dedicata, con un prefisso che scegli tu, così non si sovrappone a quella delle fatture che emetti altrove:

```text
FD-2026-00001
FD-2026-00002
```

La numerazione è progressiva, senza buchi e riparte da 1 ogni anno. Il numero della fattura Stripe, quando esiste, è riportato nella causale.

## Stati di un documento

| Stato | Significato |
|---|---|
| Inviata | Trasmessa, in attesa della ricevuta del Sistema di Interscambio |
| Consegnata | Recapitata al cliente |
| Emessa, non recapitata | Valida, ma lo SdI non è riuscito a recapitarla: avvisa il cliente che la trova nella sua area riservata e mandagli una copia |
| Scartata | Non accettata: si considera non emessa. Correggila e reinviala entro 5 giorni, manterrà numero e data |
| Mancano dati | Servono dati del cliente o tuoi |
| Non emessa | Per questa vendita non serve una fattura elettronica |
| Prova | Pagamento in modalità test: XML generato, non trasmesso |

## Modalità test

Collega una chiave `rk_test_…` (o un account in sandbox) e fai un pagamento di prova: il documento compare in dashboard in stato **Prova**, con l'XML scaricabile, ma non viene trasmesso. Così controlli il risultato prima di andare in produzione.

## Conservazione

La conservazione a norma delle fatture non è inclusa. Puoi usare il servizio gratuito dell'Agenzia delle Entrate: accedi a *Fatture e Corrispettivi*, apri *Fatturazione elettronica e conservazione* e aderisci all'accordo di servizio. L'adesione va fatta da te, una volta sola.

Dalla dashboard puoi scaricare l'XML di ogni documento, e puoi indicare l'email del commercialista per fargli arrivare ogni XML appena trasmesso.

## Chi è responsabile

Fattura.dev genera e trasmette le fatture su tuo incarico, tramite un intermediario accreditato presso lo SdI. Il soggetto che emette la fattura resti tu, e resti responsabile del suo contenuto. Fattura.dev tratta i dati dei tuoi clienti come responsabile del trattamento, secondo l'[accordo sul trattamento dei dati](/dpa).

## Limiti attuali

- Solo incassi in euro.
- Niente fatture verso la Pubblica Amministrazione (formato `FPA12`).
- Niente fatture per le vendite a privati UE in regime OSS.
- Niente autofatture `TD17` per le commissioni di Stripe.
- Nessuna ritenuta d'acconto né cassa previdenziale.

## Usarlo da Claude o ChatGPT

Fattura.dev ha un connettore per gli assistenti AI. Una volta collegato, puoi chiedere in chat cose come «quante fatture ho inviato questo mese?», «quali fatture sono in sospeso e perché?» oppure «completa la fattura di Mario Rossi con questo codice fiscale e inviala».

Indirizzo del connettore:

```text
https://fattura.dev/api/mcp
```

Aggiungilo come connettore personalizzato in Claude o in ChatGPT e accedi con il tuo account Fattura.dev quando ti viene chiesto. In Claude Code:

```bash
claude mcp add --transport http fattura https://fattura.dev/api/mcp
```

L'assistente può vedere fatture, stato e riepilogo del mese, scaricare l'XML, e completare i dati di una fattura in sospeso per inviarla quando glielo chiedi tu. Non può vedere né modificare le credenziali di Stripe o l'abbonamento.

## Configurare con un assistente AI

Se usi Claude Code, Cursor o un altro assistente, incolla questo prompt nel tuo progetto:

```text
Il mio progetto incassa con Stripe e uso Fattura.dev (https://fattura.dev/docs) per
emettere le fatture elettroniche italiane. Fattura.dev legge i dati del cliente da Stripe.
Trova nel codice dove creo le Checkout Session e i Customer e fai in modo che:
1. le Checkout Session abbiano billing_address_collection: "required" e
   tax_id_collection: { enabled: true };
2. le Checkout Session abbiano due custom_fields di tipo text, facoltativi, con key
   "codice_fiscale" e "codice_destinatario";
3. quando creo o aggiorno un Customer salvo indirizzo e Tax ID (eu_vat per le aziende,
   it_cf per i privati) e, se li ho, i metadata codice_fiscale e codice_destinatario.
Non cambiare prezzi, prodotti o logica di pagamento.
```

## Domande frequenti

### Devo scrivere codice?

No. Il collegamento a Stripe e l'invio sono automatici. Il codice qui sopra serve solo a far raccogliere a Checkout i dati fiscali dei clienti, se non lo fa già.

### Funziona per i forfettari?

Sì. Scegli «Forfettario» nei dati fiscali: le fatture escono senza IVA, con natura `N2.2`, la dicitura di legge e il bollo virtuale quando è dovuto.

### Che cosa succede se lo SdI scarta una fattura?

Ti avvisiamo per email con il motivo. Correggi i dati dalla dashboard e la reinviamo con lo stesso numero e la stessa data.

### Posso mettere in pausa l'emissione?

Sì, dalle impostazioni. Mentre è in pausa i nuovi incassi non generano documenti.

### Come disdico?

Dal portale di fatturazione, raggiungibile dalla dashboard. La disdetta ha effetto alla fine del periodo già pagato.

### Fattura.dev è un prodotto di Stripe?

No. È un servizio indipendente che si collega al tuo account Stripe con permessi di sola lettura.