Connettore Amazon per Odoo: quali credenziali richiede SP-API, quali limiti di frequenza ha e cosa deve coprire

Se cerchi connettore Amazon Odoo o Amazon SP-API Odoo, la risposta breve è questa: servono tre credenziali che non arrivano dallo stesso posto (un'applicazione SP-API registrata da un profilo sviluppatore con i ruoli approvati, le chiavi LWA di quell'applicazione e un refresh token per ogni venditore che la autorizza), più il marketplace id e l'endpoint regionale. E una decisione di progetto: i limiti sono secchielli di token per operazione, quindi il connettore usa coda e backoff, non cicli.

Tutto quello che segue è stato verificato il 13 settembre 2026 nella documentazione di SP-API e nel codice del nostro Connettore Amazon Seller per Odoo, pubblicato nei rami 19.0, 18.0 e 17.0, con 786 test propri in quello di Odoo 19 e 685 in ciascuno degli altri due.

Cosa deve risolvere un connettore Amazon Odoo

• Importazione affidabile degli ordini e riserve di giacenza.
• Mappatura di SKU, varianti e listing senza duplicati.
• Sincronizzazione di stati, tracking e conferme.
• Gestione di prezzi, incidenze e casi di errore.
• Gestione di FBA quando fa parte dell'operatività.
• Log e nuovi tentativi quando Amazon o la coda interna falliscono.

Ogni riga entra da una porta diversa (/orders/v0, /listings/2021-08-01, /feeds/2021-06-30, /reports/2021-06-30) e ogni porta ha il suo limite.

Quali credenziali richiede SP-API e chi le rilascia

1. L'applicazione. SP-API non si apre con l'utente di Seller Central, ma con un'applicazione registrata nel Solution Provider Portal da un profilo sviluppatore approvato. Nella registrazione si scelgono i ruoli (Amazon ne documenta diciotto) e puoi scegliere solo quelli già approvati. Quattro sono ristretti perché toccano dati personali, tra cui Direct-to-Consumer Shipping. E avere il ruolo non basta: l'indirizzo di consegna si richiede con un restricted data token (POST /tokens/2021-03-01/restrictedDataToken).

2. Le chiavi LWA. Dall'applicazione si ottengono un client_id e un client_secret di Login with Amazon. Il secret scade dopo 180 giorni: Amazon avvisa 90 giorni prima e il vecchio resiste sette giorni in più. Scaduto il termine le chiamate falliscono senza che nessuno abbia toccato nulla, e il sintomo (invalid_client di notte) non somiglia alla sua causa; per questo il connettore salva quella data e avvisa con un cron giornaliero.

3. Il refresh token del venditore. È l'unica cosa che non compili tu: lo genera il venditore autorizzando l'app su sellercentral…/apps/authorize/consent, con il application_id e un state proprio; se l'app è ancora in bozza si aggiunge &version=beta, e quando la pubblichi va tolto. Amazon lo restituisce al tuo redirect URI con un spapi_oauth_code da scambiare entro cinque minuti su https://api.amazon.com/auth/o2/token: ne escono un access_token, che scade dopo un'ora, e il refresh_token.

4. Marketplace e regione. Un account non è un paese: è un marketplace id (Spagna A1RKKUPIHCS9HS, Francia A13V1IB3VIYZZH) che punta a un endpoint regionale, https://sellingpartnerapi-eu.amazon.com in Europa. Il nostro connettore include i 23 marketplace come dati e ogni account punta a uno solo, in modo che giacenza, imposte e canale vengano dal posto giusto.

Limiti di frequenza: perché il connettore ha bisogno di una coda

Amazon distribuisce il traffico con un secchiello di token: ogni operazione ha una frequenza (token al secondo) e un burst (capacità), e ogni richiesta consuma un token. Quando il secchiello si svuota arriva un 429, che la documentazione definisce ritentabile, e (quando è disponibile, cosa che non succede sempre) torna l'intestazione x-amzn-RateLimit-Limit con il limite della tua coppia venditore-applicazione. I limiti sono per operazione, e quelli della tabella sono i valori predefiniti, che Amazon può alzare a chi muove più volume.

