Integrare il tuo gestionale con l'API E-SHIPPY

Chi gestisce ordini con un proprio gestionale, un ERP interno o un sito custom — non Shopify — non ha bisogno di un'app pronta: ha bisogno di un'API. E-SHIPPY espone un'API REST pubblica pensata proprio per questo: creare spedizioni, ricevere le tariffe reali e integrare il flusso di spedizione nel proprio sistema, senza passare dalla dashboard a mano ordine per ordine.

Come funziona l'autenticazione delle API E-SHIPPY?

L'accesso all'API avviene tramite una chiave (API key) generata dalla dashboard, con prefisso riconoscibile esk_live_. La chiave va passata come Bearer token nell'header Authorization di ogni richiesta. Non c'è OAuth né flusso di autorizzazione complesso: si genera la chiave una volta, si usa in ogni chiamata, e si può rigenerare in qualsiasi momento dalla dashboard se sospetti che sia stata compromessa.

Creare una spedizione via API

La chiamata principale crea un ordine di spedizione: destinatario, indirizzo, peso e dimensioni del collo, servizio richiesto (standard o express). Il sistema calcola la tariffa reale FedEx applicando lo stesso margine e le stesse tariffe riservate della piattaforma — non è un prezzo stimato, è lo stesso motore di pricing usato dalla dashboard. Una spedizione può contenere fino a 20 colli in un'unica chiamata, utile per ordini multi-pacco senza dover ripetere la chiamata collo per collo.

