> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Struttura Dati SFTP

## 1. Introduzione

Questa documentazione descrive come strutturare i tuoi file di dati — **prodotti**, **ordini**, **resi** e dati correlati — all'interno del nostro ambiente SFTP una volta che il tuo spazio dedicato è stato provisioning.

Se gestisci più negozi, o hai più ambienti (prod, preprod, ecc.), crea una sottocartella separata per ciascuno (potrebbe anche trattarsi di brand diversi, paesi diversi, ecc.).

### Esempio di struttura directory

```
/root_space
    /shop_fr
    /shop_en
    /shop_it
```

***

## 2. Programma di Trasmissione dei Dati

I file di dati dovrebbero idealmente essere trasmessi **quotidianamente** tra:

* **02:00**
* **05:00**

Questa finestra temporale garantisce un'elaborazione e un'acquisizione dei dati ottimali.

***

## 3. Standard di Organizzazione dei File

All'interno di ogni directory del negozio, crea le seguenti cartelle:

* `products`
* `orders`
* `returns`
* `return_reasons` (opzionale)
* `misc` (opzionale)

**Note:**

* La cartella `return_reasons` viene utilizzata per i file di esportazione contenenti dati aggiuntivi sui resi, come i motivi forniti dai clienti. Queste esportazioni sono opzionali.
* La cartella `misc` può contenere file vari. Se desideri utilizzare questa cartella, discuti prima con noi la gerarchia e la struttura per garantire la compatibilità.

Ogni esportazione deve essere collocata nella cartella appropriata e **datata** utilizzando un nome file con timestamp.

### Esempio di formato nome file

```
products_2025-01-15T02-00-00.csv
```

***

## 4. Requisiti per il Contenuto delle Esportazioni

Una specifica dettagliata dei campi attesi, dei formati e dei vincoli per ciascun tipo di dataset è disponibile nella documentazione **Trasferimenti Dati: Template**.

**Requisiti principali per le esportazioni del catalogo prodotti:**

* Esporta **tutte le varianti del prodotto**, inclusi gli articoli esauriti
* Includi un campo **data di ultima modifica** per l'elaborazione incrementale
* Mantieni le informazioni complete sulle varianti per consentire un'analisi corretta delle taglie
* Aggiungi opzionalmente un flag di disattivazione per il controllo della presenza Kleep

Fai riferimento al template per le definizioni complete dei campi ed esempi.

***

## 5. Gestione dei Dati Ripetuti nelle Esportazioni

I record possono comparire legittimamente in più esportazioni giornaliere. Ad esempio, un determinato reso può essere incluso più volte in file diversi.

Il nostro sistema di acquisizione gestisce automaticamente la deduplicazione e elabora solo la **versione più recente** di ciascun record.

***

## 6. Linee guida per il Formato dei Dati

Tutte le esportazioni devono essere fornite in formato **CSV**.

I file Excel (`.xlsx`) sono sconsigliati poiché introducono inconsistenze di formattazione e possono complicare i flussi di lavoro di acquisizione automatizzata.

* **Datetime:** Usa il formato ISO 8601: `YYYY-MM-DDTHH:MM:SSZ`, esempio: `2025-01-15T14:30:00Z`
* **Codifica:** Codifica UTF-8 per tutti i campi di testo, eseguire correttamente l'escape dei caratteri speciali in CSV
* **Valori booleani:** Usa `true`/`false` (minuscolo) o `True`/`False`
* **Valori decimali:** Usa il punto (`.`) come separatore decimale. Esempio: `129.99` non `129,99`
* **Valori null:** Stringa vuota per i campi di testo opzionali mancanti nei CSV, usa null nei JSON

### Convenzione per i nomi dei file

***

Come specificato nella Documentazione sulla Struttura Dati SFTP, usa il seguente formato:

```
{data_type}_{timestamp}.csv
```

Esempi:

* `products_2025-01-15T02-00-00.csv`
* `orders_2025-01-15T02-00-00.csv`
* `returns_2025-01-15T02-00-00.csv`

***

## 7. Esportazione di Dati Storici

Se hai bisogno di fornire **dati storici** (ovvero dati che non fanno parte delle esportazioni giornaliere), puoi esportare fino a **un anno di record storici** per tutti i tipi di dati, inclusi:

* **Prodotti**
* **Ordini**
* **Resi**

I dataset storici possono essere trasmessi **tramite SFTP** o, se più comodo, **tramite un altro mezzo concordato**.

# Esempio di una struttura SFTP completa

```
/root_space
    /shop_fr
        /products
            products_2025-01-15T02-00-00.csv
            products_2025-01-16T02-00-00.csv
        /orders
            orders_2025-01-15T02-00-00.csv
            orders_2025-01-16T02-00-00.csv
        /returns
            returns_2025-01-15T02-00-00.csv
            returns_2025-01-16T02-00-00.csv
        /return_reasons
            return_reasons_2025-01-15T02-00-00.csv  (opzionale)
        /misc
            (opzionale, discuti la gerarchia con noi)

    /shop_en
        /products
        /orders
        /returns
        /return_reasons
        /misc

    /shop_it
        /products
        /orders
        /returns
        /return_reasons
        /misc

```

***