Quella tabella spiega il progetto. Poiché getOrders va a uno al minuto, gli ordini si leggono con una filigrana (LastUpdatedAfter) e paginazione tramite NextToken da un cron ogni quindici minuti, non con un pulsante. Poiché i report vanno attesi, il ciclo è creare, interrogare e scaricare: interroghiamo fino a dodici volte ogni dieci secondi. E poiché le chiamate dei report condividono il secchiello, davanti a un 429 il connettore scrive un raffreddamento condiviso di 90 secondi e l'inventario FBA ripiega sull'API in tempo reale.

Il nuovo tentativo vive in una sola funzione: 429 e 500, 502, 503 e 504 vengono ritentati, si rispetta Retry-After e, se non arriva, si attende un backoff esponenziale a partire da 1,5 secondi con rumore casuale perché due cron non tornino insieme. Se anche l'ultimo tentativo fallisce, l'errore porta con sé Retry-After, l'intestazione della quota e il percorso: il log dice quale quota si è esaurita, non «errore di sincronizzazione».

Da qui la regola: ciò che scrive va in coda con chiave di idempotenza; ciò che legge va con una filigrana. Confermare la spedizione può restare in coda come «in sospeso» e allora l'unico che invia è un cron ogni cinque minuti che prende al massimo 200 prelievi degli ultimi tre giorni, con un blocco per prelievo che impedisce di inviare due volte lo stesso tracking. Prezzi e giacenza hanno una coda propria ogni minuto; se una scrittura fallisce, un'altra coda la ritenta ogni 180 secondi, al massimo venti volte per SKU.

Perché Amazon rompe le operazioni quando Odoo non comanda

Se la giacenza arriva da più posti o il tracking si gestisce fuori dall'ERP, arrivano le incidenze: ordini non mappati, inventario incoerente e assistenza post-vendita più cara. Con i limiti davanti si capisce perché il canale che pubblica la giacenza deve essere uno solo: pubblicarla due volte costa il doppio di quota. Lo sviluppiamo in giacenza in tempo reale sui marketplace e in vendere su più marketplace da un solo Odoo.

Errori frequenti di Amazon SP-API in Odoo

Quasi tutti i guasti che vediamo vengono da quelle tre credenziali, non dal codice: un redirect URI che punta a un altro Odoo, e il ritorno del venditore finisce in una schermata che dice che nessuno lo aspettava; un'autorizzazione con version=beta quando l'app è già pubblicata; il secret LWA scaduto; il ruolo ristretto non approvato, che non dà un errore chiaro ma indirizzi vuoti; e il ciclo di 429 quando qualcuno ritenta a mano mentre ritenta anche il cron.

Ognuno ha un sintomo che non somiglia alla sua causa, quindi li abbiamo raccolti con la loro diagnosi in Amazon SP-API e Odoo: errori frequenti e come evitarli. Se il tuo tema è l'avvio, il percorso è in come integrare Amazon con Odoo 19.

Parti da ciò che fa più male

Con i limiti davanti c'è un ordine sensato: prima ordini, giacenza e tracking, le tre chiamate che reggono il magazzino; poi listing, prezzi, FBA o resi se l'attività lo richiede. I report vanno per ultimi: non sono difficili, consumano la quota lenta.

Cosa dovresti chiedere prima di acquistare

• Quali flussi sono supportati oggi e da quale API passa ciascuno.
• Se la connessione usa la tua applicazione o quella del fornitore, e chi ruota il secret LWA.
• Cosa succede davanti a un 429: ritenta, mette in coda, rispetta Retry-After, lascia traccia?
• Come si trattano FBA, resi e indirizzi con dati personali.
• Se confermando due volte la stessa spedizione il tracking viene inviato due volte.
• Se il fornitore implementa o vende solo la licenza, e su quali versioni mantiene il modulo.

Se l'integrazione non è con Amazon ma con il tuo gestionale, l'impostazione è la stessa e la raccontiamo in connettore Odoo per il tuo software; il catalogo è in moduli e la mappa per problema, in soluzioni.

Domande frequenti

Link utili all'interno di FlexigoTech

Cosa facciamo su questo