Documentazione API Amazon Vendor Central: guida SP-API, autenticazione e endpoint specifici per vendor
Guida completa SP-API per Amazon Vendor Central — autenticazione LWA OAuth 2.0, endpoint vendor-specific, SLA riconoscimento PO, limitazioni sandbox e errori comuni.
Indice dei contenuti
In sintesi — Punti chiave
-
SP-API ha sostituito definitivamente MWS nel gennaio 2024: tutti i vendor che usano ancora MWS devono migrare adesso.
-
L’autenticazione usa LWA OAuth 2.0 in 5 passaggi — niente chiavi API statiche, solo token temporanei con scadenza a 1 ora.
-
Gli endpoint vendor critici sono: Vendor Orders, Vendor Shipments, Vendor Inventory, Vendor Retail Procurement e Catalog Items.
-
Il riconoscimento degli ordini di acquisto ha una finestra di 24-48 ore — superarla danneggia il vendor scorecard e rischia di bloccare i PO futuri.
-
L’ambiente sandbox ha limitazioni severe: niente dati reali, rate limit ridotti, alcune operazioni non disponibili — testate con cautela.
Nel gennaio 2024 Amazon ha spento MWS. Non un avviso, non una proroga: spento. I vendor che non avevano completato la migrazione a SP-API si sono trovati con sistemi di integrazione silenziosi e pipeline di dati rotte. Se stai ancora leggendo documentazione su MWS, fermati qui — quella piattaforma non esiste più.
SP-API (Selling Partner API) è ora l’unico modo per integrare programmaticamente Amazon Vendor Central. La documentazione ufficiale è su developer-docs.amazon.com/sp-api/, ma è densa e frammentata tra sezioni pensate per seller, vendor e hybrid account. Questa guida si concentra esclusivamente sugli endpoint rilevanti per i vendor — quelli che gestiscono ordini di acquisto, spedizioni, inventario e dati di catalogo.
MWS è morto: SP-API è la piattaforma
La deprecazione non è stata improvvisa. Amazon aveva comunicato il piano di migrazione da anni. Eppure quando il sunset è arrivato, una percentuale non trascurabile di vendor ha scoperto che le proprie integrazioni interne — spesso costruite anni fa da sviluppatori che non lavorano più in azienda — non funzionavano più.
La differenza architetturale principale tra MWS e SP-API è l’autenticazione. MWS usava chiavi API statiche (Access Key + Secret Key) — semplici da implementare, difficili da ruotare in sicurezza. SP-API usa LWA (Login with Amazon) OAuth 2.0, che genera token temporanei con scadenza a 1 ora. Più sicuro, ma richiede una gestione attiva del refresh dei token — un punto dove molte implementazioni falliscono silenziosamente.
Il secondo cambiamento è strutturale: SP-API è organizzata in sezioni separate per seller e vendor. Non tutte le API disponibili per i seller sono disponibili per i vendor e viceversa. La console sviluppatori è accessibile da Seller Central (non da Vendor Central), il che crea confusione per chi gestisce solo account vendor.
2024
Anno del sunset definitivo di MWS — nessuna proroga, nessuna eccezione
Fonte: Amazon SP-API Developer Documentation
Autenticazione SP-API: il flusso LWA in 5 passaggi
Il 90% dei problemi di integrazione che vediamo nascono dall’autenticazione. Il flusso LWA non è complicato, ma ha dettagli critici che non sono enfatizzati abbastanza nella documentazione ufficiale.
Passaggio 1 — Registrazione applicazione: accedi a Seller Central → Apps & Services → Develop Apps. Crea un’applicazione SP-API. Riceverai Client ID e Client Secret. Nota: anche se gestisci solo account vendor, la registrazione avviene in Seller Central.
Passaggio 2 — Autorizzazione vendor: il vendor deve autorizzare la tua applicazione tramite OAuth redirect. L’URL di autorizzazione segue il formato: https://sellercentral.amazon.it/apps/authorize/consent?application_id={appId}&state={state}&redirect_uri={uri}. Al completamento ricevi un authorization code con scadenza di 5 minuti.
Passaggio 3 — Scambio token: POST all’endpoint LWA https://api.amazon.com/auth/o2/token con grant_type=authorization_code, il codice ricevuto, client_id, client_secret e redirect_uri. La risposta contiene access_token (scadenza 1 ora) e refresh_token (scadenza non documentata, ma tipicamente anni).
Passaggio 4 — Refresh token: prima che l’access token scada (implementa un buffer di 5 minuti), usa grant_type=refresh_token con il refresh_token. Questo è il punto dove molte implementazioni si rompono — il refresh non viene schedulato e le chiamate successive ricevono 401 Unauthorized senza una ragione ovvia.
Passaggio 5 — Firma AWS Signature Version 4: ogni chiamata SP-API deve essere firmata con AWS Signature Version 4 oltre al bearer token LWA. Hai bisogno di AWS Access Key ID, Secret Access Key e Security Token (da STS AssumeRole). Le AWS SDK gestiscono la firma automaticamente — non costruirla a mano.
Per operazioni che accedono a dati personali (PII) — come indirizzi di spedizione negli ordini di acquisto — serve un Restricted Data Token (RDT), ottenuto tramite l’endpoint /tokens/2021-03-01/restrictedDataToken prima della chiamata principale.
Endpoint vendor-specific: mappa delle sezioni critiche
SP-API ha sezioni pensate esclusivamente per vendor. Questi endpoint non sono accessibili agli account seller standard.
| Sezione API | Endpoint base | Uso principale |
|---|---|---|
| Vendor Orders | /vendor/orders/v1/ | Recupero e riconoscimento PO |
| Vendor Shipments | /vendor/shipments/v1/ | Conferma spedizione, tracking, ASN |
| Vendor Inventory | /vendor/inventories/v1/ | Stock on-hand, disponibilità warehouse |
| Vendor Retail Procurement | /vendor/retail/v1/ | Dati di vendita, analisi procurement |
| Catalog Items | /catalog/2022-04-01/items/ | Attributi prodotto, ASIN lookup |
| Product Pricing | /products/pricing/v0/ | Prezzi competitivi, Buy Box status |
SESSIONE GRATUITA
Stai integrando SP-API per un brand o un retailer?
In Epinium aiutiamo i team tecnici a costruire integrazioni SP-API solide — autenticazione, gestione PO, pipeline di dati. 30 minuti, gratis, nessun impegno.
Parliamo → ✓ Gratuito ✓ 30 min ✓ Nessun pitch
Vendor Orders API: il meccanismo dei PO e l’SLA di riconoscimento
Vendor Orders è l’API più critica per la maggior parte dei vendor. Gestisce l’intero ciclo degli ordini di acquisto — ricezione, riconoscimento e tracciamento dello stato.
Il pattern di integrazione corretto non è event-driven: SP-API non invia webhook quando Amazon crea un PO. Devi fare polling su GET /vendor/orders/v1/purchaseOrders con parametri createdAfter e createdBefore per recuperare i nuovi ordini. La raccomandazione di Amazon è ogni 15-30 minuti per vendor ad alto volume.
Quando recuperi un PO, devi riconoscerlo entro 24-48 ore tramite POST /vendor/orders/v1/acknowledgements. Il payload include il numero PO, lo stato per ogni line item (Accepted, Rejected, Backordered) e le quantità confermate. La risposta non è sincrona — ricevi un transactionId.
Qui molte implementazioni si fermano, sbagliando. Il transactionId indica solo che Amazon ha ricevuto la tua richiesta, non che l’ha elaborata. Devi fare polling su GET /vendor/orders/v1/acknowledgements/transactionStatus/{transactionId} finché lo stato non diventa Success o Failure. Senza questo polling, non sai se il riconoscimento è stato accettato.
Superare la finestra di 24-48 ore ha conseguenze reali: il vendor scorecard peggiora, e Amazon può sospendere la creazione di nuovi PO per i vendor con tassi di riconoscimento sistematicamente bassi. Per i vendor che operano su più marketplace europei — Germania, Francia, Italia, Spagna — ogni marketplace ha un suo ID specifico (A1PA6795UKMFR9 per la Germania, APJ6JRA9NG5V4 per l’Italia) e i PO non sono condivisi tra marketplace.
Limitazioni dell’ambiente sandbox SP-API
L’ambiente sandbox è accessibile sostituendo sellingpartnerapi-na.amazon.com con sandbox.sellingpartnerapi-na.amazon.com negli endpoint. Utile per testare il flusso di autenticazione e la struttura delle richieste. Ma ha limitazioni che devi conoscere prima di pianificare i tuoi test.
Primo: il sandbox restituisce dati statici predefiniti, non dati reali del tuo account vendor. Non puoi testare scenari con i tuoi PO reali o il tuo inventario. I dati sono simulati e spesso non rappresentano casi limite reali.
Secondo: non tutte le operazioni sono disponibili in sandbox. Alcuni endpoint vendor-specific — in particolare quelli legati a Retail Procurement — non hanno implementazione sandbox e restituiscono errori 404 o 501 che potrebbero confondersi con errori di configurazione.
Terzo: i rate limit in sandbox sono più restrittivi che in produzione per alcune sezioni, meno per altre. Non usare le performance sandbox per dimensionare la frequenza di polling in produzione.
Una nota importante: Amazon pubblica test case specifici per sandbox, con payload di richiesta e risposta documentati per ogni scenario. Usali — riduce significativamente il tempo di debugging in fase di sviluppo.
Errori comuni nelle integrazioni SP-API vendor
Dopo aver visto decine di implementazioni, questi sono i pattern di fallimento più frequenti.
Nessun refresh automatico del token. Il token LWA scade dopo 1 ora. Se la tua implementazione ottiene il token all’avvio e non lo rinfresca, funzionerà per un’ora e poi inizierà a ricevere 401 silenziosamente — specialmente in processi batch notturni dove nessuno sta guardando. Implementa sempre un refresh proattivo con buffer di 5 minuti.
Mancanza di polling sullo stato delle transazioni. Come descritto sopra: POST di riconoscimento → transactionId → polling su transactionStatus. Saltare il polling significa non sapere se i tuoi riconoscimenti sono stati accettati. Alcuni vendor hanno scoperto mesi dopo che i loro riconoscimenti fallissero sistematicamente per un errore nel payload.
Marketplace ID errato. Il marketplace ID per Amazon Italia è APJ6JRA9NG5V4, non lo stesso degli Stati Uniti (ATVPDKIKX0DER). Errore banale, conseguenze gravi: tutte le chiamate restituiscono risultati vuoti o PO di un altro marketplace.
Rate limit non gestiti. SP-API restituisce 429 Too Many Requests quando superi i rate limit. La risposta contiene un header x-amzn-RateLimit-Limit che indica il rate corrente. Implementa backoff esponenziale con jitter per i retry: wait = min(cap, base * 2^attempt) + random(0, 1). Senza gestione del rate limit, le tue integrazioni ad alto volume si bloccheranno periodicamente.
Permessi SP-API insufficienti. Non tutti i ruoli applicazione hanno accesso a tutti gli endpoint vendor. Se ricevi 403 su endpoint che dovrebbero funzionare, verifica che l’applicazione abbia il ruolo Vendor Orders o Inventory and Order Management nelle impostazioni dell’app in Seller Central.
Domande frequenti sulla SP-API di Amazon Vendor Central
Posso usare SP-API con un account Vendor Central esistente senza creare un account Seller Central?
No, non direttamente. La console sviluppatori e la registrazione delle applicazioni SP-API si trovano in Seller Central. I vendor puri (senza account seller) devono creare un account Seller Central separato per accedere alla console sviluppatori, ma l’account seller non deve essere attivo o avere listing. È un requisito burocratico, non tecnico — Amazon non ha ancora unificato i portali sviluppatori.
Qual è la differenza tra un’applicazione SP-API privata e pubblica?
Un’applicazione privata è sviluppata e usata solo dal proprietario dell’account — tipica per vendor che costruiscono integrazioni interne. Un’applicazione pubblica può essere autorizzata da qualsiasi seller o vendor terzo — usata da ISV e agenzie per costruire connettori multi-cliente. La maggior parte delle integrazioni vendor interne sono private. Le applicazioni pubbliche richiedono un processo di review più esteso da parte di Amazon e una politica di privacy pubblica.
Con quale frequenza devo fare polling per i nuovi PO?
Amazon raccomanda ogni 15-30 minuti per vendor ad alto volume. I rate limit di Vendor Orders consentono circa 10 richieste al secondo con burst rate più alto. Per vendor con pochi PO giornalieri, polling ogni ora è sufficiente. L’importante è rispettare la finestra di riconoscimento di 24-48 ore — pianifica il polling in modo da avere tempo sufficiente per processare e riconoscere prima della scadenza. Non aspettare mai l’ultimo momento.
SP-API supporta le notifiche push o devo sempre fare polling?
SP-API ha un sistema di notifiche basato su Amazon SNS (Simple Notification Service) e SQS. Puoi sottoscrivere notifiche per eventi specifici — inclusi ORDER_CHANGE per i vendor — tramite l’endpoint /notifications/v1/subscriptions. Questo elimina la necessità di polling. Tuttavia, le notifiche richiedono infrastruttura AWS (SNS + SQS) e la configurazione è più complessa rispetto al semplice polling. Per la maggior parte dei vendor con volumi medi, il polling schedulato è più semplice da implementare e mantenere.
Come gestisco gli errori di rate limit in produzione?
Implementa un retry handler con backoff esponenziale e jitter. La formula standard: attendi min(60, 2^tentativi) + random(0, 1) secondi tra i retry, con un massimo di 3-5 tentativi. Log sempre il header x-amzn-RateLimit-Limit per monitorare quando ti avvicini ai limiti. Per sistemi ad alto volume, considera di distribuire le chiamate nel tempo invece di fare batch burst. Amazon pubblica i rate limit per ogni endpoint nella documentazione ufficiale — usali per dimensionare la tua architettura preventivamente.
L’integrazione SP-API per Vendor Central non è particolarmente complessa, ma richiede attenzione ai dettagli: gestione del token refresh, polling del transactionStatus, marketplace ID corretti e rate limit handling. I vendor che costruiscono queste integrazioni internamente spesso scoprono i problemi solo in produzione, quando un PO rimane non riconosciuto o un batch di spedizioni non viene processato.
La tendenza che vediamo è verso integrazioni più intelligenti — non solo pipeline di sincronizzazione dati, ma sistemi che usano i dati SP-API per decision support: riconoscimento automatico dei PO con validazione delle disponibilità, alerting su anomalie nei dati di pricing competitivo, forecast basati su sell-through data. SP-API fornisce i dati grezzi; cosa ne fai determina il vantaggio competitivo.
TRANSFORM BY EPINIUM
Integrazioni SP-API vendor-grade, costruite per durare
Brand e distributori che lavorano con noi costruiscono pipeline SP-API che non si rompono a ogni aggiornamento Amazon. Inizia con una sessione gratuita di 30 minuti.
Gratuito · 30 min · Nessun impegno
