Files
Khaemhat/docs/wiki/Import-Export.md
T
Alby96andClaude Opus 5.5 4b759ee96e
CI / Build and test (SQLite) (pull_request) Canceled after 0s
CI / PostgreSQL 16 integration (pull_request) Canceled after 0s
CI / PostgreSQL 17 integration (pull_request) Canceled after 0s
CI / Docker image (pull_request) Canceled after 0s
CI / YAML check (pull_request) Canceled after 0s
docs: purchases and warehouse guide with screenshots, ADR 0035 and the 0.6.0 changelog (#61)
The Acquisti and Magazzino wiki pages now describe what M6 delivers, with real
screenshots of the demo company: stock, item movements, valuation, stock take, reorder
proposal, receipts, price differences, e-invoice import and pending self-invoices. The
user guide gains the buying and warehouse steps; the pages that said "arriva con M6"
(sales, items, dashboard, import, scheduled jobs, demo data) are brought up to date.
ADR 0035 records how documents post to the warehouse, the recomputed weighted average,
the invoice cost correction, the rebuild, the stock take, the base tables of existing
companies and where the Italian self-invoice and import rules live.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 22:24:43 +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 in M7; saldi e partite di apertura in M7 e M9) 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 (solo verifica fino a M7)

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
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 sarà precaricato con la contabilità (M7); l'importazione serve a chi vuole usare il piano del proprio commercialista o del gestionale precedente. Fino a M7 il file si verifica soltanto.

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 già nella mappatura e si importano con la contabilità (M7).

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). Giacenze e piano dei conti hanno per ora solo il modello. 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