Introduzione ai feed JSON personalizzati
I feed JSON personalizzati consentono di distribuire i dati dei prodotti attraverso una struttura dati completamente personalizzata, adattata alle specifiche esigenze della vostra piattaforma di destinazione. Diversamente dai feed standardizzati, lo schema JSON personalizzato offre la massima flessibilità nella definizione dei campi, della gerarchia dei dati e della logica di sincronizzazione.
Questa documentazione spiega come configurare un feed con schema JSON personalizzato, mappare i campi del vostro catalogo ai campi della destinazione tecnica, e gestire l'integrazione dati in modo da garantire che ogni sincronizzazione trasmetta informazioni accurate e complete.
Struttura e configurazione dello schema JSON personalizzato
Lo schema JSON personalizzato definisce la forma e il contenuto dei dati che verranno inviati alla destinazione. A differenza di feed predefiniti, ogni campo e ogni livello di annidamento può essere configurato secondo le vostre necessità specifiche.
Elementi fondamentali della configurazione
La configurazione di un feed JSON personalizzato richiede:
- Definizione della struttura radice: il contenitore principale che contiene i vostri dati prodotto, solitamente un array di oggetti.
- Mappatura dei campi sorgente: associazione tra i campi del vostro catalogo interno e i nomi dei campi nello schema JSON di destinazione.
- Tipi di dato: specifica del tipo atteso per ogni campo (stringa, numero, booleano, array, oggetto).
- Validazione e trasformazione: regole per formattare, filtrare o trasformare i dati prima dell'invio.
Una configurazione tipica potrebbe avere questa struttura:
{
"products": [
{
"id": "SKU123",
"name": "Nome Prodotto",
"price": 29.99,
"currency": "EUR",
"availability": "in stock",
"description": "Descrizione dettagliata",
"image_link": "https://esempio.com/immagine.jpg",
"category": "Categoria Principale",
"brand": "Nome Marca"
}
]
}
Ogni campo deve essere mappato correttamente dalla vostra fonte dati al nome corrispondente nello schema di destinazione. La precisione della mappatura influisce direttamente sulla qualità dei dati ricevuti dalla piattaforma di distribuzione.
Mappatura dei campi e integrazione dati personalizzata
La mappatura campi è il processo che collega i vostri dati interni ai campi attesi dalla destinazione tecnica. Una mappatura errata causa il rifiuto dei dati, approvazioni parziali o listing incompleti presso i canali distributivi.
Principi di mappatura efficace
Identificazione univoca dei prodotti: il campo id (o equivalente identificativo) deve essere univoco, stabile nel tempo e coerente tra gli aggiornamenti. Se questo campo non è mappato correttamente, la destinazione non riconoscerà gli aggiornamenti successivi e creerà duplicati.
Campi obbligatori vs. opzionali: ogni destinazione ha requisiti minimi. I campi come title, price, link e availability sono generalmente obbligatori. Se mancano, il feed viene rifiutato o i prodotti non vengono approvati per la distribuzione.
Formato e coerenza dei dati: i prezzi devono essere numerici, le valute in formato ISO (EUR, GBP, USD), le disponibilità in valori predefiniti (in stock, out of stock, preorder). Incoerenze nei formati causano errori di parsing e fallimenti di sincronizzazione.
Campi categorici e tassonomie: se la destinazione richiede categorie specifiche (ad esempio, google_product_category), la mappatura deve convertire le vostre categorie interne nel formato atteso. Una categorizzazione imprecisa riduce la visibilità dei prodotti nei risultati di ricerca.
Tabella di riferimento per i campi comuni
| Campo | Tipo | Obbligatorio | Descrizione | Impatto su approvazione |
|---|---|---|---|---|
| id | Stringa | Sì | Identificativo univoco del prodotto | Rifiuto feed se mancante |
| title | Stringa | Sì | Nome del prodotto (max 150 car.) | Listing incompleto se assente |
| price | Numero | Sì | Prezzo in formato decimale | Rifiuto se non numerico |
| currency | Stringa | Sì | Codice valuta ISO (EUR, GBP, USD) | Errore sincronizzazione se non valido |
| link | URL | Sì | URL della pagina prodotto | Listing non cliccabile se assente |
| image_link | URL | Sì | URL immagine principale (JPG, PNG) | Rifiuto se formato non valido |
| availability | Stringa | Sì | Stato disponibilità (in stock, out of stock) | Listing sospeso se non valido |
| description | Stringa | No | Descrizione dettagliata (max 5000 car.) | Migliora ranking ricerca |
| brand | Stringa | No | Nome del marchio | Migliora ricerca per marca |
| google_product_category | Stringa | No | Categoria Google (ID numerico) | Migliora targeting pubblicitario |
| condition | Stringa | No | Condizione (new, refurbished, used) | Obbligatorio per alcuni canali |
| mpn | Stringa | No | Codice produttore | Facilita matching con cataloghi |
| gtin | Stringa | No | Codice EAN/UPC | Essenziale per matching catalogo |
Gestione delle destinazioni e sincronizzazione dati
Una volta definito lo schema JSON personalizzato, la gestione delle destinazioni determina come, quando e dove i dati vengono inviati.
Configurazione della destinazione tecnica
Ogni destinazione tecnica richiede:
- Endpoint API: l'URL dove il feed JSON deve essere inviato. Deve essere raggiungibile e rispondere ai metodi HTTP attesi (POST, PUT).
- Autenticazione: credenziali (API key, token Bearer, basic auth) per autorizzare le richieste.
- Frequenza di sincronizzazione: intervalli regolari (oraria, giornaliera, settimanale) per aggiornare i dati.
- Formato di risposta atteso: il sistema deve riconoscere i codici di stato HTTP e i messaggi di errore restituiti dalla destinazione.
- Gestione degli errori: logica di retry, notifiche, e fallback in caso di fallimento della sincronizzazione.
Ciclo di sincronizzazione dati
Ogni ciclo di sincronizzazione segue questi passaggi:
- Estrazione: i dati vengono estratti dal vostro catalogo interno.
- Trasformazione: i dati vengono mappati e trasformati secondo lo schema JSON personalizzato.
- Validazione: il JSON generato viene validato contro lo schema definito.
- Invio: il payload JSON viene inviato all'endpoint della destinazione.
- Verifica: la risposta della destinazione viene analizzata per confermare il successo o identificare errori.
- Logging: ogni sincronizzazione viene registrata per audit e troubleshooting.
Un fallimento in qualsiasi fase interrompe la sincronizzazione. Ad esempio, se la validazione rileva che il campo price non è numerico, l'intero feed viene scartato e la destinazione non riceve aggiornamenti.
Configurazione pratica e best practice
Definizione dello schema
Prima di implementare il feed JSON personalizzato, documentate chiaramente:
- La struttura completa del JSON (campi, tipi, annidamento).
- Quali campi del vostro catalogo interno corrispondono a quali campi dello schema.
- Le trasformazioni necessarie (ad esempio, conversione di valute, formattazione di date).
- I valori predefiniti per campi opzionali.
- Le regole di filtro (ad esempio, escludere prodotti non disponibili).
Mappatura e test
Per ogni campo della destinazione:
- Identificate il campo sorgente nel vostro sistema.
- Definite la trasformazione richiesta (se necessaria).
- Testate con un campione di prodotti reali.
- Verificate che il JSON generato sia valido (usate un validatore JSON online).
- Inviate un feed di test alla destinazione e controllate i risultati.
Gli errori di mappatura sono la causa principale di rifiuto dei feed. Dedicate tempo ai test prima di attivare la sincronizzazione in produzione.
Monitoraggio e manutenzione
Dopo l'attivazione:
- Monitorate i log di sincronizzazione per errori ricorrenti.
- Verificate periodicamente che i dati ricevuti dalla destinazione siano completi e corretti.
- Aggiornate la mappatura se la struttura del vostro catalogo cambia.
- Comunicate con il team della destinazione se i formati o i requisiti cambiano.
Una sincronizzazione regolare e senza errori garantisce che i vostri prodotti rimangono sempre aggiornati presso la destinazione.
Conclusione
I feed JSON personalizzati offrono massima flessibilità nella distribuzione dei dati, ma richiedono una configurazione accurata dello schema, una mappatura precisa dei campi e una gestione attenta delle destinazioni. Seguire i principi di mappatura efficace, testare accuratamente prima della produzione e monitorare continuamente la sincronizzazione sono le chiavi per mantenere un feed di qualità elevata e garantire l'approvazione dei vostri prodotti presso i canali distributivi.