Automazione dei flatfile: gestire le schede prodotto su più marketplace Amazon
Il sistema flatfile di Amazon è l’interfaccia più completa per gestire in blocco le schede prodotto di un catalogo ampio, ed è una delle meno documentate per chi opera su più marketplace. Ogni marketplace usa una versione diversa del modello, impone requisiti diversi per i campi e applica regole di convalida diverse, spesso per lo stesso prodotto nella stessa categoria. Gestire le schede su dieci marketplace a partire da un’unica fonte di dati prodotto richiede un approccio sistematico alle differenze tra i modelli, alla traduzione degli attributi e al ciclo di caricamento, convalida e correzione.
Questo articolo descrive il flusso di lavoro con i flatfile che usiamo per gestire cataloghi su più marketplace: come differiscono i modelli, dove l’automazione offre i maggiori vantaggi e dove l’intervento manuale resta inevitabile.
Che cosa sono i flatfile
Un flatfile è un foglio di calcolo con campi separati da tabulazioni che Amazon usa per elaborare la creazione e l’aggiornamento in blocco delle schede prodotto. Ogni riga rappresenta un prodotto. Ogni colonna rappresenta un attributo. Il modello, scaricato dalla sezione Catalogo > Aggiungi prodotti tramite caricamento di Seller Central, definisce le colonne obbligatorie e facoltative e i valori validi per ciascun campo.
Il sistema flatfile precede la SP-API Listings Items API e resta l’interfaccia principale per le modifiche in blocco all’interno di Seller Central. Sul versante API, Amazon ha dichiarato deprecati i feed delle schede prodotto in formato flatfile e XML a marzo 2024, con rimozione prevista per il 30 giugno 2025, a favore della Listings Items API basata su JSON e di JSON_LISTINGS_FEED; i caricamenti di flatfile tramite Seller Central non sono stati interessati. Per qualsiasi venditore con più di qualche decina di SKU su più marketplace, un flusso di lavoro in blocco è di fatto necessario e, nella nostra configurazione, il flatfile è l’interfaccia principale per la gestione del catalogo.
In realtà, però, la documentazione di Amazon sui flatfile è frammentata e spesso non aggiornata. La specifica più recente di un modello è il modello stesso, appena scaricato per il marketplace e la categoria da gestire. Affidarsi a modelli salvati in precedenza o a documentazione di sei mesi prima è un modo sicuro per incorrere in errori di caricamento.
Differenze tra i modelli dei marketplace
Le differenze strutturali tra i modelli dei marketplace sono maggiori di quanto si aspettino molti venditori quando iniziano a operare su più mercati. Non si tratta semplicemente di traduzioni degli stessi campi.
Il modello statunitense per l’abbigliamento in una determinata categoria può avere cinquanta colonne di attributi. L’equivalente tedesco può averne sessanta, inclusi campi senza un corrispettivo statunitense: dichiarazioni specifiche di conformità chimica richieste dalla normativa UE o obblighi di etichettatura energetica per determinati tipi di prodotti. Il modello giapponese può organizzare diversamente le varianti di taglia e colore, usando nomi dei temi di variazione che la versione statunitense non riconosce.
I valori validi per un campo spesso differiscono tra marketplace anche quando il nome del campo è identico. Il campo item_type_keyword accetta stringhe diverse su .com e .co.uk. I valori di color_name vengono convalidati rispetto a un elenco specifico del marketplace; un nome di colore valido negli Stati Uniti può essere rifiutato in Germania o in Giappone perché non corrisponde ai valori approvati per quel mercato. Questi rifiuti non sono sempre chiari nel report degli errori: si riceve un errore generico sull’attributo anziché un’indicazione esplicita che il valore non è nell’elenco approvato.
Le versioni dei modelli vengono aggiornate senza preavviso. Amazon rilascia periodicamente nuove versioni per una categoria, aggiungendo campi obbligatori o deprecando quelli vecchi. Se carichi dati con una versione non più attuale, il caricamento può riuscire ma la scheda potrebbe non essere indicizzata correttamente, oppure alcuni attributi potrebbero essere ignorati senza segnalazioni. Scarichiamo modelli nuovi all’inizio di ogni aggiornamento significativo del catalogo, anziché riutilizzare quelli salvati.
Conversione dei sistemi di taglie
Per abbigliamento e calzature, la conversione dei sistemi di taglie è uno degli aspetti più laboriosi della gestione del catalogo su più marketplace. I sistemi statunitense, europeo, britannico e giapponese non sono direttamente equivalenti e le tabelle di conversione non sono uniformi tra tipi di prodotto.
Una scarpa da donna di taglia US 8 corrisponde in genere a UK 6 ed EU 39 nelle comuni tabelle di conversione (le tabelle dei marchi possono differire di mezza taglia), ma una camicia da donna di taglia media statunitense può corrispondere a EU 38 o 40, a seconda delle convenzioni del marchio. Non esiste una tabella di conversione universale. L’approccio corretto è mantenere una mappatura principale delle taglie per ogni tipo di prodotto e marchio, convalidata rispetto alla guida alle taglie del produttore specifico.
I campi Amazon size_name e size_system devono essere compilati correttamente insieme affinché la scheda venga visualizzata nei filtri di navigazione specifici del marketplace. Una scheda caricata con una taglia statunitense nel campo size_name, ma senza dichiarazione di size_system, può essere trattata come una stringa non formattata e, nella nostra esperienza, può non comparire nei risultati filtrati per taglia. La conferma del caricamento non lo rende sempre evidente: la scheda viene creata correttamente, ma il filtro per taglia non funziona.
Nel marketplace giapponese, in particolare, il sistema di taglie differisce da quello europeo e statunitense per molte categorie. Le taglie dell’abbigliamento giapponese usano un sistema numerico distinto. Le calzature usano un sistema basato sui centimetri. Il campo size_map_unit_of_measure era obbligatorio nei modelli giapponesi con cui abbiamo lavorato ed era assente negli equivalenti statunitensi ed europei: la sua mancanza provocava errori di elaborazione non segnalati quando si riutilizzavano i modelli tra mercati. I nomi dei campi variano in base al tipo di prodotto e alla versione del modello: verifica quindi le intestazioni delle colonne e i valori validi nel modello che scarichi davvero.
Limiti delle parole chiave del backend
Le parole chiave del backend, cioè i termini di ricerca inviati nel campo generic_keyword, hanno limiti di caratteri diversi tra marketplace, e varia anche il tipo di limite applicato.
Amazon.com impone un limite di 249 byte al campo generic_keyword complessivo. Anche Amazon.de applica un limite in byte, ma il testo tedesco contiene più caratteri multibyte dell’inglese: una stringa che rientra in inglese nel limite in byte statunitense può quindi superare il limite in byte tedesco dopo la traduzione. Amazon.co.jp applica limiti che interagiscono con la codifica dei caratteri giapponesi: un singolo kanji occupa tre byte in UTF-8, perciò la capacità effettiva delle parole chiave in giapponese è molto inferiore a quanto il limite in byte lascia intendere se misurato in caratteri latini.
In realtà, però, il limite delle parole chiave è una delle variabili con minore impatto sulle prestazioni delle schede su più marketplace. Abbiamo osservato che l’ottimizzazione eccessiva delle parole chiave del backend, riempiendo il campo fino al limite esatto di byte, offre rendimenti decrescenti rispetto all’ottimizzazione di titolo, punti elenco e descrizione visibili per ricerche in linguaggio naturale. I limiti in byte sono un vincolo da rispettare, non una leva da massimizzare.
L’approccio pratico è mantenere un insieme di parole chiave specifico per ogni prodotto e marketplace, dimensionato per rientrare nei limiti di quel mercato, e verificare il conteggio dei byte tramite codice anziché a vista. Una semplice funzione Python che codifica la stringa e ne misura la lunghezza in byte rispetto al limite del marketplace intercetta gli errori di troncamento prima del caricamento.
Il flusso di automazione
L’idea alla base dell’automazione dei flatfile è che le differenze tra marketplace sono soprattutto strutturali, non semantiche. Il prodotto è lo stesso: dimensioni, materiali, uso previsto e caratteristiche principali non cambiano. Cambia il modo in cui queste informazioni devono essere rappresentate nel formato del modello di ciascun marketplace.
Manteniamo un foglio principale di dati prodotto con tutti gli attributi in un formato neutro: dimensioni nel sistema metrico, taglie nel sistema originale del produttore, parole chiave nella lingua di origine e categorie mappate su una tassonomia interna neutra. I flatfile specifici dei marketplace vengono generati da questo foglio applicando un livello di trasformazione che gestisce le differenze strutturali di ogni mercato di destinazione.
Il livello di trasformazione è uno script, nel nostro caso scritto in Python, che associa ogni attributo principale alla colonna flatfile corrispondente per ciascun marketplace, applica le conversioni di taglia, traduce la tassonomia delle categorie nella struttura dei nodi di navigazione del marketplace e convalida i singoli campi prima di generare il file finale. I campi che richiedono una revisione manuale, come testi tradotti, dichiarazioni di conformità specifiche del marketplace e attributi normativi nazionali, vengono segnalati nell’output anziché compilati automaticamente.
Il ciclo di download, modifica e caricamento è semiautomatizzato. I download vengono eseguiti tramite script usando la SP-API Reports API, che espone GET_FLAT_FILE_OPEN_LISTINGS_DATA e tipi di report correlati. L’elaborazione del download, il confronto con il foglio principale e la generazione del file da caricare sono automatizzati. Il caricamento e la revisione del relativo report di elaborazione restano manuali, non perché automatizzarli sia impossibile, ma perché il costo di un errore in un caricamento su larga scala giustifica una revisione umana prima dell’invio dei file ad Amazon.
Modalità di errore comuni
Gli errori di caricamento si dividono in tre categorie: errori di convalida, errori di elaborazione ed errori non segnalati.
Gli errori di convalida sono i più semplici: il report di caricamento restituisce messaggi espliciti che identificano la riga e il campo interessati. Le cause più comuni sono valori non validi nei campi con vocabolario controllato (size_name, color_name, item_type_keyword), campi obbligatori mancanti per la versione specifica del modello e superamento dei limiti in byte nei campi delle parole chiave o delle descrizioni.
Gli errori di elaborazione si verificano quando il caricamento supera la convalida, ma la scheda non si aggiorna come previsto. Le cause comuni includono errori nelle relazioni tra varianti, come un ASIN figlio inviato senza il genitore corrispondente o un genitore con un tema di variazione incompatibile con gli attributi del figlio, e conflitti tra nodi di navigazione, quando il nodo inviato non corrisponde alla classificazione esistente di un ASIN già consolidato.
Gli errori non segnalati sono i più difficili da individuare. Il caricamento riesce, il report di elaborazione non mostra errori, ma la scheda si comporta in modo scorretto. Una taglia non compare nei filtri di navigazione. Un termine di ricerca non viene indicizzato. Una relazione tra varianti compare nel backend ma non viene visualizzata correttamente nella vetrina. Per rilevare questi errori occorre confrontare gli attributi delle schede pubblicate con i valori inviati tramite la Catalog Items API, anziché limitarsi a un controllo visivo della vetrina.
La difesa pratica contro gli errori non segnalati è una verifica dopo il caricamento: recuperare via API i dati delle schede pubblicate per ogni ASIN interessato entro ventiquattro ore dal caricamento, confrontarli con i valori inviati e segnalare le discrepanze. Questo passaggio non è complesso, ma distingue un processo di gestione del catalogo affidabile da uno che richiede controlli manuali continui per individuare modifiche inspiegate alle schede, mai annunciate da un report di errori.
Approfondimenti correlati
- Espandere Amazon FBA a nuovi marketplace: un modello basato sui dati — il modello di selezione dei mercati che precede le decisioni sulla gestione delle schede
- Costruire un data warehouse Amazon con FastAPI e TimescaleDB — come archiviamo e interroghiamo i dati del catalogo e delle prestazioni delle schede per orientare gli aggiornamenti