Files
Khaemhat/docs/wiki/Import-Export.md
T
Alby96andClaude Opus 5.5 88de272b3e docs: avoid ambiguous Unicode and record Gitea planning in STATUS
Gitea flags en dash, multiplication sign, minus sign and single angle
quotes as confusable characters, which put a warning on most pages;
use plain equivalents (docs/SPEC.md stays untouched). STATUS.md now
lists the issue numbers per milestone, the items waiting for the owner
and the open specification questions tracked by issue #114.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:44:14 +01:00

7.5 KiB

Import/Export

Stato: bozza · Ultima revisione: 2026-11-10 · Versione software: non ancora rilasciata (milestone M4; saldi e partite di apertura in M12) Modulo di licenza: CORE (piano dei conti, saldi e partite: ACCT/FIN) · Livello richiesto: amministratore · Specifica: SPEC §11.7, §12.12

A cosa serve

La procedura guidata di Import/Export porta in Khaemhat i dati che arrivano da un altro gestionale o da un foglio di calcolo e li esporta in formati aperti. È lo strumento per l'avviamento di un'azienda: anagrafiche, articoli, listini, giacenze iniziali, piano dei conti, saldi iniziali e partite aperte.

Dove si trova

Amministrazione → Import/Export (titolo: Import / export dati). Ogni importazione si apre in una scheda propria (es. Import clienti).

Schermata

077 · Import/Export · procedura guidata CSV/XLSX/JSON

Mockup 077 — a sinistra i quattro passi della procedura guidata (Origine, Mappatura colonne, Validazione, Importazione) e le opzioni; a destra l'Anteprima e validazione con l'esito riga per riga; in alto Scarica report errori e Importa N righe (anteprima ridotta)

Formati

Formato Uso
CSV testo con separatore ; e codifica UTF-8 (formato più comune per gli scambi)
XLSX foglio Excel con le stesse colonne del CSV
JSON scambio completo fra installazioni Khaemhat (es. piano dei conti con voci di bilancio e causali)

Entità importabili

Entità Note
Anagrafiche (clienti, fornitori) verifica partita IVA (VIES per i soggetti UE), comune da CAP
Articoli
Listini
Giacenze iniziali quantità di apertura per deposito
Piano dei conti tracciato descritto sotto; verifica della coerenza gerarchica
Saldi iniziali saldi di apertura dei conti
Partite di apertura crediti e debiti aperti verso clienti e fornitori, con scadenze

Le colonne disponibili per ogni entità corrispondono ai campi della relativa scheda (vedi Anagrafiche, Articoli e listini, Magazzino, Contabilità, Scadenzario); i tracciati completi saranno pubblicati con i rispettivi moduli.

Come si importa

1. Origine

  1. Scegli l'Entità (es. Clienti).
  2. Carica il file. Khaemhat riconosce numero di righe, codifica e separatore (es. clienti.csv · 1.284 righe · UTF-8 · separatore ;).
  3. Imposta le opzioni:
Opzione Valori
Se il codice esiste Aggiorna il record esistente oppure lo salta (valori esatti definiti in sviluppo)
Codici mancanti Genera automatici secondo le regole dei codici automatici (vedi Tabelle azienda)
Verifica P.IVA (VIES per UE) controlla le partite IVA
Compila comune da CAP completa comune e provincia dal CAP

2. Mappatura colonne

Khaemhat abbina le colonne del file ai campi dell'entità (es. 12 di 14 colonne abbinate). Controlla gli abbinamenti proposti, correggi quelli sbagliati e indica le colonne da ignorare.

3. Validazione

Ogni riga viene controllata come se fosse inserita a mano. L'Anteprima e validazione mostra le prime righe con l'Esito:

Esito Significato Esempio
OK riga importabile
Avviso riga importabile con una correzione proposta CAP mancante: proposto 12100
Errore riga non importabile P.IVA non valida

Il filtro Tutte / Solo problemi mostra solo le righe con avvisi o errori. Scarica report errori scarica l'elenco delle righe problematiche con il motivo: correggile nel file di origine e reimportale.

4. Importazione

Il riepilogo indica quante righe verranno create e quante aggiornate. Premi Importa N righe: le righe con errori vengono escluse, le altre importate. L'esito finisce nel Log e ogni record creato ha il suo storico.

Consiglio: prova l'importazione su un'azienda clonata (vedi Istanza e database) prima di farla sull'azienda reale, soprattutto per saldi e partite di apertura.

Tracciato del piano dei conti

In Italia non esiste uno standard per lo scambio del piano dei conti, perciò Khaemhat definisce il proprio tracciato. Il piano standard per PMI è già precaricato con le tabelle di base; l'importazione serve a chi vuole usare il piano del proprio commercialista o del gestionale precedente.

CSV e XLSX

Separatore ;, una riga per conto, con le colonne:

codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag
Colonna Contenuto
codice codice gerarchico nella forma MM.CC.SSS (mastro, conto, sottoconto)
descrizione descrizione del conto
livello livello nella gerarchia (mastro, conto, sottoconto)
padre codice del conto padre (vuoto per i mastri)
natura natura del conto (es. patrimoniale/economico; valori ammessi definiti in sviluppo)
tipo tipo del conto (valori ammessi definiti in sviluppo)
voce_cee voce dello schema di bilancio CEE (artt. 2424/2425 c.c.)
riclassifica voce del bilancio riclassificato
flag indicatori del conto (partitario clienti/fornitori, rilevante IVA, chiusura automatica, movimentabile, attivo; codifica definita in sviluppo)

Esempio di righe (valori indicativi):

codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag
01;Immobilizzazioni;1;;…;…;;;
01.01;Immobilizzazioni immateriali;2;01;…;…;…;…;
01.01.001;Software;3;01.01;…;…;…;…;…

Il file XLSX usa le stesse colonne, nella prima riga del primo foglio.

JSON (khaemhat-coa.json)

Per l'export e l'import completo fra installazioni Khaemhat: contiene conti, voci di bilancio, causali contabili e mappature. È il formato da usare per copiare il piano dei conti da un'azienda all'altra.

Controlli in importazione

  • Coerenza gerarchica: ogni conto deve avere un padre esistente e un livello coerente con il codice.
  • Gli altri controlli (ad esempio codici duplicati o voci CEE inesistenti) seguono le regole del piano dei conti e saranno precisati in sviluppo.

Export

I dati si esportano negli stessi formati:

  • dalla procedura guidata, per le entità sopra elencate (l'obiettivo è che un file esportato si possa reimportare con lo stesso tracciato; dettagli definiti in sviluppo);
  • dalle griglie e dai report (CSV/XLSX/PDF), dal pulsante Genera file/esporta;
  • il piano dei conti completo in khaemhat-coa.json.

Gli export richiedono il flag utente Può esportare dati (vedi Utenti e permessi).

Domande frequenti

  • Il file ha la virgola come separatore. Usa il separatore ; (standard per i CSV in italiano, dove la virgola è il separatore decimale) oppure salva in XLSX.
  • Le lettere accentate appaiono sbagliate. Salva il CSV in UTF-8.
  • Posso importare documenti (fatture, DDT) da un altro gestionale? Non con questa procedura: le fatture elettroniche di acquisto si importano dall'XML SDI (vedi Acquisti e Fatturazione elettronica).

Pagine correlate

Dati di base e di esempio · Contabilità · Anagrafiche · Articoli e listini · Scadenzario · Tabelle azienda · Primi passi