Errori comuni nelle integrazioni eBay (e come evitarli)

Le integrazioni eBay falliscono raramente per la "chiamata sbagliata" e quasi sempre per cattive abitudini strutturali: gestione dei token, limiti API, validazione, idempotenza. Ecco gli errori che vediamo più spesso e come evitarli.

1. Trattare la Sell API come un pulsante "pubblica"

La Sell API non è un bottone "metti su eBay": è uno strato di integrazione tra i sistemi interni e il marketplace. Pensarla così porta a saltare account, policy, validazione e riconciliazione. Soluzione: progettare il flusso completo, non solo la pubblicazione.

2. Gestire male i token OAuth

Gli access token scadono e i refresh token vanno conservati in sicurezza. Hardcodare credenziali o non rinnovare i token genera errori 401 intermittenti. Soluzione: centralizzare i segreti (es. Azure Key Vault), rinnovare i token prima della scadenza e gestire il refresh in modo concorrente-sicuro.

3. Ignorare i rate limit

eBay applica limiti di chiamata. Chi non li rispetta riceve errori e, nei casi peggiori, blocchi temporanei. Soluzione: throttling lato client, backoff esponenziale con jitter e gestione esplicita delle risposte di limite.

4. Nessuna idempotenza

Senza chiavi idempotenti, un retry crea ordini doppi, tracking doppio, registrazioni doppie. Soluzione: usare identificatori univoci (orderId, transactionId, SKU) come chiavi e rendere ogni operazione ripetibile senza effetti collaterali.

5. Saltare la validazione pre-pubblicazione

Pubblicare senza verificare categoria, aspetti obbligatori, identificatori prodotto e policy porta a errori a valle, difficili da diagnosticare. Soluzione: validare i dati con i Metadata prima di chiamare publishOffer.

6. Account venditore non pronto

Mancano payment, return o fulfillment policy compatibili con la categoria e la pubblicazione fallisce. Soluzione: verificare la readiness dell'account in fase di onboarding e rendere gli errori comprensibili.

7. Confondere ordini e incassi

Un ordine non è un payout: commissioni e rimborsi cambiano l'importo. Soluzione: usare la Finances API e riconciliare le transazioni con i payout.

8. Flussi sincroni e fragili

Chiamare le API in linea con l'azione dell'utente o del magazzino rende il sistema fragile ai picchi. Soluzione: code, worker e processi asincroni con retry.

9. Nessun monitoraggio

Senza log strutturati e alert, gli errori si scoprono dai feedback negativi. Soluzione: log con correlation ID, metriche di business e alert sulle anomalie.

10. Sincronizzare tutto, sempre

Inviare l'intero catalogo a ogni ciclo satura le API. Soluzione: lavorare per delta e usare le operazioni bulk solo dove necessario.

Conclusione

Quasi tutti questi errori hanno la stessa radice: trattare l'integrazione come uno script invece che come un sistema. Token, limiti, idempotenza, validazione e monitoraggio non sono dettagli: sono ciò che rende un'integrazione eBay affidabile nel tempo. Documentazione ufficiale: eBay Sell API — Overview.