Anagrafica Prodotti
Il flusso prodotti è il più complesso in quanto coinvolge la maggior parte dei dati e richiede attenzione sulle tipologie del dato, soprattutto sui metafields configurati lato Shopify.
La singola chiamata di inserimento prodotti contiene al suo interno una semplificazione delle API di Shopify frutto di 6 anni di esperienza sull'applicativo. Questo adapter soprattutto integra all'interno circa 23 chiamate per ogni prodotto, che aumentano a seconda dei casi (nuove immagini, nuovi file, modifiche sui markets etc...).
Anagrafica prodotti Json
Informazioni sul tracciato relativo all'inserimento prodotti
- Le informazioni saranno nella lingua principale di Shopify
- I dati indispensabili per creare un prodotto (in draft come da procedura Puro/SBS) sono title e sku
- Per l'aggiornamento del prodotto è necessario SKU
- Gli attributi non presenti sui json non verranno aggiornati su Shopify (intendendo con attributi i campi base, i metafields e i files)
- Gli attributi con valore NULL o vuoto verranno sbiancati anche su Shopify
- L'attributo variants quando presente deve comprendere tutte le varianti (quelle non presenti sono rimosse)
- Ordinamento varianti può essere fatto implicito, tramite ordine sull'array oppure esplicito tramite il metadato "sortingNumber"
- L'attributo optionValues delle varianti contiene gli attributi che definiscono la configurabilità del prodotto (colore, taglia etc...). Possono essere al massimo 3 livelli di configurazione
- Le immagini possono essere associate al prodotto principale o alle varianti.
- In aggiornamento l'elenco immagini deve essere completo, le immagini mancanti verranno rimosse.
- Se nessuna immagine viene inviata, né sul prodotto principale né sulle varianti, la galleria immagini non viene aggiornata. (Questo soprattutto per evitare rimozioni erronee delle immagini)
- I metafield sono tipizzati già nel tracciato di esempio, il tipo deve essere mantenuto per preservare il successo dell'integrazione.
Per identificare un metafield, è possibile specificare una chiave semplice, che deve corrispondere alla chiave definita nel metafield,
oppure una chiave composta nel formato
namespace.key, dove namespace e chiave sono separati da un punto. Nel caso della chiave semplice, se presenti più definizioni con la stessa chiave (ma con namespace diversi), verrà considerata sempre la prima definizione trovata. - La sezione metaobjects contiene l'associazione con entità create su Shopify. E' possibile utilizzare l'handle del metaobject (es: "app-test-con-link" oppure "type.app-test-con-link" se si vuole specificare anche il type del metaobject) oppure tramite resourceId
- La sezione markets indica l'elenco dei mercati in cui un prodotto è visibile. Se il campo è assente o è definito come array vuoto, in fase di creazione il prodotto sarà visibile su tutti i mercati. Invece in fase di aggiornamento: se il campo è vuoto non viene apportata alcuna modifica, se definito come array vuoto il prodotto sarà visibile su tutti i mercati.
- Per quanto riguarda la parte di invetory item, supportiamo le seguenti proprietà: weight, weightUnit, harmonizedSystemCode, countryCodeOfOrigin, provinceCodeOfOrigin, costPerItem, isDigitalItem e inventoryTracked.
Le proprietà weight e weightUnit possono essere specificate sia a livello di prodotto sia a livello di variante; ad esempio, se il peso è lo stesso per tutte le varianti è possibile specificarlo solo a livello di prodotto senza doverlo riscrivere per ciascuna variante presente.
Nel caso dell'harmonizedSystemCode, del countryCodeOfOrigin, provinceCodeOfOrigin, costPerItem e isDigitalItem, se nella richiesta esistono delle varianti è necessario specificare tali dati a livello di variante.
La proprietà inventoryTracked può essere specificata sia a livello di prodotto sia a livello di variante; se valorizzata a livello di prodotto, verrà applicata a tutte le varianti che non lo specificano esplicitamente.
Il tracciamento dell'inventario viene calcolato basandosi sui campi isDigitalItem e inventoryTracked: se isDigitalItem ètrue, l'inventario non è mai tracciato a prescrindere dal valore di inventoryTracked. Se invece isDigitalItem èfalse, il tracciamento dell'inventrario dipende dal valore di inventoryTracked (setruel'inventario viene tracciato, altrimenti sefalseno)
(N.B. i valori che possono essere associati a weightUnit sono: 'g' e 'kg'. Se omesso, il valore di default è kg. Inoltre, il valore di default di isDigitalItem è 'false', ovvero il prodotto è considerato come fisico e non digitale. Il valore di default di inventoryTracked a livello di prodotto è 'true'.) - Le informazioni riguardanti la SEO possono essere inserite utilizzando i campi metaTitle e metaDescription.
- Il barcode, se specificato a livello di prodotto, viene inserito solo in assenza di varianti o nel caso di una singola variante. Se il prodotto presenta più varianti, è necessario assegnare il barcode a ciascuna variante specifica.
- È possibile configurare l'URL di reindirizzamento tramite il campo not-found-handle per gestire i casi di archiviazione o esclusione del prodotto da un catalogo (market), solo nel caso di prodotto attivo. Inoltre, aggiorna automaticamente il reindirizzamento del prodotto all'URL (handle) quando questo viene modificato. (N.B. Quando il prodotto viene archiviato e successivamente riattivato su Shopify, l'URL di reindirizzamento viene cancellato da Shopify)
- I tag possono essere gestiti in due modalità:
- Inserimento/Aggiornamento completo: i tag presenti su Shopify saranno sostituiti interamente da quelli specificati nel campo tags del tracciato.
- Inserimento/Aggiornamento parziale: i tag indicati nel campo tagsDomain vengono aggiunti o modificati senza alterare quelli esistenti, inseriti manualmente o da altri applicativi.
- Il prezzo (price) del prodotto può essere specificato in due modalità: a livello globale per il prodotto oppure in modo specifico per ciascuna variante. Nel caso in cui il prezzo non venga definito per una variante, verrà utilizzato quello indicato a livello globale per il prodotto, se presente. Tuttavia, se entrambe le informazioni sono disponibili o se sono specificate solo nella variante, quest'ultimo avrà priorità. Il solito principio si applica al campo compareAtPrice, seguendo la medesima logica di priorità tra variante e prodotto. (N.B. Il prezzo è un'informazione obbligatoria quando il prodotto è sincronizzato come 'active')
- È possibile aggiungere dei video alla sezione media del prodotto. Per maggiori dettagli sui formati di file supportati, dimensioni massime,
durata, risoluzione consigliata e altri criteri tecnici, si rimanda alla documentazione ufficiale di Shopify.
I video possono essere inclusi nei media del prodotto nelle seguenti modalità:
- Tramite URL di Youtube o Vimeo
- Tramite URL pubbliche dirette (es. link a file MP4)
- Gestione dei package: per la gestione dei package è necessario passare sempre l’ID del packaging da associare al prodotto o alle varianti.
L'ID può essere fornito sia come ID numerico sia come ID completo (ad esempio
gid://shopify/ShippingPackageV2/...). L’ID del packaging, se diverso da quello di default, deve essere sempre valorizzato: se viene specificato a livello di variante, viene utilizzato quello della variante; se invece è specificato solo a livello di prodotto, viene applicato automaticamente a tutte le varianti che non lo hanno specificato. Nel caso in cui siano presenti entrambi, l’ID definito a livello di variante ha priorità su quello del prodotto.
Tracciato
Tracciato per inserimento prodotti con esempio di metafield tipizzati.
{
"sku": "BGSM001C210",
"title": "Product Test 1 Con Varianti",
"barcode": "14785985742",
"handle": "product-product-1",
"not-found-handle": "/collections/all",
"description": "Description of product",
"type": "product-type",
"price": 15.99,
"compareAtPrice": 19.99,
"vendor": "SBS",
"tags": [
"tagprimo",
"tag2"
],
"markets": [
"81543987507",
"81544020275",
"81544053043",
"81544085811",
"82294604083"
],
"media": [
{
"alternativeText": "image test",
"url": "https://demo.sintra-soh.com/csv-import-images/BGSM001C005/BGSM001C005.jpg",
"filename": "BGSM001C005.jpg"
},
{
"alternativeText": "image test 1",
"url": "https://demo.sintra-soh.com/csv-import-images/BGSM001C005/BGSM001C005_1.jpg",
"filename": "BGSM001C005_1"
}
],
"metaobjects": {
"namespace.app": [
"type.app-test-senza-link",
"type.app-test-con-link"
],
"tech": "test-da-cancellare"
},
"files": {
"namespace.certification_file": "http://demo.sintra-soh.com/LdV/samplepdf.pdf",
"documents_file": "http://demo.sintra-soh.com/LdV/samplepdf_1.pdf",
"gallery_images_file": "http://demo.sintra-soh.com/ShippingLabels/1002-816-0.pdf",
"manual": "http://demo.sintra-soh.com/ShippingLabels/1006-867-0.pdf"
},
"metafields": {
"namespace.accessories_included": "value",
"addition_features": "value",
"attachment": "value",
"attachment_system": "value",
"audio_output": "value",
"audio_power": "value",
"audio_power_unit": "value",
"logistic_depth": 1,
"type_product": "[\"tipo1\",\"tipo2\"]",
"video": "https://www.youtube.com/watch?v=WqDiH5bnZ4s",
"volume_control_position": "value",
"warrentyupgrade": false
},
"variants": [
{
"sortingNumber": 1,
"sku": "BGSM001C210-1",
"barcode": "1478598574258",
"price": 12.99,
"compareAtPrice": 15.99,
"optionValues": {
"color": "Blue"
},
"media": [
{
"alternativeText": "image test 1 facoltativo",
"url": "http://demo.sintra-soh.com/csv-import-images/BGSM003C014/BGSM003C014.jpg",
"filename": "test.jpg"
},
{
"alternativeText": "image test 2 facoltativo",
"url": "http://demo.sintra-soh.com/csv-import-images/BGSM003C014/BGSM003C014_1.jpg"
}
],
"metafields": {
"subtitle": "value"
},
"files": {
"gallery_images_file": "http://demo.sintra-soh.com/ShippingLabels/1006-867-0.pdf"
},
"harmonizedSystemCode": "147856923",
"countryCodeOfOrigin": "IT",
"provinceCodeOfOrigin": "IT-52",
"costPerItem": 14.95,
"package": "123456789",
"isDigitalItem": true,
"inventoryTracked": false
},
{
"sortingNumber": 2,
"sku": "BGSM001C210-2",
"barcode": "1478598574259",
"optionValues": {
"color": "Lilac"
},
"media": [
{
"alternativeText": "lilla davanti",
"url": "http://demo.sintra-soh.com/csv-import-images/BGSM003C015/BGSM003C015.jpg"
},
{
"alternativeText": "lilla sopra",
"url": "http://demo.sintra-soh.com/csv-import-images/BGSM003C015/BGSM003C015_1.jpg"
}
],
"metafields": {
"subtitle": "value"
},
"files": {
"gallery_images_file": "http://demo.sintra-soh.com/ShippingLabels/1006-867-0.pdf"
},
"weight": "1.09",
"weightUnit": "kg",
"harmonizedSystemCode": "123456789",
"countryCodeOfOrigin": "IT",
"provinceCodeOfOrigin": "IT-52",
"costPerItem": 14.95,
"isDigitalItem": true,
"inventoryTracked": true
}
],
"weight": "1090",
"weightUnit": "g",
"metaTitle": "SEO Product metaTile",
"metaDescription": "SEO Product metaDescription",
"harmonizedSystemCode": "987456321",
"countryCodeOfOrigin": "IT",
"provinceCodeOfOrigin": "IT-52",
"costPerItem": 14.95,
"package": "gid://shopify/ShippingPackageV2/987654321",
"isDigitalItem": true,
"inventoryTracked": false
}
Configurazione destinazione
Configurare una destinazione Shopify e associarla al flusso, oltre alla configurazione base del flusso dati.
| Campo | Valore | Note |
|---|---|---|
Destination Type | Shopify | |
Operation | Product sync | POST /egress/sync-product-to-shopify |
GraphQL endpoint URL | https://SHOPIFYURL.myshopify.com/ | URL dell'endpoint GraphQL Admin API dello shop Shopify |
Admin API access token | shpat_CODICEALFANUMERICO | Oppure Client ID (API key) + Client secret — vedi Autenticazione |
Client ID (API key) | IL_TUO_CLIENT_ID | |
Client secret | IL_TUO_CLIENT_SECRET | |
Active product | true / false | Se true, i prodotti creati risultano attivi su Shopify (obbligatorio) |
Publish product | true / false | Se true, pubblica il prodotto nello online store (default: true, obbligatorio) |
Avoid title update | true / false | Se true, non sovrascrive il titolo esistente in aggiornamento (default: false, obbligatorio) |
Parallel processes | 1 | Numero di processi paralleli per messaggi bulk (minimo 1, default: 1, obbligatorio) |
Deprecato — configurazione precedente (HTTP Adapter)
Deprecato
La configurazione tramite HTTP Adapter con Base Url, Resource Path e header x-api-key nei Settings Override è deprecata. Utilizzare la destinazione Shopify descritta sopra.
Oltre alle configurazioni base del flusso dati era necessario impostare nei Settings Override:
| Campo | Valore | Note |
|---|---|---|
Base Url | https://adapter.flowlyze.io | url degli adapter |
Resource Path | /api/adp/shopify/egress/sync-product-to-shopify | path dell'adapter per i prodotti |
Headers :: x-api-key | ********** | api key di verifica interazione endpoint |
Headers :: x-shopify-graphql-url | https://SHOPIFYURL.myshopify.com/ | url dello shopify con cui connettersi |
Headers :: x-shopify-access-token | shpat_CODICEALFANUMERICO | secret della custom app creata per l'integrazione |
Headers :: x-active-product | true/false | determina se i prodotti vengono creati come attivi (true) o draft (false) |
Headers :: x-publish-product | true/false | determina se i prodotti vengono pubblicati su online store (true) oppure no (false) |
Headers :: x-avoid-title-update | true/false | determina se il titolo del prodotto deve essere aggiornato (false) oppure no (true) |
Headers :: x-parallel-processes-number | 3 | numero di processi da eseguire in parallelo (default: 1, max: 3) |