# Creare fatture XRechnung da un file CSV o JSON

- 2026-11-17

Questo progetto pilota crea fatture XRechnung da dati di fattura invece che da PDF. Carica un file CSV o JSON in un’elaborazione in blocco, assegna le colonne, controlla le fatture in un’anteprima e avvia l’elaborazione. Il servizio legge il file senza IA, quindi ogni dato deve essere nel file.

## Dati di fattura invece dei PDF

Un file con fino a 500 fatture diventa un’elaborazione in blocco di file XRechnung.

In un’elaborazione in blocco per XRechnung puoi caricare un file CSV o JSON al posto dei PDF. Il servizio legge il file senza IA. Ogni dato viene dal file: nulla viene dedotto, completato o arrotondato. Paese, valuta, IVA, date e tutti i totali devono essere nel file.

Un’elaborazione contiene o PDF o fatture importate, non entrambi. Il progetto pilota crea solo XRechnung (UBL). L’elaborazione in blocco richiede un abbonamento Enterprise attivo.

> **Progetto pilota**: L’importazione è un progetto pilota. I file Excel non vengono letti direttamente: esporta prima il foglio come CSV UTF-8.

## Importare un file

1. Apri Profilo e poi Elaborazione in blocco, e scegli Importa CSV o JSON.
2. Scegli il file. Imposta il separatore decimale e il formato della data usati nel file.
3. Assegna le colonne. Una colonna il cui nome corrisponde a un campo della fattura, al suo numero BT o alla sua etichetta riceve un suggerimento. Ogni colonna con valori deve essere assegnata o ignorata.
4. Controlla le fatture nell’anteprima. Una fattura con rilievi non può essere importata: correggi il file, scegli il file corretto e aggiorna l’anteprima.
5. Conferma il controllo e scegli Aggiungi le fatture al lotto.
6. Leggi il controllo dei costi e avvia l’elaborazione, come per i PDF.

## Tipi di file

| File | Struttura |
| --- | --- |
| CSV | UTF-8 con una riga di intestazione. Separatore `,` `;` tabulazione o `|`, virgolette secondo la RFC 4180. È ammesso un byte order mark. |
| Record JSON piatti | Un array di oggetti con valori di testo o numerici. Ogni oggetto è una riga, e le sue chiavi sono le colonne. |
| JSON canonico | Un array di oggetti fattura strutturati, oppure `{"invoices": [...]}`. Non richiede l’assegnazione delle colonne. |

## Come le righe diventano fatture

- Una riga CSV o un record JSON piatto è una riga di fattura.
- Le righe con lo stesso numero di fattura (BT-1) formano una fattura. Devono concordare sui dati della fattura, per esempio il nome dell’acquirente.
- Una fattura da CSV o JSON piatto ha un solo riepilogo IVA. Invia le fatture con più categorie o aliquote IVA come JSON canonico.

## Numeri e date

| Valore | Regola |
| --- | --- |
| Separatore decimale | `.` o `,`. Con `,` il `.` raggruppa le migliaia. I numeri JSON usano sempre `.`. |
| Formato della data | `2026-11-13` (ISO) o `13.11.2026` |
| Importi in CSV | Al massimo due decimali |
| Quantità e prezzi | Al massimo dieci decimali |
| Ogni numero | Al massimo 15 cifre prima del separatore decimale |
| Identificativi come i CAP | Gli zeri iniziali restano |

## Quando una fattura resta in attesa

Una fattura ha un rilievo, e l’importazione resta in attesa, quando:

- le sue righe non concordano su un dato della fattura, per esempio due nomi dell’acquirente;
- un campo obbligatorio è vuoto, o un valore non si può leggere;
- i suoi totali non tornano (regole EN 16931 BR-CO-10, BR-CO-13, BR-CO-14, BR-CO-15 e BR-CO-16);
- un importo di riga (BT-131) differisce di più di un centesimo da quantità × prezzo unitario ÷ quantità di base del prezzo, su una riga senza sconti o maggiorazioni di riga;
- una categoria IVA diversa da `O` non ha aliquota (BT-119, BT-152);
- i dati non rispettano lo schema canonico della fattura.

## File che il servizio rifiuta

Il servizio rifiuta un file che potrebbe leggere in più di un modo:

- nomi di colonna vuoti o ripetuti;
- righe con più o meno celle dell’intestazione;
- chiavi JSON ripetute;
- `NaN`, `Infinity` e numeri con esponente;
- valori annidati nei record piatti, e campi sconosciuti nel JSON canonico.

## Limiti

| Limite | Valore |
| --- | --- |
| Dimensione del file | 2 MB |
| Fatture per file | 500 |
| Righe | 10.000 |
| Colonne | 100 |
| Profondità JSON | 32 |

## Fatturazione

Ogni fattura importata viene convertita, convalidata, addebitata e consegnata come una fattura PDF in un’elaborazione in blocco: una conversione per fattura rilasciata, prima dalle conversioni incluse, poi dai crediti API. Vedi il costo prima dell’avvio.

Prima dell’importazione non viene salvato nulla. Se ripeti un’importazione invariata, vengono riutilizzate le stesse fatture.

## File di esempio

L’esempio sintetico contiene tre fatture con dati inventati. Usa punti e virgola, virgole decimali e date come 13.11.2026. La fattura SYNTH-0002 ha due righe.

- [Scarica l’esempio CSV](/examples/structured-invoices.csv)

## Prossimi passi

L’elaborazione in blocco richiede un abbonamento Enterprise attivo.

- [Leggi la guida all’elaborazione in blocco](/developer-api/bulk-runs)
- [Inizia con Enterprise](/pricing)
- [Consulta la documentazione della External API V1](/developer-api)
