Questa guida offre istruzioni pratiche ed esempi per lavorare con gli endpoint API degli ordini di GelatoConnect. Vedremo insieme come inviare ordini, annullare ordini, aggiornare le informazioni di spedizione, recuperare i dettagli degli ordini e cercare ordini tramite l'API.
Cosa serve prima di iniziare
Prima di iniziare a usare questi endpoint, assicurati di avere:
La tua chiave API e il segreto (che ricevi quando configuri un connettore per il tuo cliente)
L’URL di base per i tuoi endpoint API
Conoscenza di base su come fare richieste HTTP con curl o lo strumento che preferisci
Invia ordine
L'endpoint Submit Order ti permette di creare un nuovo ordine su GelatoConnect.
Endpoint: POST /{submitOrderUrl}
Esempio di richiesta
# Invio di un ordine semplicecurl --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": "TUO-ORDINE-123", "orderType": "ordine", "currency": "USD", "shippingAddress": { "country": "Stati Uniti", "firstName": "John", "lastName": "Doe", "addressLine1": "Via Principale 123", "city": "New York", "postCode": "10001", "state": "NY", "email": "[email protected]", "telefono": "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, "files": [ { "type": "predefinito", "url": "https://example.com/files/printfile.pdf" } ] } ]}'Esempio di risposta
{ "id": "32884a3e-bd09-42be-8225-c5cea7d24611", "orderReferenceId": "YOUR-ORDER-123", "createdAt": "13/04/2025 10:23:28"}Utilizzare i prodotti dei clienti
Invece di specificare un productUid, puoi usare i prodotti cliente con productName e productVariant:
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": "YOUR-ORDER-124", "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", "productName": "Biglietto da visita", "productVariant": { "Size": "Standard", "Paper": "Carta premium opaca", "Color": "Colore su entrambi i lati" }, "quantity": 100, "files": [ { "type": "fronte", "url": "https://example.com/files/front.pdf" }, { "type": "retro", "url": "https://example.com/files/back.pdf" } ] } ]}'Ordini internazionali
Per gli ordini internazionali, indica i prezzi al dettaglio per le dichiarazioni doganali:
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": "INTL-ORDER-456", "orderType": "ordine", "currency": "EUR", "retailCurrency": "GBP", "retailShippingPriceInclVat": 6,99, "shippingAddress": { "country": "DE", "firstName": "Hans", "lastName": "Schmidt", "addressLine1": "Unter den Linden 10", "city": "Berlino", "postCode": "10117", "email": "[email protected]", "phone": "+49123456789" }, "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, "retailPriceInclVat": 19,99, "file": [ { "type": "default", "url": "https://example.com/files/printfile.pdf" } ] } ]}'Problemi frequenti
Campi obbligatori mancanti: assicurati di includere tutti i campi richiesti nella tua richiesta.
URL dei file non validi: assicurati che gli URL dei tuoi file siano accessibili pubblicamente.
UID prodotto sconosciuto: verifica che il UID del prodotto esista oppure usa prodotti personalizzati.
ID riferimento ordine duplicato: usa un ID riferimento ordine unico per ogni ordine.
Annulla Ordine
L'endpoint Annulla ordine ti permette di fermare la produzione e la spedizione di un ordine che non è ancora stato spedito.
Endpoint: POST /{orderCancelUrl}/{orderId}/cancel
Esempio di richiesta
# Annulla usando l'ID ordine Gelatocurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611/cancel' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto'# Annulla usando il tuo ID di riferimento ordinecurl --location --request POST 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123/cancel' \--header 'X-API-KEY: your-key:your-secret'Esempio di risposta
{ "code": 200, "message": "OK"}Problemi frequenti
Ordine già spedito: Gli ordini già spediti non possono essere annullati.
Ordine non trovato: verifica che l'ID ordine o l'ID di riferimento siano corretti.
Problemi di autenticazione: controlla che la tua chiave API e il segreto siano corretti.
Aggiorna spedizione
L'endpoint Update Shipment ti permette di cambiare il metodo di spedizione o aggiornare l'indirizzo di consegna per un ordine che non è ancora stato spedito.
Endpoint: POST /{updateShipmentURL}/{orderId}
Esempio di richiesta
# Aggiorna i dettagli di spedizionecurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ "shipmentMethodUid": "fed_ex_2_day", "shippingAddress": { "country": "US", "firstName": "Jane", "lastName": "Smith", "addressLine1": "456 Park Ave", "city": "New York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }}'# Aggiorna solo il metodo di spedizionecurl --location --request PUT 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ "shipmentMethodUid": "fed_ex_2_day"}'Esempio di risposta
{ "shippingAddress": { "id": "2f85d65b-4814-4b5f-90a2-a7de28250bd1", "orderId": "32884a3e-bd09-42be-8225-c5cea7d24611", "country": "US", "firstName": "Jane", "lastName": "Smith", "addressLine1": "456 Park Ave", "city": "New York", "postCode": "10022", "state": "NY", "email": "[email protected]", "phone": "987-654-3210" }, "spedizione": { "shipmentMethodUid": "fed_ex_2_day", "shipmentMethodName": "FedEx 2Day", "fulfillmentCountry": "US", "fulfillmentFacilityId": "db0622e7-d7af-4453-b39f-cdf1b67f3daa", "packageCount": 1, "initialMinDeliveryDate": "15/04/2025", "initialMaxDeliveryDate": "15/04/2025", "serviceType": "normale" }}Problemi frequenti
Ordine già spedito: non è possibile aggiornare i dettagli di spedizione per gli ordini già spediti.
Campi obbligatori mancanti: assicurati di inserire tutti i campi richiesti nell'indirizzo di spedizione.
Metodo di spedizione non valido: controlla che il UID del metodo di spedizione sia corretto.
Ordine non trovato: controlla che l'ID ordine o l'ID di riferimento siano corretti.
Recupera ordine
L'endpoint Get Order ti permette di recuperare informazioni dettagliate su un ordine esistente.
Endpoint: POST /{getOrderURL}/{orderId}
Esempio di richiesta
# Recupera l’ordine usando l’ID ordine Gelatocurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/32884a3e-bd09-42be-8225-c5cea7d24611' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto'# Trova l’ordine con il tuo ID di riferimentocurl --location --request GET 'https://api.partner-connect.io/api/{partner-prefix}/YOUR-ORDER-123' \--header 'X-API-KEY: your-key:your-secret'Esempio di risposta
La risposta include informazioni dettagliate sull'ordine, tra cui:
Dettagli dell’ordine (ID, riferimento, stato, date e orari)
Indirizzo di spedizione
Articoli ordinati
Informazioni sulla spedizione
Informazioni finanziarie
Per via della lunghezza della risposta, consulta la documentazione API per vedere la struttura completa della risposta.
Come usare i dati di risposta
La risposta Get Order ti dà informazioni preziose che puoi usare per:
Mostra lo stato dell'ordine: fai vedere ai clienti a che punto sono i loro ordini.
Traccia le spedizioni: recupera le informazioni di tracciamento per seguire le tue spedizioni.
Controlla i dettagli dell’ordine: Assicurati che tutte le informazioni siano corrette.
Analizza la cronologia ordini: crea report e analisi basati sui dati degli ordini.
Problemi frequenti
Ordine non trovato: controlla che l'ID ordine o l'ID di riferimento siano corretti.
Problemi di autenticazione: controlla che la tua API key e il tuo secret siano corretti.
Cerca ordini
L'endpoint Search Orders ti permette di visualizzare un elenco di ordini in base a criteri specifici.
Endpoint: POST /{searchOrdersURL}
Esempio di richiesta
# Cerca per stato di realizzazionecurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto' \--data '{ "fulfillmentStatus": ["spedito", "consegnato"]}'# Cerca per intervallo di datecurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto' \--data '{ "startDate": "01/01/2025 00:00", "endDate": "13/04/2025 23:59:59"}'# Cerca per ID di riferimento ordinecurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--data '{ "orderReferenceId": "YOUR-ORDER-123"}'# Ricerca con paginazionecurl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto' \--data '{ "fulfillmentStatus": ["creato", "stampato"], "limite": 50, "offset": 0}'Esempio di risposta
{ "ordini": [ { "id": "9f9ff09f-5891-4d3d-be35-9b302db835a1", "clientId": "ddb4371a-ad83-4f68-b99d-6b48c7eff366", "orderReferenceId": "YOUR-ORDER-123", "fulfillmentStatus": "spedito", "financialStatus": "pagato", "currency": "USD", "totalInclVat": "33,45", "orderType": "ordine", "channel": "api", "firstName": "John", "lastName": "Doe", "country": "US", "itemsCount": 1, "createdAt": "10/04/2025 11:05:09", "updatedAt": "10/04/2025 14:05:10", "orderedAt": "10/04/2025 11:05:07", "customerReferenceId": "CUST-456" }, // Altri ordini... ]}Paginazione
L'endpoint Search Orders supporta la paginazione per gestire grandi quantità di risultati:
# Prima pagina (50 elementi)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: your-key:your-secret' \--dati '{ "fulfillmentStatus": ["spedito"], "limite": 50, "offset": 0}'# Seconda pagina (prossimi 50 elementi)curl --location 'https://api.partner-connect.io/api/{partner-prefix}/search' \--header 'Content-Type: application/json' \--header 'X-API-KEY: la-tua-chiave:il-tuo-segreto' \--dati '{ "fulfillmentStatus": ["spedito"], "limite": 50, "offset": 50}'Situazioni tipiche di ricerca
Ordini per stato:
{ "fulfillmentStatus": ["creato", "stampato"] }Ordini per intervallo di date:
{ "startDate": "01/04/2025 00:00:00", "endDate": "13/04/2025 23:59:59"}Ordini per paese:
{ "countries": ["US", "CA"] }Unire i criteri:
{ "fulfillmentStatus": ["spedito"], "countries": ["US"], "startDate": "01/04/2025 00:00:00"}
Problemi frequenti
Nessun risultato: controlla che i criteri di ricerca non siano troppo restrittivi.
Troppi risultati: usa la paginazione e/o altri filtri per restringere la ricerca.
Formato non valido: assicurati che le date seguano il formato ISO 8601 (YYYY-MM-DDTHH:MM:SS+00:00).
Collegare i template agli endpoint API
Quando invii ordini tramite API, spesso dovrai trasformare i dati dal tuo formato a quello di GelatoConnect. I template gestiscono questa trasformazione, ma devi collegare esplicitamente il tuo template all'endpoint API perché venga applicato.
Come collegare un template a un endpoint di invio ordine:
Vai alla tua lista di connettori e clicca sul link Modifica accanto all'endpoint di invio ordine.
Nella pagina di configurazione dell'endpoint, trova la sezione Modello endpoint
Seleziona il tuo modello di invio ordine dal menu a tendina
Fai clic sul pulsante Imposta endpoint in alto a destra nella pagina
Fai clic su Salva modifiche in alto a destra per applicare la tua configurazione
Dopo aver completato questi passaggi, tutte le richieste d’ordine inviate a questo endpoint useranno il tuo template per trasformare i dati prima dell’elaborazione. Così il formato del tuo sistema verrà convertito correttamente nel formato previsto da GelatoConnect.
Senza questa configurazione, il tuo template non verrà applicato anche se esiste ed è stato progettato correttamente; questo può causare errori nella convalida degli ordini se il formato dei tuoi dati non corrisponde esattamente ai requisiti di GelatoConnect.
Le migliori pratiche per integrare
Quando integri con gli endpoint API degli ordini, tieni a mente queste best practice:
1. ID ordine del negozio
Conserva sempre sia il tuo ID di riferimento ordine che l’ID ordine Gelato restituito nella risposta. Così sarà più semplice tracciare e trovare gli ordini in entrambi i sistemi.
2. Gestisci gli errori con eleganza
Gestisci correttamente gli errori per ogni chiamata API; analizza il messaggio di errore nella risposta per offrire un feedback utile a chi usa l’App e implementa soluzioni di recupero adeguate.
Per scoprire come gestire gli errori in modo efficace, dai un'occhiata alla sezione "Best practice per la gestione degli errori" nella Order Management API Documentation.
3. Implementa l'idempotenza
Genera un riferimento ordine unico per ogni ordine e usa il parametro preventDuplicate per assicurarti che, anche in caso di problemi di rete e di un nuovo tentativo, l’ordine non venga inviato due volte.
4. Usa le notifiche Webhook
Invece di controllare continuamente lo stato degli ordini, imposta le notifiche Webhook per ricevere aggiornamenti in tempo reale quando lo stato degli ordini cambia.
5. Controlla i dati prima di inviarli
Controlla i dati dell’ordine prima di inviarli all’API: così puoi evitare errori evidenti e offrire un’esperienza migliore a chi usa l’App.
6. Implementa una logica di ripetizione
Aggiungi una logica di ripetizione con backoff esponenziale per gli errori temporanei, soprattutto per le risposte di limite di velocità (429).
Per i dettagli sull'implementazione di exponential backoff e jitter, consulta la sezione "Rate Limit Best Practices" nella Order Management API Documentation oppure il blog post di AWS su exponential backoff e jitter.
7. Ottimizza le ricerche
Sii preciso nei criteri di ricerca per ottenere meno risultati e migliorare le prestazioni.
8. Memorizza i dati di riferimento nella cache
Memorizza gli UID dei prodotti e altri dati di riferimento per ridurre il numero di chiamate API necessarie.
Conclusione
L'Order API di GelatoConnect offre una serie di endpoint potenti per gestire tutto il ciclo di vita degli ordini. Se impari a usare questi endpoint in modo efficace, puoi creare un'integrazione senza intoppi tra i tuoi sistemi e GelatoConnect.
Per informazioni più dettagliate, consulta la documentazione API di gestione ordini.