CAF Jesi - Specifiche File CSV

Versione: 1.0
Data: 24 Luglio 2025
Sistema: CAF Jesi - Carico Gestionale API
Documento: Specifiche tecniche formato CSV

📁 Nomenclatura File

Formato Nome File

PartitaIvaFornitore_DataDocumento_NumeroDocumento.csv

Componenti del Nome

PartitaIvaFornitore: Partita IVA del fornitore (11 cifre, solo numeri)
DataDocumento: Data del documento in formato YYYYMMDD
NumeroDocumento: Numero del documento (alfanumerico, senza spazi o caratteri speciali)

Esempi Validi

✅ 12345678901_20250724_DDT001.csv

✅ 98765432109_20250115_FAT2025001.csv

✅ 11223344556_20241231_BOL123ABC.csv

Esempi NON Validi

❌ 1234567890_20250724_DDT001.csv (P.IVA solo 10 cifre)

❌ 12345678901_2025-07-24_DDT001.csv (Data con trattini)

❌ 12345678901_20250724_DDT 001.csv (Spazi nel numero documento)

❌ ABC12345678_20250724_DDT001.csv (P.IVA con lettere)

📊 Struttura CSV

Formato File

Separatore: Punto e virgola (;)
Encoding: UTF-8
Header: Prima riga con nomi delle colonne
Quote: Campi con punto e virgola racchiusi tra virgolette doppie

Colonne Obbligatorie

Pos	Nome Colonna	Tipo	Obbligatorio	Descrizione
1	`PartitaIva_Fornitore`	string	✅	Partita IVA fornitore (11 cifre)
2	`Data_Documento`	date	✅	Data documento (YYYY-MM-DD)
3	`Numero_Documento`	string	✅	Numero identificativo documento
4	`Codice_Prodotto`	string	✅	Codice identificativo prodotto
5	`Quantita`	numeric	✅	Quantità prodotto (numero decimale)
6	`Importo_Netto`	numeric	✅	Importo netto in Euro (formato: 00.00)
7	`Aliquota_IVA`	numeric	✅	Aliquota IVA in percentuale (es: 22.00)
8	`Categoria_Prodotto`	string	❌	Categoria prodotto (BDF o altra)

Header CSV Richiesto

PartitaIva_Fornitore;Data_Documento;Numero_Documento;Codice_Prodotto;Quantita;Importo_Netto;Aliquota_IVA;Categoria_Prodotto

📋 Specifiche Dettagliate Campi

1. PartitaIva_Fornitore

Formato: Stringa numerica di 11 cifre
Validazione: Solo numeri, esattamente 11 caratteri
Esempio: 12345678901

2. Data_Documento

Formato: YYYY-MM-DD (ISO 8601)
Validazione: Data valida, non futura
Esempio: 2025-07-24

3. Numero_Documento

Formato: Stringa alfanumerica
Validazione: Massimo 50 caratteri, no spazi iniziali/finali
Caratteri permessi: A-Z, a-z, 0-9, trattino (-), underscore (_)
Esempio: DDT001, FAT2025-001, BOL_123

4. Codice_Prodotto

Formato: Stringa alfanumerica
Validazione: Massimo 50 caratteri
Caratteri permessi: A-Z, a-z, 0-9, trattino (-), underscore (_), punto (.)
Esempio: PROD001, ART-123.45, COD_ABC_001

5. Quantita

Formato: Numero decimale
Validazione: Maggiore di 0, massimo 2 decimali
Separatore decimale: Punto (.)
Esempio: 1, 2.50, 100.75

6. Importo_Netto

Formato: Numero decimale in Euro
Validazione: Maggiore o uguale a 0, massimo 2 decimali
Separatore decimale: Punto (.)
Esempio: 100.00, 1250.99, 0.50

7. Aliquota_IVA

Formato: Numero decimale (percentuale)
Validazione: Tra 0 e 100, massimo 2 decimali
Separatore decimale: Punto (.)
Valori comuni: 0.00, 4.00, 10.00, 22.00

8. Categoria_Prodotto (Opzionale)

Formato: Stringa
Validazione: Massimo 100 caratteri
Valori suggeriti: BDF, ALIMENTARI, BEVANDE, ALTRI
Default: Campo vuoto se non specificato

📄 Esempio File CSV Completo

Nome File

12345678901_20250724_DDT001.csv

Contenuto File

PartitaIva_Fornitore;Data_Documento;Numero_Documento;Codice_Prodotto;Quantita;Importo_Netto;Aliquota_IVA;Categoria_Prodotto
12345678901;2025-07-24;DDT001;PROD001;10.00;100.50;22.00;BDF
12345678901;2025-07-24;DDT001;PROD002;5.50;75.25;10.00;ALIMENTARI
12345678901;2025-07-24;DDT001;PROD003;1.00;25.00;22.00;
12345678901;2025-07-24;DDT001;PROD004;3.25;150.75;4.00;BEVANDE

✅ Regole di Validazione

Validazioni Nome File

P.IVA: Esattamente 11 cifre numeriche
Data: Formato YYYYMMDD, data valida
Numero: Solo caratteri alfanumerici, trattini, underscore
Estensione: Deve essere .csv

Validazioni Contenuto

Header: Deve corrispondere esattamente alla struttura richiesta
Righe: Almeno una riga di dati dopo l'header
Campi obbligatori: Non possono essere vuoti
Formati numerici: Devono utilizzare il punto come separatore decimale
Coerenza P.IVA: P.IVA nel nome file deve corrispondere a quella nelle righe

❌ Errori Comuni e Soluzioni

Errore	Descrizione	Soluzione
P.IVA non valida	Meno/più di 11 cifre	Utilizzare esattamente 11 cifre numeriche
Data errata	Formato non YYYYMMDD	Usare formato 20250724 senza separatori
Header mancante	Prima riga non è header	Inserire riga header con nomi colonne esatti
Formato numeri	Virgola invece di punto	Usare punto (.) come separatore decimale
P.IVA diversa	P.IVA file ≠ P.IVA righe	Mantenere coerenza tra nome file e contenuto

📊 CAF Jesi - Specifiche File CSV

Formato e Struttura Dati per Upload Carico Gestionale