Vai al contenuto principale

[Order Intake - GCW] Configurazione dei Lookups per l'integrazione API

Scritto da Kyle Sawyer

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

✅ Standardizzazione: garantisce la coerenza dei dati tra il tuo sistema e Gelato
✅ Prevenzione degli errori: riduce i problemi causati da identificatori non corrispondenti
✅ Protezione fallback: fornisce valori predefiniti se non vengono trovate corrispondenze esatte
✅ Scalabilità: rende più semplice la gestione dell'aggiunta di nuovi prodotti o metodi di spedizione
✅ Manutenzione: gestione centralizzata delle mappature per aggiornamenti più semplici

Configurare le ricerche: guida passo dopo passo

1. Vai alla pagina Lookups

  1. Accedi al tuo account GelatoConnect

  2. Vai su Workflow > Order Intake nel menu a sinistra

  3. 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

  1. Clicca sul pulsante Create nella parte superiore della pagina

  2. Inserisci un nome descrittivo per la tua ricerca (ad esempio: "Mappatura SKU prodotto")

  3. Seleziona il cliente a cui si applicherà questo lookup dal menu a tendina

  4. Aggiungi una Descrizione (facoltativa ma consigliata) per aiutare a identificare lo scopo del lookup

  5. Inserisci un campo template: questo è il riferimento utilizzato nel codice del template mapper per accedere a questo lookup

  6. Aggiungi le associazioni cliccando sull'icona +:

    • Chiave: inserisci il valore dal tuo sistema (ad es. lo SKU o il codice del tuo prodotto)

    • Valore: inserisci il valore Gelato corrispondente (ad es. l'UID del prodotto Gelato)

  7. Ripeti per tutti i valori che devono essere mappati

  8. Fai clic su Salva modifiche per applicare la configurazione

Opzione B: importazione in blocco (consigliata se hai molti valori)

  1. Prepara un file Excel o CSV con due colonne:

    • Colonna A: intestazione "lookup key" seguita dai valori del tuo sistema

    • Colonna B: intestazione "UID prodotto" seguita dai valori corrispondenti di Gelato

  2. Fai clic su Crea per iniziare una nuova ricerca

  3. Compila i campi Nome, Cliente, Descrizione e Modello come sopra

  4. Clicca su Importa invece di inserire tutto a mano

  5. Seleziona il tuo file Excel/CSV già pronto

  6. Controlla le associazioni importate

  7. Fai clic su Salva modifiche per completare la configurazione

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):

  1. Vai su Workflow > Order Intake > Templates

  2. Modifica il template dove vuoi usare le ricerche

  3. Nella sezione Template Mapper, usa la funzione lookups() per accedere alle tue tabelle di mapping

  4. Sintassi 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="normal")|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:

  1. Vai al tuo template nella sezione Templates

  2. Vai alla scheda Template Testing

  3. Usa il modulo di prova per controllare che le tue ricerche traducano i valori nel modo giusto

  4. Controlla che le chiavi mancanti usino davvero il valore predefinito

  5. 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 ricerca

  • Imposta 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

Cosa fare adesso

Ora che hai configurato le ricerche per l'integrazione API, potresti voler:

  1. Scopri come creare un template per Order Intake

  2. Esplora le tecniche avanzate di Template Mapper

  3. Configura i Postbacks automatici per aggiornare i clienti

Hai bisogno di ulteriore aiuto? Contatta il nostro team di supporto all'indirizzo [email protected]

Articoli correlati
Hai ricevuto la risposta alla tua domanda?