Amazon SP-API: guida pratica all'integrazione seller

Amazon è un canale imprescindibile per molti venditori, ma la sua integrazione ha regole proprie. La Selling Partner API (SP-API) è l'interfaccia ufficiale lato seller, e capirne la struttura è il primo passo per costruire un'integrazione solida a partire dall'ERP.

Autenticazione: LWA

L'accesso passa per Login with Amazon (LWA): l'applicazione ottiene un refresh token in fase di autorizzazione e da questo ricava gli access token a scadenza breve. I refresh token vanno protetti (es. in Azure Key Vault) e gli access token cachati e rinnovati prima della scadenza.

Le aree principali

Area	A cosa serve
Listings Items	Creare e aggiornare prodotti e offerte
Feeds	Operazioni massive e asincrone sul catalogo
Orders	Importare e gestire gli ordini
Reports	Estrazioni asincrone (inventario, vendite, settlement)
Finances	Eventi finanziari e riconciliazione

Listings: puntuale, Feeds: massivo

Per aggiornamenti singoli e immediati si usa la Listings Items API; per grandi volumi conviene la Feeds API, che lavora in modo asincrono: si carica un documento, si crea un feed e si monitora il job fino a leggerne l'esito. La scelta tra i due dipende da volume e latenza richiesta.

Ordini e report

Gli ordini si importano con la Orders API tramite polling incrementale; molte estrazioni (inventario, vendite, settlement per la riconciliazione) passano invece dai Report, anch'essi asincroni: si richiede il report, si attende il completamento, si scarica il documento. Il pattern asincrono ricorre, quindi vale la pena standardizzarlo.

Rate limit e robustezza

SP-API applica limiti con un modello a "rate + burst". Servono throttling lato client, backoff con jitter e idempotenza, esattamente come per le altre API marketplace. La gestione degli errori va distinta tra transitori (retry) e permanenti (correzione del dato).

Mappare il catalogo

Amazon richiede attributi specifici per tipo di prodotto (product type) e identificatori. Come per ogni marketplace, il valore sta nel layer di mapping e validazione dal modello interno al formato Amazon, eseguito prima dell'invio per intercettare gli errori a monte.

Architettura su Azure

Una integrazione SP-API su Microsoft Azure combina: gestione sicura dei token (Key Vault + Managed Identity), Functions schedulate per ordini e report, code per le operazioni Feed e i loro job asincroni, worker con retry e rate limiting, e osservabilità con correlation ID per seguire ogni operazione end-to-end.

Esempio pratico: token LWA e chiamata Orders

In produzione separo sempre il recupero del token dalla chiamata applicativa: il worker chiede un access token a un servizio interno, che legge il refresh token da Key Vault, lo rinnova se necessario e lo mette in cache per pochi minuti. La chiamata applicativa non vede mai il refresh token.

POST https://api.amazon.com/auth/o2/token
content-type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=Atzr|...
&client_id=amzn1.application-oa2-client....
&client_secret=...

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders?MarketplaceIds=APJ6JRA9NG5V4&CreatedAfter=2026-06-21T00:00:00Z
x-amz-access-token: <lwa-access-token>
user-agent: erp-marketplace-sync/1.0

La risposta va salvata con una chiave idempotente: AmazonOrderId più marketplace. Se un job viene rieseguito dopo un timeout, l'ordine non deve essere duplicato in ERP.

Runbook operativo per feed e report asincroni

1. crea il documento di feed/report e salva feedDocumentId o reportDocumentId con un correlation ID interno;
2. crea il job (createFeed o createReport) e accodalo con stato Submitted;
3. polling con backoff: ogni tentativo legge stato, quota residua e prossimo retry;
4. su DONE, scarica il documento, archivia il raw file e importa solo righe valide;
5. su FATAL o errori di validazione, ferma il retry e manda il dettaglio al team catalogo.

Un caso ricorrente: catalogo da 40.000 SKU con prezzi aggiornati ogni ora. Uso Listings per fix puntuali su pochi SKU urgenti, Feeds per riallineamenti massivi notturni e Reports per verificare lo stato accettato da Amazon.

Errori comuni

• refresh token non protetti o access token non rinnovati;
• uso delle Listings per volumi che richiederebbero i Feeds;
• polling ordini senza idempotenza, con duplicati;
• nessuna gestione dei job asincroni di feed e report.

Conclusione

La SP-API è potente ma asincrona e ricca di regole. Padroneggiare autenticazione LWA, la distinzione Listings/Feeds, la natura asincrona di ordini e report e i pattern di resilienza è ciò che rende un'integrazione Amazon affidabile. Documentazione ufficiale: Amazon SP-API (developer docs).