Introduzione
L'API di GelatoConnect ti permette di integrare i tuoi sistemi con GelatoConnect in modo automatico: puoi inviare ordini, monitorare lo stato e gestire i dettagli di spedizione. Questa guida ti aiuterà a capire come Inizia adesso con l'API e realizzare la tua prima integrazione.
Cosa serve prima di iniziare
Prima di iniziare a lavorare con le API di GelatoConnect, dovresti avere:
La tua chiave API e il segreto (forniti quando configuri un connettore per il tuo cliente)
Conoscenza di base delle REST API e dei metodi HTTP
Familiarità con il formato dati JSON
Un ambiente di sviluppo che ti permette di fare richieste HTTP
Nozioni di base sulle API
L'API di gestione ordini GelatoConnect è strutturata secondo i principi REST e utilizza i metodi HTTP standard per interagire con le risorse. Tutte le richieste API devono usare HTTPS e tutte le risposte sono restituite in formato JSON, inclusi i messaggi di errore.
URL di base
L'URL di base per l'API di GelatoConnect è:
https://api.partner-connect.io/api/{partner-prefix}/Riceverai il tuo prefisso partner personalizzato durante l’onboarding.
Autenticazione
Tutte le richieste API devono includere le tue credenziali di autenticazione nell’header. Per autenticarti:
Aggiungi l'intestazione
X-API-KEYalla tua richiestaImposta il valore inserendo la tua chiave e il tuo segreto nel formato
chiave:segret
Esempio:
X-API-KEY: your-api-key:your-api-secret
Come fare la tua prima richiesta API
Vediamo insieme come inviare una richiesta API semplice per inoltrare un ordine.
1. Prepara i dati del tuo ordine
Crea un oggetto JSON con i dettagli dell’ordine. Ecco un esempio semplice:
{"orderReferenceId": "your-order-ref-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]","telefono": "1234567890"},"items": [{"itemReferenceId": "item-123","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/path/to/printfile.pdf"}]}]}2. Invia l'ordine
Invia una richiesta POST all'endpoint per inviare l'ordine:
POST https://api.partner-connect.io/api/{partner-prefix}/orderInserisci l’header di autenticazione e i dati dell’ordine in formato JSON nel corpo della richiesta.
3. Gestisci la risposta
Se va tutto bene, riceverai una risposta simile a questa:
{"id": "32884a3e-bd09-42be-8225-c5cea7d24611","orderReferenceId": "your-order-ref-123","createdAt": "12/04/2025 10:23:28"}Il campo id contiene l'ID ordine di GelatoConnect, che dovresti conservare per riferimento futuro.
Operazioni API comuni
Quando ti senti a tuo agio con l'invio degli ordini di base, puoi scoprire anche le altre operazioni API:
Scopri i dettagli dell'ordine
Recupera le informazioni su un ordine già esistente:
GET https://api.partner-connect.io/api/{partner-prefix}/{orderId}Annulla un ordine
Annulla un ordine che non è ancora stato spedito:
POST https://api.partner-connect.io/api/{partner-prefix}/{orderId}/cancelCerca ordini
Trova gli ordini in base a criteri specifici:
POST https://api.partner-connect.io/api/{partner-prefix}/searchAggiorna spedizione
Modifica i dettagli di spedizione per un ordine:
PUT https://api.partner-connect.io/api/{partner-prefix}/{orderId}Implementare prodotti personalizzati
Invece di usare gli UID dei prodotti, puoi usare i prodotti cliente per un approccio più intuitivo:
{"productName": "Biglietto da visita","productVariant": {"Size": "Standard","Carta": "Opaca premium","Colore": "Stampa a colori su entrambi i lati"}}Per poterli usare nelle chiamate API, devi prima configurare i prodotti cliente in GelatoConnect.
Metti alla prova la tua integrazione
Prima di lanciare la tua integrazione, mettila alla prova con questi metodi:
Fai una prova con ordini di esempio: crea ordini di test con quantità basse e controlla che vengano visualizzati correttamente su GelatoConnect.
Verifica gli aggiornamenti sullo stato dell’ordine: segui gli ordini in ogni fase per assicurarti che il tuo sistema riceva e gestisca correttamente i cambi di stato.
Gestione degli errori: crea apposta ordini non validi per mettere alla prova la tua logica di gestione degli errori.
Test end-to-end: prova tutto il percorso dell’ordine, dall’invio alla consegna, usando un piccolo gruppo di ordini di prova.
Buone pratiche
Per garantire un'integrazione ottimale con l'API di GelatoConnect:
ID ordine del negozio: conserva sempre l’ID ordine GelatoConnect che ricevi nella risposta alla creazione dell’ordine.
Gestisci gli errori: aggiungi un sistema solido per gestire risposte inaspettate o momenti in cui l’API non è disponibile.
Usa l'idempotenza: crea ID unici per gli ordini, così eviti di inviare lo stesso ordine due volte.
Usa l’attesa progressiva: se ricevi errori di limite di frequenza (429), aumenta il tempo di attesa tra un tentativo e l’altro.
Monitora l'utilizzo delle API: tieni d'occhio quanto usi le API per non superare i limiti consentiti.
Risolvere i problemi più comuni
Errori di autenticazione
Se ricevi un errore 401 Unauthorized, controlla che:
La tua API key e la tua secret sono corrette
Il formato è
key:secretnell'intestazione X-API-KEY.Stai usando HTTPS, non HTTP
Errori di richiesta non validi
Se ricevi un errore 400 Bad Request:
Controlla il messaggio di errore per capire quali campi hanno problemi
Verifica che tutti i campi obbligatori siano inclusi
Conferma che il formato JSON sia valido
Errori di limite di richieste
Se ricevi un errore 429: troppe richieste.
Adotta una strategia di attesa per distribuire meglio le richieste
Quando puoi, raggruppa le richieste
Controlla la tua integrazione per evitare chiamate ripetute e inutili
Prossimo passo
Ora che hai capito le basi dell’API di GelatoConnect, sei anche prontə a leggere la documentazione completa dell’API per scoprire tutti i dettagli sugli endpoint 🔗 [Gestione degli ordini - GCW] Documentazione API per la gestione degli ordini