Quando invii ordini a GelatoConnect tramite l’API, hai due modi per specificare i prodotti: puoi usare i Product UID oppure i prodotti personalizzati del cliente. In questa guida trovi entrambe le opzioni, i loro vantaggi e quando conviene scegliere l’una o l’altra.
Approccio UID al prodotto
Il metodo Product UID prevede l'uso di identificatori unici di prodotto (UID) per specificare i prodotti nei tuoi ordini.
Come funziona
Quando usi gli UID di prodotto, devi includere il parametro productUid nell'articolo dell'ordine:
{ "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g/mq-non-patinato_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantità": 1, "file": [ { "type": "default", "url": "https://example.com/files/printfile.pdf" } ]}Struttura UID del prodotto
Un Product UID è una stringa strutturata che racchiude le caratteristiche di un prodotto. Ad esempio, in flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor:
flat_product: Tipo di prodottopf_a4: Formato carta (dimensione A4)pt_200-g/mq-non-patinato: Tipo di carta (carta non patinata da 200 g/mq)cl_4-0: Configurazione colore (stampa a 4 colori sul fronte, nessun colore sul retro)ct_none: Taglio (nessuno)prt_none: Effetti di stampa speciali (nessuno)sft_none: Trattamenti superficiali (nessuno)set_none: Effetti speciali (nessuno)hor: orientamento (orizzontale)
Approccio ai prodotti per i clienti
Il metodo Customer Products consiste nel creare definizioni di prodotti personalizzati su GelatoConnect e richiamarli per nome e variante nei tuoi ordini.
Come funziona
Per prima cosa, imposti i prodotti cliente su GelatoConnect, definendo i nomi dei prodotti e le loro varianti. Poi, quando effettui gli ordini, fai riferimento a questi prodotti usando i parametri productName e productVariant:
{ "itemReferenceId": "ITEM-001", "productName": "Biglietto da visita", "productVariant": { "Size": "Standard", "Paper": "Opaco premium", "Color": "Colore pieno su entrambi i lati" }, "quantity": 100, "files": [ { "type": "fronte", "url": "https://example.com/files/front.pdf" }, { "type": "indietro", "url": "https://example.com/files/back.pdf" } ]}Come configurare i prodotti per i clienti
Prima di usare i prodotti personalizzati nei tuoi ordini API, devi configurarli su GelatoConnect:
Vai alla sezione Prodotti in GelatoConnect
Crea prodotti personalizzati per i clienti con nomi specifici e opzioni di variante
Collega questi prodotti personalizzati alle specifiche dei prodotti di Gelato
Quando scegliere ogni approccio
Usa gli UID dei prodotti quando:
Hai appena iniziato con GelatoConnect
Hai solo pochi prodotti fissi
Vuoi partire subito senza dover fare altre configurazioni
Stai creando una versione di prova o una soluzione di test
Usa i prodotti personalizzati quando:
Hai un catalogo prodotti davvero ampio
Vuoi riferimenti ai prodotti più intuitivi nel tuo codice
I nomi dei tuoi prodotti sono diversi dalle convenzioni di denominazione di Gelato
Le configurazioni dei prodotti possono cambiare nel tempo
Esempi pratici di implementazione
Esempio di UID prodotto
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto' \--data '{ "orderReferenceId": "ORDER-123", "orderType": "ordine", "currency": "USD", "shippingAddress": { "country": "US", "firstName": "John", "lastName": "Doe", "addressLine1": "Via Principale 123", "city": "New York", "postCode": "10001", "state": "NY", "email": "[email protected]", "phone": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productUid": "flat_product_pf_a4_pt_200-g-mq-non-patinato_cl_4-0_ct_none_prt_none_sft_none_set_none_hor", "quantity": 1, "file": [ { "type": "predefinito", "url": "https://example.com/files/printfile.pdf" } ] } ]}'Esempio di prodotti per clienti
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \--header 'Content-Type: application/json' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto' \--data '{ "orderReferenceId": "ORDER-124", "orderType": "order", "currency": "USD", "shippingAddress": { "country": "US", "firstName": "John", "lastName": "Doe", "addressLine1": "Via Principale 123", "city": "New York", "postCode": "10001", "state": "NY", "email": "[email protected]", "phone": "123-456-7890" }, "items": [ { "itemReferenceId": "ITEM-001", "productName": "Volantino", "productVariant": { "Size": "A4", "Paper": "Non patinato 200 g/mq", "Printing": "Stampa a colori su un lato" }, "quantity": 100, "files": [ { "type": "default", "url": "https://example.com/files/volantino.pdf" } ] } ]}'Buone pratiche
Qualunque sia la strada che scegli, segui questi consigli pratici:
Coerenza: segui sempre lo stesso approccio durante tutta la tua implementazione
Documentazione: tieni sempre aggiornata e chiara la documentazione delle tue associazioni di prodotto
Validazione: controlla che gli identificatori dei prodotti siano corretti prima di inviare gli ordini
Test: prova tutto con ordini di esempio prima di partire sul serio
Gestione degli errori: crea una gestione solida degli errori per i prodotti non validi
Passare da un approccio all'altro
Se inizi con gli UID di prodotto e poi vuoi passare ai prodotti cliente:
Imposta i tuoi prodotti personalizzati su GelatoConnect
Collega questi elementi ai UID dei prodotti che hai già usato
Aggiorna la tua integrazione API usando productName e productVariant
Metti alla prova tutto a fondo prima di lanciare in produzione.
Anche il passaggio inverso è possibile, ma succede più raramente.
Conclusione
Entrambi gli approcci hanno i loro vantaggi; la scelta dipende dalle tue esigenze e dai tuoi limiti specifici. Gli UID dei prodotti offrono semplicità e accesso diretto al catalogo di Gelato, mentre i prodotti personalizzati garantiscono maggiore chiarezza, flessibilità e una gestione centralizzata.
Per la maggior parte delle soluzioni a lungo termine, i prodotti personalizzati offrono vantaggi in termini di manutenzione e chiarezza. Tuttavia, per implementazioni rapide o casi d’uso specifici, i Product UID possono essere la scelta migliore.
Per maggiori informazioni su come configurare i prodotti personalizzati in GelatoConnect, consulta la guida Creare prodotti personalizzati.