eBay Fulfillment API: sincronizzare ordini e spedizioni passo-passo

Pubblicare le inserzioni è solo metà del lavoro. La parte che fa davvero la differenza in produzione è la gestione operativa degli ordini: importarli, evaderli, spedirli e riportare il tracking su eBay. È qui che entra in gioco la eBay Fulfillment API, parte della famiglia Sell API dedicata al ciclo di vita dell'ordine.

Che cosa copre la Fulfillment API

La Fulfillment API espone gli ordini lato venditore e le azioni necessarie a evaderli. In pratica permette di:

• recuperare gli ordini con getOrders filtrando per data o stato;
• leggere il dettaglio di un singolo ordine con getOrder;
• creare la spedizione e inviare il tracking con createShippingFulfillment;
• gestire rimborsi, contestazioni e richieste di reso.

Il ciclo di vita di un ordine

Un'integrazione robusta non si limita a "scaricare gli ordini". Modella gli stati e li fa avanzare in modo controllato:

Fase	Azione integrazione
Nuovo ordine	Polling o notifica, import e deduplica per orderId
In lavorazione	Creazione ordine in ERP/magazzino e prenotazione stock
Spedito	Invio di corriere e tracking number con createShippingFulfillment
Chiuso	Riconciliazione con payout e gestione di eventuali resi

Import affidabile: polling e idempotenza

Il modo più semplice per importare è il polling incrementale: si interroga getOrders con un filtro sulla data di ultima modifica e si salva un checkpoint. Due regole sono essenziali:

• Idempotenza: usa orderId come chiave univoca per non creare ordini duplicati se la stessa pagina viene processata due volte;
• Finestra di sovrapposizione: interroga con un piccolo margine temporale rispetto all'ultimo checkpoint, per non perdere ordini arrivati al confine della finestra.

Inviare la spedizione e il tracking

Quando il magazzino spedisce, l'integrazione chiama createShippingFulfillment indicando le righe spedite, il corriere e il codice di tracking. eBay aggiorna lo stato dell'ordine e notifica l'acquirente. Punti di attenzione:

• gestire le spedizioni parziali quando non tutte le righe partono insieme;
• normalizzare i nomi dei corrieri sui valori accettati da eBay;
• ritentare in caso di errore temporaneo senza inviare due volte lo stesso tracking.

Perché serve un flusso asincrono

In un negozio reale gli ordini arrivano a raffica e i sistemi non sono sempre allineati. Conviene disaccoppiare import ed evasione con code e worker: un componente importa e mette in coda, un altro evade e aggiorna. Così un picco di ordini o un errore del magazzino non blocca l'intera pipeline, e i retry diventano sicuri grazie all'idempotenza.

Architettura tipica su Azure

Una pipeline ordini affidabile su Microsoft Azure può combinare:

• Azure Functions a tempo (timer trigger) per il polling degli ordini;
• Service Bus per accodare gli ordini importati;
• Worker che evadono, sincronizzano l'ERP e inviano il tracking;
• database per checkpoint, stato e log delle operazioni.

Errori da evitare

• importare senza deduplica e creare ordini doppi;
• inviare tracking sincrono dal magazzino senza retry o idempotenza;
• ignorare resi e rimborsi, che spostano lo stato e il valore dell'ordine;
• non monitorare i fallimenti: senza alert ci si accorge dei problemi dai feedback negativi.

Conclusione

La Fulfillment API è il cuore operativo di un'integrazione eBay. Importare ordini in modo idempotente, evaderli con flussi asincroni e riportare il tracking in modo affidabile è ciò che distingue una demo da un sistema che regge i volumi reali. Documentazione ufficiale: eBay Fulfillment API — Overview.