eBay Inventory API: dal catalogo ERP all'inserzione (SKU → listing)

La eBay Inventory API è la parte della Sell API che gestisce prodotti, prezzi e disponibilità con un modello vicino a quello di ERP e magazzini: si ragiona per SKU e non per singola inserzione. Capire questo modello è il passo che rende un'integrazione manutenibile invece che fragile.

Il modello a quattro livelli

La Inventory API separa il concetto di prodotto dal concetto di inserzione. Il flusso è:

1. SKU: l'identificatore univoco che arriva dal gestionale;
2. Inventory item: il prodotto a inventario, con attributi, immagini e quantità;
3. Offer: l'offerta commerciale (prezzo, marketplace, categoria, policy);
4. Listing: l'inserzione pubblicata che nasce dalla pubblicazione dell'offerta.

La separazione tra inventory item e offer è preziosa: lo stesso prodotto può avere offerte diverse su marketplace diversi, e un aggiornamento di stock tocca l'inventory item senza ricostruire l'offerta.

Le chiamate principali

Operazione	Chiamata
Creare/aggiornare prodotto	createOrReplaceInventoryItem
Creare l'offerta	createOffer
Pubblicare l'inserzione	publishOffer
Aggiornare solo lo stock	createOrReplaceInventoryItem (campo availability)
Caricamenti massivi	bulkCreateOrReplaceInventoryItem

Varianti e gruppi

Per i prodotti con taglie e colori si usa l'inventory item group: i singoli SKU restano prodotti a inventario, mentre il gruppo li unisce in un'unica inserzione con varianti. È fondamentale mappare correttamente gli aspetti (es. taglia, colore) sugli attributi richiesti dalla categoria, altrimenti la pubblicazione fallisce.

Aggiornamenti incrementali

Il vantaggio del modello è che un cambio di prezzo o quantità non richiede di ripubblicare tutto. Conviene quindi:

• distinguere gli eventi: nuovo prodotto, aggiornamento stock, aggiornamento prezzo, ritiro;
• inviare solo i delta, non l'intero catalogo a ogni sincronizzazione;
• usare le operazioni bulk per i grandi volumi, rispettando i limiti di dimensione.

Mappare il catalogo ERP

Il punto critico non è la chiamata, ma la trasformazione dei dati. Il gestionale parla la sua lingua (codici interni, categorie merceologiche), eBay un'altra (aspetti, condizioni, categorie marketplace). Un layer di mapping converte e valida prima della pubblicazione: identificatori prodotto (GTIN/EAN), attributi obbligatori, immagini conformi, descrizioni.

Architettura su Azure

Una sincronizzazione catalogo affidabile su Microsoft Azure può prevedere un componente che intercetta i cambi nell'ERP, un mapping che prepara i payload e worker che chiamano la Inventory API con retry e gestione dei limiti, registrando esito e differenze per ogni SKU.

Esempio payload: item, offer e stock delta

Il primo invio crea o sostituisce l'inventory item. Qui salvo sempre anche il payload normalizzato, così un errore di pubblicazione può essere riprodotto senza rileggere l'ERP.

PUT /sell/inventory/v1/inventory_item/TSHIRT-BLK-M
{
  "availability": {
    "shipToLocationAvailability": { "quantity": 15 }
  },
  "condition": "NEW",
  "product": {
    "title": "T-shirt nera taglia M",
    "description": "Cotone 100%, vestibilita regular",
    "aspects": { "Size": ["M"], "Color": ["Black"] },
    "imageUrls": ["https://cdn.example.com/tshirt-black-m.jpg"]
  }
}

L'offerta commerciale resta separata. Il prezzo cambia più spesso della descrizione, quindi lo tratto come evento diverso.

POST /sell/inventory/v1/offer
{
  "sku": "TSHIRT-BLK-M",
  "marketplaceId": "EBAY_IT",
  "format": "FIXED_PRICE",
  "availableQuantity": 15,
  "pricingSummary": { "price": { "value": "24.90", "currency": "EUR" } },
  "listingPolicies": {
    "fulfillmentPolicyId": "123",
    "paymentPolicyId": "456",
    "returnPolicyId": "789"
  },
  "categoryId": "15687",
  "merchantLocationKey": "WAREHOUSE_IT"
}

Per un delta stock successivo non ricreo l'offerta: aggiorno solo availability.shipToLocationAvailability.quantity sull'inventory item e traccio differenza precedente/nuova per audit.

Errori comuni

• ricostruire l'intera inserzione a ogni aggiornamento di stock;
• non gestire i gruppi di varianti e creare inserzioni duplicate;
• dimenticare gli identificatori prodotto richiesti dalla categoria;
• inviare l'intero catalogo invece dei soli delta, saturando le API.

Conclusione

La Inventory API premia chi adotta il suo modello a SKU: prodotti a inventario, offerte e inserzioni separate, aggiornamenti incrementali e validazione a monte. È la base per allineare il catalogo ERP a eBay in modo scalabile. Documentazione ufficiale: eBay Inventory API — Overview.