Sincronizzazione File nei Metafield

Endpoint per l'aggiornamento, l'inserimento o la rimozione di file multimediali all'interno dei Metafield Shopify per diverse entità.

⚠️ Nota Importante Questo endpoint carica i file a partire dagli URL forniti e li associa ai metafield specificati. Assicurarsi che il tipo di Metafield su Shopify (es. file_reference o list.file_reference) sia coerente con il dato inviato (stringa singola o array).

Informazioni generali

L'endpoint gestisce l'associazione di risorse ai Metafield di tre entità principali: Prodotti, Varianti e Ordini.

Logica di Identificazione

L'identificazione del target avviene secondo questa gerarchia:

1. Id: Se popolato, viene utilizzato l'ID univoco di Shopify (solo parte numerica 12345678 o GID completo gid://shopify/Order/12345678).
2. Reference: Se l'ID è assente, il sistema effettua una ricerca tramite il valore di riferimento. Il comportamento varia in base all'entità:
   • ORDER: Ricerca tramite orderName.
   • PRODUCTVARIANT: Ricerca tramite SKU.
   • PRODUCT: Ricerca tramite lo SKU di una qualsiasi delle sue varianti.

Struttura dei Campi

Campi Principali

Campo	Tipo	Descrizione
id	String	ID numerico o GID di Shopify. Ha la priorità su reference.
reference	String	Valore di ricerca (Order Name o SKU). Ignorato se id è presente.
entity	Enum	Tipo di entità target. Valori: PRODUCT, PRODUCTVARIANT, ORDER.
files	Object	Mappa di chiavi (metafield) e valori (URL dei file).

Gestione delle Chiavi (files)

Le chiavi all'interno dell'oggetto files identificano il Metafield:

• Namespace completo: (Es: "flowlyze.manuale") Metodo raccomandato. Identifica univocamente il metafield.
• Solo Chiave: (Es: "manuale") Se esistono più metafield con la stessa chiave in namespace differenti, il sistema aggiornerà il primo creato cronologicamente.

Gestione dei Valori

I valori associati alle chiavi possono essere di due tipi, in base alla configurazione del Metafield su Shopify:

• Stringa singola: Un unico URL (es. "http://.../file.pdf").
• Array di stringhe: Una lista di URL (es. ["http://.../1.pdf", "http://.../2.pdf"]). Da usare solo se il metafield è definito come lista.

Tracciato di esempio

[
  {
    "id": "594412345678",
    "reference": "#1108",
    "entity": "ORDER",
    "files": {
      "flowlyze.list_file": [
        "http://PDF/esempio1_pdf.pdf",
        "http://PDF/esempio2_pdf.pdf"
      ],
      "flowlyze.single_file": "http://PDF/esempio_pdf.pdf"
    }
  },
  {
    "id": null,
    "reference": "SKU-VARIANT-123",
    "entity": "PRODUCTVARIANT",
    "files": {
      "custom.manuale_tecnico": "http://PDF/esempio_pdf.pdf"
    }
  }
]

Operazione sui dati

L'endpoint opera in modalità Upsert (Update o Insert) e gestisce il ciclo di vita del file sui metafield Shopify come segue:

• Inserimento/Aggiornamento: Fornendo un URL (o una lista di URL), il sistema carica i file su Shopify e aggiorna il riferimento nel metafield. Se il metafield conteneva già dei dati non uguali a quelli forniti, questi verranno sovrascritti dai nuovi link.
• Rimozione: Per svuotare un metafield e rimuovere l'associazione ai file, è sufficiente inviare un valore null, una stringa vuota ("") o un array vuoto ([]) per la chiave corrispondente.

Configurazioni flusso

Campo	Valore	Note
Base Url	https://adapter.flowlyze.io	url degli adapter
Resource Path	/api/adp/shopify/egress/sync-file-to-shopify	path dell'adapter per il flusso di aggiunta file metafield
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