Files
Khaemhat/docs/wiki/Import-Export.md
T
Alby96andClaude Opus 5.5 9e3ba92993 feat: general ledger, automatic posting, VAT settlement, withholdings and F24 (#62 #63 #64 #65 #66 #67 #68)
M7 adds the double-entry ledger so that the documents of M5 and M6 reach the
accounts without retyping, and the Italian VAT obligations can be prepared from
the same data.

- Chart of accounts on three levels with the Italian "PMI standard" model in the
  fiscal pack, journal templates with proposed lines, VAT registers; the chart
  import now writes the accounts and exports them (#62, ADR 0036).
- Journal entries: draft, posted, final with the libro giornale number,
  reversal; recurring entries with the nightly ledger.recurring job (#63).
- Documents post their entry inside the document transaction (PostingEngine,
  LedgerPoster) with VAT lines, open items and withholdings; a change rewrites
  the same entry, a cancellation removes or reverses it (#64, ADR 0037).
- VAT registers with final print, monthly or quarterly settlement with pro rata,
  interest, minimum and advance, confirmation with the LIQ entry, period lock
  and F24 line, LIPE file and F24 data (#65).
- Operated and suffered withholdings, CU data, stamp duty by quarter with the
  5,000 euro threshold, F24 summary with its payment entry (#66).
- Party ledgers, account ledgers, trial balance and libro giornale (#67).
- Demo accounting with the settlements of the past months confirmed and checked
  by hand in a test; wiki Contabilita, IVA, Fiscalita italiana completed with
  screenshots; CHANGELOG 0.7.0, STATUS, ADR 0036-0037 (#68).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 01:41:58 +01:00

14 KiB

Import/Export

Stato: completa per M4 · Ultima revisione: 2026-11-12 · Versione software: 0.4.0 (giacenze iniziali dalla 0.6.0, piano dei conti dalla 0.7.0; saldi e partite di apertura più avanti) Modulo di licenza: CORE (piano dei conti: ACCT) · Livello richiesto: amministratore, oppure permesso di scrittura o di export dell'entità · Specifica: SPEC §11.7, §12.12 · Decisione: ADR 0031

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, prezzi, giacenze iniziali e piano dei conti.

Dove si trova

Amministrazione → Import / export dati (indirizzo /amministrazione/import-export). Il tasto F1 apre questa pagina.

Schermata

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

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

Khaemhat 0.4.0 · mappatura colonne Khaemhat 0.4.0 — il passo Mappatura colonne con un CSV di clienti: le dieci colonne si abbinano da sole, anche P.IVA, Città e Prov.

Khaemhat 0.4.0 · anteprima e validazione Khaemhat 0.4.0 — l'anteprima dello stesso file: un comune dedotto dal CAP (avviso), un cliente nuovo e tre righe escluse (partita IVA mancante ed e-mail non valida, codice ripetuto, pagamento inesistente).

Formati

Formato Lettura Scrittura (export e modelli)
CSV (.csv, .txt) separatore ;, , o tabulazione (dedotto dalla riga di intestazione); UTF-8 con o senza BOM, altrimenti Windows-1252 ;, UTF-8 con BOM, numeri con la virgola, date gg/mm/aaaa, sì/no come VERO/FALSO
XLSX il primo foglio, intestazioni nella prima riga un foglio con le intestazioni bloccate
JSON un elenco di oggetti con le colonne come chiavi; per il piano dei conti anche khaemhat-coa.json lo stesso elenco (numeri e sì/no come valori JSON)

La prima riga contiene sempre le intestazioni. Le righe vuote si saltano. Al massimo 50.000 righe e 25 MB per file.

Valori accettati in tutte le colonne:

  • numeri all'italiana (1.234,56, € 12,5, 22 %) o con il punto decimale (1234.56, come li scrivono Excel e JSON);
  • date gg/mm/aaaa (anche g/m/aa, gg-mm-aaaa, gg.mm.aaaa), aaaa-mm-gg, aaaammgg o il numero di serie di una cella data di Excel;
  • sì/no come sì, si, x, 1, VERO, true oppure no, 0, FALSO, false;
  • le parole di una scelta (es. tipo_soggetto) senza badare a maiuscole, accenti, spazi e punteggiatura (Extra UE = extra-ue, P.A. = pa).

Entità e colonne

Le intestazioni si abbinano da sole quando sono uguali ai nomi qui sotto o a un nome simile (es. P.IVA, Partita IVA, piva → partita_iva; Città → comune). Le colonne con * servono per un record nuovo.

Clienti e fornitori

codice, ragione_sociale, nome, cognome, tipo_soggetto, partita_iva, codice_fiscale, rea, indirizzo, civico, cap, comune, provincia, nazione, telefono, email, pec, sito, codice_destinatario, categoria; per i clienti anche agente, pagamento, listino, sconto1, sconto2, fido, iban, note; per i fornitori pagamento, iban, note.

Colonna Valori
tipo_soggetto impresa, privato, pa, ue, extra-ue, forfettario (vuoto: impresa; con solo cognome e nome: privato)
nazione codice ISO a due lettere (IT, DE...)
categoria, agente, pagamento, listino il codice della tabella (vedi Tabelle azienda)
iban aggiunge il conto se non c'è già (il primo diventa predefinito)

Ragione sociale (o cognome e nome per un privato), partita IVA e gli altri controlli sono quelli della scheda (vedi Anagrafiche).

Articoli

codice, descrizione*, descrizione_estesa, tipo, categoria, um, iva_vendite, iva_acquisti, ean, nc8, marca, produttore, peso_netto, peso_lordo, a_magazzino, magazzino, scorta_minima, punto_riordino, lotto_riordino, prezzo, costo_standard, conto_ricavo, conto_costo, note.

Colonna Valori
tipo merce, servizio, spesa, descrittivo, cespite (vuoto: merce)
categoria, um, iva_vendite, iva_acquisti, magazzino il codice della tabella (PZ, 22, il codice del deposito)
a_magazzino sì/no; un articolo che non è merce non è mai a magazzino
prezzo il prezzo dell'articolo; i prezzi di listino si importano con l'entità Prezzi

Il codice generato usa la regola degli articoli, di solito {categoria}-{seq:0000}: in quel caso la categoria è obbligatoria. Unità alternative, codici alternativi, fornitori e sostitutivi restano quelli della scheda (vedi Articoli e listini).

Prezzi di listino e netti cliente

articolo*, listino, cliente, prezzo*, valido_dal. Ogni riga ha il listino oppure il cliente (prezzo netto), non entrambi. Stesso articolo, listino o cliente e data: il prezzo si sostituisce; una data nuova aggiunge un prezzo che vale da quel giorno, come nella griglia dei listini. Le righe senza errori si scrivono tutte insieme.

Giacenze iniziali

articolo*, deposito (vuoto: il deposito dell'articolo, poi quello predefinito), quantita* (maggiore di zero), costo_unitario (vuoto: costo medio, standard o ultimo costo dell'articolo). L'articolo deve essere merce gestita a magazzino e non può comparire due volte nello stesso deposito. Dalla 0.6.0 l'import scrive un movimento di magazzino per deposito con la causale APE (esistenza iniziale) alla data dell'import e lo conferma: giacenze e costo medio partono da lì (vedi Magazzino). Se la causale APE manca, le righe sono saltate con un messaggio: aggiungila con Aggiorna da tabelle base.

Piano dei conti

Vedi il tracciato più sotto.

Come si importa

1. Origine

  1. Scegli l'Entità.
  2. Imposta le opzioni:
Opzione Valori Entità
Se il codice esiste Aggiorna (le celle piene cambiano il record, le vuote lasciano ciò che c'è) oppure Salta la riga (avviso) clienti, fornitori, articoli, prezzi, piano dei conti
Codice mancante Genera automatico con le regole dei codici automatici (vedi Tabelle azienda) oppure Errore sulla riga clienti, fornitori, articoli
Verifica P.IVA su VIES (UE) controlla su VIES le partite IVA dei soggetti UE durante l'import (più lento) clienti, fornitori
Completa comune da CAP completa comune e provincia da un CAP con un solo comune, o il CAP da un comune con un solo CAP (avviso) clienti, fornitori
  1. Scegli il file. Il passo mostra nome, righe e dimensione (es. clienti_2026.csv · 1.284 righe · 37 KB).

Un codice scritto nel file per un record nuovo deve essere ammesso dalla regola dei codici (codice manuale): per mantenere i codici del gestionale precedente lascia attiva quell'opzione nella regola. Un codice già presente in una riga precedente del file è un errore; il codice di un'anagrafica di altro tipo (un fornitore fra i clienti) anche.

2. Mappatura colonne

Khaemhat abbina le colonne del file ai campi dell'entità (es. 14 di 16 colonne abbinate) e mostra per ognuna il valore della prima riga. Correggi gli abbinamenti con l'elenco Campo; scegli Ignora per le colonne da tralasciare. Un campo va su una sola colonna. Un avviso elenca i campi obbligatori non abbinati. Premi Verifica le righe.

3. Validazione

Ogni riga viene controllata come se fosse inserita a mano nella scheda. L'Anteprima e validazione mostra fino a 500 righe con l'Esito e il motivo accanto; le celle con un problema sono evidenziate.

Esito Significato Esempio
Nuovo / Aggiorna riga importabile
Avviso riga importabile con una correzione proposta o una nota Comune: dedotto dal CAP (Forlì)
Errore riga esclusa Partita IVA non valida, Il codice XX non esiste

Il filtro Tutte / Solo problemi mostra solo le righe con avvisi o errori. Scarica report errori scarica un CSV con riga, codice, colonna, esito e messaggio: correggi il file di origine e reimportalo. Mappatura torna al passo precedente.

4. Importazione

Importa N righe chiede conferma e scrive le righe senza errori, una alla volta come un salvataggio della scheda (i prezzi tutti insieme). Il riepilogo indica creati, aggiornati, saltati e righe con errori; ogni record ha il suo storico e l'esito finisce nel Log (sezione Sistema). Nuova importazione ricomincia.

Consiglio: prova l'importazione su un'azienda clonata (vedi Istanza e database) prima di farla sull'azienda reale.

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 è precaricato con la contabilità (dalla 0.7, vedi Contabilità); l'importazione serve a chi vuole usare il piano del proprio commercialista o del gestionale precedente. I conti nuovi si aggiungono; quelli che esistono si aggiornano se l'opzione Se il codice esiste è Aggiorna, altrimenti si saltano. Lo stesso tracciato si usa per esportare il piano dell'azienda.

CSV e XLSX

Una riga per conto, con le colonne:

codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag
Colonna Contenuto
codice* da 1 a 3 parti separate da punto: mastro, conto, sottoconto (01, 01.10, 01.10.001)
descrizione* descrizione del conto
livello 1, 2 o 3: il numero di parti del codice (se indicato deve corrispondere)
padre il codice senza l'ultima parte (se indicato deve corrispondere); deve essere nel file
natura attivo, passivo, costo, ricavo, ordine; obbligatoria sui mastri, ereditata dai sottoconti e uguale a quella del padre
tipo generico (vuoto), clienti, fornitori, banca, cassa, iva, erario
voce_cee voce dello schema di bilancio CEE (artt. 2424/2425 c.c.)
riclassifica voce del bilancio riclassificato
flag lettere: M movimentabile, I rilevante IVA, P con partitario clienti/fornitori, C chiusura automatica, X disattivato

Esempio:

codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag
01;Attivo;1;;attivo;;;;
01.10;Crediti verso clienti;2;01;;;;;
01.10.001;Clienti Italia;3;01.10;;clienti;CII1;;MP
01.20;Disponibilità liquide;2;01;;;;;
01.20.001;Banca;3;01.20;;banca;CIV1;;M

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

JSON (khaemhat-coa.json)

Per lo scambio completo fra installazioni Khaemhat:

{
  "format": "khaemhat-coa",
  "version": 1,
  "accounts": [ { "codice": "01", "descrizione": "Attivo", "natura": "attivo" } ],
  "statementLines": [],
  "journalTemplates": [],
  "mappings": []
}

accounts ha le stesse colonne del CSV. Voci di bilancio (statementLines), causali (journalTemplates) e mappature (mappings) si contano nella mappatura ma non si importano ancora: le causali si gestiscono in Contabilità → Causali.

Controlli

  • codice di 1-3 parti, livello e padre coerenti con il codice, padre presente nel file;
  • natura indicata sui mastri e uguale a quella del padre;
  • solo i conti senza sottoconti sono movimentabili (M su un conto con sottoconti è un errore; un sottoconto senza M è un avviso);
  • lettere di flag sconosciute e codici ripetuti sono errori.

Export e modelli

Il riquadro Esporta e modelli usa l'entità scelta in alto:

  • Formato: CSV, XLSX o JSON;
  • Scarica modello: il file con le sole intestazioni (in JSON un oggetto con i valori vuoti; per il piano dei conti l'oggetto khaemhat-coa);
  • Esporta: tutti i record con le stesse colonne dell'import, così il file si corregge e si reimporta (nome clienti-2026-11-12.csv). I codici delle tabelle sono esportati come codici.

L'export richiede il flag utente Può esportare dati e il permesso di export dell'entità (per le anagrafiche Esportare anagrafiche) (vedi Utenti e permessi). Le giacenze hanno per ora solo il modello; il piano dei conti si esporta per intero. Le griglie esportano anche dal proprio menu (CSV/XLSX).

Domande frequenti

  • Il file ha la virgola come separatore. Va bene: il separatore si deduce dalla riga di intestazione.
  • Le lettere accentate appaiono sbagliate. Khaemhat legge UTF-8 e, in alternativa, Windows-1252 (il CSV di Excel per l'Italia); con altre codifiche salva in UTF-8 o in XLSX.
  • Il codice del vecchio gestionale viene rifiutato. La regola dei codici di quell'archivio non ammette il codice manuale: abilitalo in Preferenze azienda → Codici automatici (/tabelle/preferenze), oppure scegli Genera automatico e togli la colonna.
  • Ho importato con errori: devo rifare tutto? No: correggi solo le righe del report e reimportale; con Aggiorna le righe già importate si aggiornano senza doppioni.
  • 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 · Magazzino · Tabelle azienda · Primi passi