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-KEY alla tua richiesta
Imposta 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": "order",
  "currency": "USD",
  "shippingAddress": {
    "country": "US",
    "firstName": "John",
    "lastName": "Doe",
    "addressLine1": "123 Main St",
    "city": "New York",
    "postCode": "10001",
    "state": "NY",
    "email": "[email protected]",
    "phone": "1234567890"
  },
  "items": [
    {
      "itemReferenceId": "item-123",
      "productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
      "quantity": 1,
      "files": [
        {
          "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}/order

Inserisci 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": "2025-04-12T10:23:28+00:00"
}

Il campo id contiene l'ID ordine 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}/cancel

Cerca ordini

Trova gli ordini in base a criteri specifici:

POST https://api.partner-connect.io/api/{partner-prefix}/search

Aggiorna 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": "Business Card",
  "productVariant": {
    "Size": "Standard",
    "Paper": "Premium Matte",
    "Color": "Full Color Both Sides"
  }
}

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:

Test con ordini di prova: crea ordini di prova con quantità ridotte e verifica che vengano visualizzati correttamente in 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:secret nell'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

Cosa fare adesso

Ora che conosci le basi dell'API GelatoConnect, sei pronto per:

leggi la documentazione completa delle API per informazioni dettagliate sugli endpoint
Scopri le best practice delle API per autenticazione, limiti di velocità e gestione degli errori
Esplora come lavorare con gli endpoint API per esempi dettagliati di operazioni

Per ulteriore supporto con la tua integrazione API, contatta il nostro team di supporto all'indirizzo [email protected].

[Inizia adesso - GCW] Inizia adesso con l'API GelatoConnect