Upsert Combined Listing

L'endpoint consente di gestire le Combined Listings su Shopify. Questa funzionalità permette di creare o aggiornare un Parent Product, che funge da contenitore logico per raggruppare diversi prodotti figli (childrenSkus).

Architettura del Flusso

Il sistema adotta una gestione separata per le entità:

1. Parent Product: La creazione e l'aggiornamento del contenitore (Parent) avvengono tramite questo endpoint dedicato alle Combined Listings.
2. Child Products: I prodotti figli devono già esistere su Shopify, essendo gestiti tramite il normale flusso anagrafica prodotti.

Identificazione tramite SKU (Metafield)

Poiché i Parent Product su Shopify non possiedono nativamente un campo SKU, Flowlyze utilizza un Metafield dedicato per l'identificazione univoca. Questo permette di gestire le operazioni di update senza duplicazioni.

Configurazione Metafield richiesto su Shopify:

• Namespace: flowlyze
• Key: uniqueSku
• Type: single_line_text_field
• Opzioni: Deve essere impostato come filtrabile e deve consentire solo valori univoci.

Se il metafield non è presente verrà creato direttamente all'interno dell'endpoint.

Configurazione del Flusso

Oltre alla configurazione base del flusso dati, è necessario aggiungere le seguenti impostazioni nei Settings Override:

Campo	Valore	Note
Base Url	https://adapter.flowlyze.io	URL degli adapter
Resource Path	api/adp/shopify/egress/sync-combined-listing-to-shopify	Path per il flusso di combined listing.
Headers :: x-api-key	**********	API key di verifica
Headers :: x-shopify-access-token	shpat_CODICEALFANUMERICO	Secret della custom app Shopify
Headers :: x-shopify-graphql-url	https://SHOPIFYURL.myshopify.com/	URL dello store Shopify

Messaggio di Input

L’invio del JSON gestisce l'intero ciclo di vita del parent e la sincronizzazione dichiarativa dei figli. In fase di creazione, il prodotto parent viene impostato con status DRAFT.

Campi del Parent Product

• sku - Campo obbligatorio.
  Identificatore univoco del parent (salvato nel metafield flowlyze.uniqueSku).
• handle
  Identificatore URL-friendly. Fondamentale per la SEO e la navigazione.
• title
  Il nome del prodotto. Obbligatorio in creazione; se omesso in aggiornamento, rimane invariato.
• Campi Informativi: description, type, vendor, tags, markets.
• media: Array di oggetti contenenti url (obbligatorio), alternativeText e filename.
• metafields & files: Oggetti chiave-valore per estendere le informazioni del parent (formato namespace.key).
• SEO: metaTitle e metaDescription per i metadati della pagina.

Per svuotare il contenuto di un campo (es. la descrizione) è necessario passare una stringa vuota (""). Se il campo viene passato come null o rimosso dal JSON, il valore corrente su Shopify rimarrà invariato.

Gestione dei Children (childrenSkus)

La lista dei prodotti figli viene gestita in modo atomico:

• Associazione: Gli SKU in childrenSkus devono corrispondere a varianti esistenti su Shopify (gestite dal flusso anagrafica).
• Sincronizzazione: Vengono associati al parent solo i prodotti presenti nell'array. Qualsiasi figlio precedentemente associato e non incluso nell'invio corrente verrà rimosso.
• Svuotamento: Per rimuovere tutti i figli, inviare "childrenSkus": [].
• No Modifica: Se il campo è null, le associazioni correnti non vengono toccate.

Esempio di Tracciato JSON completo

{
  "sku": "PARENT-SHORT-001",
  "title": "Shorts Sportivi Combinati",
  "handle": "shorts-sportivi-combinati",
  "description": "Descrizione estesa del prodotto parent",
  "type": "Abbigliamento",
  "vendor": "Brand Name",
  "tags": ["Estate", "Sport"],
  "markets": ["123456", "789789"],
  "media": [
    {
      "alternativeText": "Vista frontale",
      "url": "https://demo.sintra-soh.com/images/parent_front.jpg",
      "filename": "parent_front.jpg"
    }
  ],
  "metafields": {
    "custom.season": "SS24"
  },
  "files": {
    "custom.pdf": "http://dev3.sintra-soh.com/PDF/esempio_pdf.pdf"
  },
  "childrenSkus": [
    {
      "sku": "blue-short-XS",
      "optionValues": {
        "color": "blue"
      }
    },
    {
      "sku": "pink-short-XS",
      "optionValues": {
        "color": "pink"
      }
    }
  ]
}