Ogni richiesta di creazione ordine richiede un campo idempotency_key — una stringa univoca che generi tu, tipicamente derivata dall'ID dell'ordine nel tuo gestionale. Usarla garantisce idempotenza: se la stessa richiesta arriva due volte con la stessa chiave (per un retry di rete, ad esempio), il sistema riconosce che è lo stesso ordine e non crea una spedizione duplicata. Per un'integrazione automatica è la protezione più importante da implementare fin dal primo test: evita doppioni costosi in caso di errore di rete lato tuo sistema. C'è anche un campo separato opzionale reference, pensato per un riferimento leggibile (es. il numero d'ordine del tuo gestionale) che compare nelle liste della dashboard — se lo ometti, la dashboard mostra la idempotency_key al suo posto.

Un esempio di richiesta

A titolo illustrativo, il corpo di una richiesta di creazione spedizione ha questa forma (valori di esempio, non un endpoint reale da copiare senza adattarlo al tuo caso):

{
  "idempotency_key": "ordine-gestionale-10234",
  "reference": "ORD-10234",
  "recipient": {
    "name": "Mario Rossi",
    "address": "Via Roma 12",
    "city": "Milano",
    "postal_code": "20100",
    "country": "IT",
    "phone": "+39 333 1234567"
  },
  "parcel": {
    "type": "package",
    "weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15
  },
  "service": "standard",
  "colli": 1
}

La risposta include l'ID spedizione E-SHIPPY, la tariffa reale applicata e — una volta confermata la creazione — il numero di tracking. Il campo parcel.type distingue tra package (collo standard) e envelope (busta, con limiti di peso e dimensioni più stretti); se lo ometti, il sistema tratta la spedizione come un collo standard per compatibilità con integrazioni scritte prima che questo campo esistesse.

Limiti di frequenza (rate limit)

L'API applica limiti pensati per un uso normale di integrazione, non per bloccare un flusso legittimo: 100 richieste al minuto per indirizzo IP sulla creazione ordini, un limite separato di 60 richieste al minuto sulle chiamate di lettura (consultazione stato), e un tetto giornaliero di 500 creazioni ordine per account. Per la stragrande maggioranza dei gestionali — anche con volumi di alcune centinaia di ordini al giorno distribuiti nell'arco della giornata — questi limiti non vengono mai avvicinati. Se il tuo caso d'uso prevede batch molto concentrati (es. migliaia di ordini importati in pochi minuti), è meglio distribuire le chiamate nel tempo piuttosto che sparare tutto in un'unica raffica.

Come sapere se una spedizione ha cambiato stato? (polling, non ancora webhook)

Una precisazione onesta, perché è il punto dove un'integrazione può andare storta se non lo sai in anticipo: oggi l'API non invia notifiche push (webhook) quando lo stato di una spedizione cambia. Il sistema di webhook esiste lato infrastruttura ma non è ancora raggiungibile da un'interfaccia per registrare il proprio endpoint di ricezione — quindi, per ora, sapere se una spedizione è stata evasa, è in transito o è stata consegnata richiede interrogare periodicamente l'API di lettura ordini (polling), non ricevere una notifica in tempo reale. Se il tuo gestionale ha bisogno di sapere lo stato aggiornato, imposta un job che interroga l'endpoint di lettura a intervalli ragionevoli (ogni 15-30 minuti è più che sufficiente per la maggior parte dei casi, e resta ampiamente dentro il limite di 60 richieste al minuto). Aggiorneremo questo articolo quando la registrazione webhook diventerà disponibile dall'interfaccia.

Confronto con l'app Shopify: quando usare cosa

Se vendi tramite Shopify, l'app ufficiale è quasi sempre la scelta più semplice: collegamento in due minuti, nessuna riga di codice, sincronizzazione automatica di tracking e stato. L'API REST ha senso quando Shopify non è la piattaforma di vendita (un gestionale interno, un ERP, un sito custom, un marketplace con integrazione propria) o quando serve un controllo più fine sul flusso — ad esempio decidere programmaticamente quale servizio scegliere in base a regole del tuo sistema, invece di scegliere manualmente da dashboard. Le due integrazioni non sono in conflitto: un negozio con sia Shopify sia un gestionale interno per altri canali può usare entrambe in parallelo, ognuna sul proprio flusso di ordini.

Consultare lo stato di una spedizione

Oltre alla creazione, l'API espone un endpoint di lettura per consultare lo stato di uno o più ordini — utile sia per il polling periodico già descritto, sia per una query puntuale (es. quando un cliente scrive al tuo servizio assistenza chiedendo dov'è il suo pacco, e il tuo gestionale interroga l'API in tempo reale invece di aprire la dashboard E-SHIPPY a mano). Questo endpoint ha un limite di frequenza separato da quello di creazione proprio per questo uso — query frequenti e leggere non consumano la stessa quota delle chiamate che generano spedizioni reali.

Spedizioni verso l'estero via API

Per ordini extra-UE creati via API, il sistema applica dati doganali di default (motivo spedizione e descrizione merce generici) piuttosto che i dettagli specifici riga per riga dell'ordine — la stessa logica di semplificazione già descritta per la creazione manuale da dashboard. Per volumi alti di spedizioni extra-UE via API, vale la pena verificare con il team E-SHIPPY se il caso d'uso specifico richiede una configurazione diversa.

Gestione degli errori

L'API risponde con codici di stato HTTP standard: 401 per chiave API mancante o non valida, 422 per un corpo della richiesta che non rispetta il formato atteso (con un messaggio che indica esattamente quale campo non va bene, non un errore generico), 429 quando superi il rate limit, 200 per una creazione riuscita. Un'integrazione robusta dovrebbe distinguere questi casi: un 422 indica un problema nei dati che invii (da correggere nel tuo sistema, non da ritentare uguale), mentre un 429 o un errore 5xx temporaneo può essere ritentato con un breve backoff — proprio la idempotency_key rende sicuro ritentare senza rischio di duplicati.

Sicurezza della chiave API

La chiave API ha lo stesso livello di sensibilità di una password: chiunque la possieda può creare spedizioni (e quindi generare costi) sul tuo account. Alcune buone pratiche di base: non inserirla mai in codice lato client (un sito o un'app che gira nel browser dell'utente), tenerla solo in variabili d'ambiente o in un secret manager lato server, e rigenerarla subito dalla dashboard se sospetti sia stata esposta per errore (es. commit su un repository pubblico).

Ambiente di test prima del collegamento definitivo

Prima di collegare il flusso automatico del gestionale, vale sempre la pena fare alcune chiamate manuali di test con un ordine reale a basso valore — verificando che indirizzo, peso e servizio arrivino correttamente e che la tariffa mostrata corrisponda alle aspettative. Un errore comune nelle prime integrazioni è mappare male un campo obbligatorio (es. il codice Paese a 2 lettere per recipient.country, non il nome esteso del Paese): un test manuale prima dell'automazione completa individua questo tipo di errore subito, invece che dopo aver processato decine di ordini con lo stesso problema.

Documentazione e primi passi

La documentazione completa (endpoint, formato richieste/risposte, esempi) è disponibile direttamente in dashboard, nella sezione Integrazioni. Il modo più rapido per iniziare è creare la chiave API, fare una prima chiamata di test con un ordine reale a basso valore, e verificare che tariffa e numero di spedizione arrivino come previsto, prima di collegare il flusso automatico dal gestionale.

Domande frequenti

Serve un piano specifico per usare l'API? No, l'accesso API è incluso nell'account standard E-SHIPPY, senza costi aggiuntivi oltre alle tariffe per spedizione effettuata.

L'API supporta anche i resi? L'integrazione via API è pensata principalmente per la creazione spedizioni in uscita; per la gestione strutturata dei resi automatici, l'integrazione nativa più completa oggi è quella con Shopify.

Cosa succede se supero il limite di richieste? Le chiamate oltre il limite vengono rifiutate con un errore esplicito, non silenziosamente ignorate — il tuo sistema può gestire il retry con un backoff, sapendo con certezza quando una chiamata non è stata processata.

L'API è documentata con esempi di codice in più linguaggi? La documentazione in dashboard mostra formato richiesta/risposta ed esempi; essendo un'API REST standard basata su JSON su HTTP, è compatibile con qualsiasi linguaggio che sappia fare una richiesta HTTP con header e corpo JSON, senza bisogno di un SDK dedicato per iniziare.