Passa al contenuto principale

Introduzione alle Catalog APIs

Le Catalog APIs costituiscono il motore di distribuzione e consultazione dei cataloghi Webround Commerce. Mentre le Commerce APIs si occupano delle operazioni back-office, le Catalog APIs sono progettate per servire il dato commerciale arricchito verso i tuoi frontend (Draft, sito pubblicato o qualsiasi strumento in grado di connettersi a internet).

Questo modulo è ottimizzato per gestire la complessità di cataloghi multilingua e multi-valuta, permettendo di recuperare in un'unica chiamata tutto ciò che serve per renderizzare una scheda prodotto completa o intere pagine di catalogo prodotti.

Filosofia del Dato: Enrichment on Demand​

In Webround, un prodotto non è un'entità statica. È un insieme di riferimenti (asset, attributi, varianti) che possono essere gestiti in maniera differenziata. Ad esempio, per una pagina di catalogo, potrebbero bastare nomi, asset e prezzi. Invece, per una pagina di dettaglio, sarebbe corretto mostrare tutti i dati possibili. Proprio per questo, queste API adottano la filosofia dell'enrichment on demand.

Attraverso una serie di flag di inclusione (es. includeAssets, includeAttributes), puoi decidere granularmente quali relazioni inserire nella risposta.

  • Listati Veloci: Richiedi solo i dati base per le grid di navigazione.
  • Schede Prodotto: Attiva tutti i flag per ottenere varianti, gallery multimediale e specifiche tecniche in un colpo solo.

Localizzazione e Pricing Dinamico​

Il catalogo non restituisce mai un dato "flat". Ogni richiesta viene processata in base al contesto definito dai parametri obbligatori:

1. Valuta & cadenza di prezzo​

Il prezzo di un prodotto è un dato legato alla valuta (currencyCode) e alla frequenza di pagamento (cadence).

  • Flessibilità: Puoi gestire nello stesso catalogo prodotti venduti "una tantum" e servizi in abbonamento (giornaliero, mensile, settimanale, ecc.).
  • Conversione: Il sistema filtra il prezzo richiesto in base ai parametri. Impostare come currencyCode il valore EUR taglierà fuori tutti i prodotti che non hanno un prezzo con valuta EUR. Nota: I prodotti senza prezzo vengono sempre restituiti.

2. Language Code​

Tutti i campi testuali (nomi, descrizioni, tag, attributi) vengono filtrati tramite il langCode. Se una traduzione non è presente, il sistema effettua il fallback automatico sulla lingua predefinita dello store per non lasciare mai campi vuoti.

Ricerca Avanzata e Filtraggio​

Per superare i limiti di lunghezza degli URL e permettere query complesse, la ricerca nel catalogo utilizza il metodo POST su endpoint di ricerca dedicati.

Logica dei Filtri (UUID & Range)​

Il sistema di filtraggio è progettato per gestire array di identificativi con supporto completo per Tag, Filtri e ricerche testuali.

  • Filtraggio per Tag (tagValueIds): Permette di filtrare i prodotti in base ai Tag Values associati.

    • Logica OR (Stesso Tag): Se inserisci più valori appartenenti allo stesso Tag (es. Bianco e Nero sotto il tag Colore), la ricerca restituirà i prodotti che hanno il valore Bianco oppure Nero.
    • Logica AND (Tag Diversi): Se inserisci valori di Tag differenti (es. Bianco e Nero + il tag Scarpe della categoria Calzature), il sistema costruisce un'espressione AND tra operatori OR.
    • Esempio: (Bianco OR Nero) AND Scarpe.

  • Filtraggio tramite Filtri (filterIds): Supporta sia identificativi statici che filtri di tipo range.

    • Filtri Range: Per cercare valori all'interno di un intervallo (es. il prezzo), si utilizza la sintassi UUID[min;max].
    • Esempio: Per trovare prodotti con costo compreso tra 10 e 50 usando un filtro con ID "UUID", dovrai passare UUID[10;50]. Se lasci uno dei due campi vuoti, il sistema farà fallback sul valore configurato per quel filtro nel back-office.

  • Filtraggio per Collezioni: Poiché le collezioni sono raggruppamenti logici di filtri, la ricerca per collezione si effettua passando nel campo filterIds tutti gli identificativi che la compongono.

  • Filtraggio Testuale (search): Supporta ricerche full-text e fuzzy search grazie all'integrazione con OpenSearch.

    • Rilevanza (Scoring): Il sistema assegna una priorità maggiore al nome del prodotto e della variante, calcolando uno score di corrispondenza totale.
    • Copertura: La ricerca analizza nome prodotto, nome variante, valori dei tag e valori degli attributi. Più i metadati (Tag e Attributi) sono specifici, più accurato sarà il risultato della ricerca testuale.

Integrità dei Dati e Performance​

Le Catalog APIs leggono dati "pre-processati" per garantire tempi di risposta fulminei.

Stato di Pubblicazione

Solo i prodotti pubblicati e appartenenti a uno store attivo (con abbonamento Webround Commerce valido) sono accessibili tramite le Catalog APIs pubbliche. Se un prodotto non è pubblico, non apparirà nei risultati di ricerca anche se l'ID è corretto. Se non trovi un prodotto dopo la sua pubblicazione, prova a resettare lo stato di visibilità, assicurandoti che sia visibile.

Autenticazione​

  • Public Access: Gli endpoint di consultazione (Search, Detail, Reviews) sono accessibili pubblicamente ma richiedono sempre l'identificazione dello store tramite header o parametro.
  • Context: Le richieste devono includere lo store-id per caricare le configurazioni di listino e localizzazione corrette.