Cosa sono i lookups e perché contano davvero?
Le Lookups in GelatoConnect funzionano come delle tabelle di conversione che trasformano i dati del tuo sistema in formati che Gelato può comprendere. Sono fondamentali per un'integrazione API senza intoppi, soprattutto quando si tratta di mappare:
ID prodotto/SKU: trasforma i tuoi identificatori personalizzati dei prodotti nei codici UID standardizzati di Gelato
Metodi di spedizione: associa i nomi dei tuoi metodi di spedizione ai codici dei corrieri di Gelato
Identificatori del corriere: traduci i nomi dei corrieri tra i sistemi
Altri mapping personalizzati: Qualsiasi valore che deve essere tradotto in modo coerente tra i sistemi
Senza le lookups, gli ordini potrebbero non andare a buon fine se gli identificatori del tuo sistema non corrispondono ai valori attesi da Gelato. Le lookups sono il ponte sicuro che collega questi mondi, garantendo che la gestione degli ordini sia sempre fluida.
I vantaggi principali dell'utilizzo delle Lookups
✅ Le lookups servono a standardizzare i dati per il sistema di Gelato. Così eviti che ci siano differenze tra i valori personalizzati dei clienti e quelli compatibili con Gelato.
✅ Permettono di usare valori alternativi per evitare errori se mancano delle corrispondenze.
✅ Caricamenti CSV in blocco rendono più semplice gestire le mappature su larga scala.
Configurare le ricerche: guida passo dopo passo
1. Vai alla pagina Lookups
Accedi al tuo account GelatoConnect
Vai su Workflow > Order Intake nel menu a sinistra
Fai clic su Lookups per vedere le associazioni già presenti o crearne di nuove
2. Crea una nuova tabella di ricerca
Opzione A: creazione manuale
Fai clic sul pulsante Crea in alto nella pagina.
Inserisci un nome descrittivo per la tua ricerca (ad esempio: "Mappatura SKU prodotto")
Seleziona il cliente a cui applicare questa ricerca dal menu a tendina.
Aggiungi una descrizione (opzionale ma consigliata) per aiutare a capire a cosa serve questa ricerca.
Inserisci un campo modello: questo è il riferimento che userai nel codice del template mapper per accedere a questa ricerca. Il campo template della ricerca deve essere racchiuso tra doppie parentesi graffe (ad esempio, ##{{sku}}).
Aggiungi le associazioni cliccando sull'icona +:
Chiave: inserisci il valore dal tuo sistema (ad esempio, il tuo SKU o codice prodotto).
Valore: inserisci il valore Gelato corrispondente (ad esempio, l'UID del prodotto Gelato).
Ripeti per tutti i valori che devono essere associati.
Fai clic su Salva modifiche per applicare la configurazione.
Opzione B: importazione in blocco (consigliata se hai molti valori)
Prepara un file Excel o CSV con due colonne:
Colonna A: intestazione "Lookup key" seguita dai valori del tuo sistema
Colonna B: intestazione "Product UID" seguita dai valori corrispondenti di Gelato
Fai clic su Crea per iniziare una nuova ricerca
Compila i campi Nome, Cliente, Descrizione e Modello come sopra
Clicca su Importa invece di inserire tutto a mano
Seleziona il tuo file Excel/CSV già pronto
Controlla le associazioni importate
Fai clic su Salva modifiche per completare la configurazione
Guida video
3. Implementa le ricerche nel tuo Template Mapper
Dopo aver configurato le tue tabelle di ricerca, devi richiamarle nel codice del template mapper (usando Jinja2):
Vai su Workflow > Order Intake > Templates
Modifica il template dove vuoi usare le ricerche
Nella sezione Template Mapper, usa la funzione
lookups()per accedere alle tue tabelle di mappingSintassi di base:
##{{ lookups({"alias": value_to_lookup}, strict=False, default="fallback_value")|js }}
Esempio 1: mappatura UID prodotto
{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}"productUid": ##{{ productUid|js }},Esempio 2: associazione dei metodi di spedizione
"shipmentMethodUid": ##{{ lookups({"shipping_code": order.shipping.method}, strict=False, default="normale")|js }}, Il parametro strict=False fa sì che il codice non dia errore se non viene trovato un risultato, mentre il parametro default offre un valore di riserva.
Metti alla prova le tue ricerche
Fai sempre una prova delle tue ricerche prima di usarle in produzione:
Vai al tuo template nella sezione Templates
Vai alla scheda Template Testing
Usa il modulo di prova per controllare che le tue ricerche traducano i valori nel modo giusto
Controlla che le chiavi mancanti usino davvero il valore predefinito
Invia un ordine di prova e controlla che venga gestito come previsto
Situazioni d’uso più comuni
Mappatura SKU prodotto su UID Gelato
Collega i tuoi codici prodotto interni agli UID dei prodotti Gelato:
{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}"productUid": ##{{ productUid|js }},
Traduzione del metodo di spedizione
Connetti i nomi dei tuoi metodi di spedizione agli UID dei metodi di spedizione di Gelato:
{% set shipMethod = lookups({"shipping_method": order.shipping_type}, strict=False, default="normal") %} "shipmentMethodUid": ##{{ shipMethod|js }},
Mappatura dei corrieri
Collega gli identificatori dei corrieri tra i sistemi:
{% set carrier = lookups({"carrier_code": shipment.carrier}, strict=False, default=shipment.carrier) %} "carrier": ##{{ carrier|js }},
Mappatura dei codici di stato specifici per paese
Gestisci i casi particolari dei codici di stato in alcuni paesi:
{% set stateCode = shipTo.state %}{% if shipTo.country|upper == "US" %} {% set stateCode = lookups({"us_state": shipTo.state}, strict=False, default=shipTo.state) %}{% endif %}"state": ##{{ stateCode|js }},
Risolvere i problemi di ricerca
Se le tue ricerche non funzionano come dovrebbero:
Controlla le corrispondenze esatte: le chiavi distinguono tra maiuscole e minuscole e devono essere identiche a quelle presenti nei tuoi dati API.
Verifica i nomi dei campi del template: assicurati che il campo del template che stai cercando corrisponda a quello indicato nel tuo template.
Usa
strict=False: così eviti errori se manca una chiave di ricercaImposta sempre dei valori predefiniti: scegli valori adatti per gestire le associazioni mancanti
Controlla tutto il payload della richiesta: usa la pagina Requests per vedere il payload che viene elaborato
Buone pratiche
Usa nomi descrittivi: dai ai lookups un nome chiaro che spieghi subito a cosa servono
Aggiungi descrizioni: inserisci dettagli su quando e dove viene utilizzata ogni ricerca
Tieni sempre aggiornate le associazioni: controlla e aggiorna regolarmente le look-up quando i prodotti o i servizi cambiano
Usa l'importazione in blocco per grandi quantità di dati: risparmia tempo importando le look-up tutte insieme
Metti tutto alla prova: testa sempre le ricerche sia con valori che corrispondono sia con valori che non corrispondono
Documenta le tue ricerche: tieni traccia di quali ricerche usi in ogni modello
Vuoi saperne di più?
Ora che hai configurato le ricerche per l'integrazione API, potresti voler:
Configura i postback per tenere aggiornati i tuoi clienti