Vai al contenuto principale

​
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