Español
English
Català
Deutsch
Français
Português
Nederlands
Polski
SP-API sta per Selling Partner API: l'interfaccia con cui Amazon permette a un programma esterno di leggere e scrivere nel tuo account Seller Central. Ha sostituito MWS e ha cambiato molto più del nome. Dal lato di Odoo, l'API in sé è la parte facile: richieste HTTP con JSON. Ciò che decide se l'integrazione regge un novembre sono tre cose che non si vedono nella documentazione di un endpoint: come si autorizza, quante chiamate ti lasciano fare e quali dati arrivano in ritardo per progetto.
L'autorizzazione si firma in Seller Central, non in Odoo
Il flusso è sempre lo stesso: esiste un'applicazione registrata con un profilo sviluppatore e tu, come venditore, la autorizzi dal tuo account. Da questa autorizzazione nasce un refresh token di lunga durata che Odoo conserva; con quello chiede, ogni volta che serve, un token di accesso che dura un'ora. Se qualcuno ti chiede le credenziali di Seller Central per «configurarlo», qualcosa non va: per questo nessuno ha bisogno della tua password. E se revochi l'autorizzazione, l'integrazione si ferma di colpo, che è esattamente ciò che deve succedere.
I dati dell'acquirente passano da un'altra porta
Nome, indirizzo e telefono dell'acquirente sono dati personali e Amazon li tratta come tali: non arrivano nella risposta normale di un ordine. Per quella richiesta specifica serve un token ristretto, e il permesso per ottenerlo si concede per ruolo, non di default. Conseguenza pratica in Odoo: puoi avere ordini che si importano perfettamente e consegne che non si possono spedire perché manca l'indirizzo. Non è un difetto del connettore; è il permesso che non è stato approvato.
I limiti di chiamate sono un budget, non una velocità
Ogni operazione della SP-API ha un proprio limite e funziona come un serbatoio che si riempie a un ritmo fisso e ammette una breve raffica oltre quel ritmo. Finché c'è saldo vai veloce; quando si esaurisce, Amazon risponde 429 e bisogna aspettare. Per Odoo questo ha una lettura diretta: non puoi scorrere 4.000 referenze chiamando una per una «perché è più semplice». Bisogna raggruppare, rispettare l'header del limite che restituisce la stessa API e riprovare con attesa crescente. E la sincronizzazione manuale e il cron devono condividere lo stesso freno, perché il budget è dell'intero account, non di ogni processo.
Report e chiamate in tempo reale: perché la tua giacenza è sempre in ritardo
La SP-API ha due modi per darti i dati. Uno è la chiamata diretta: chiedi gli ordini da una certa data e ti risponde subito. L'altro è il sistema di report, che è asincrono: richiedi il report, Amazon lo prepara quando può, tu controlli se è pronto e poi scarichi un file compresso. L'inventario FBA e i pagamenti (settlement) passano da lì. Questo significa che la giacenza che vedi in Odoo è quella dell'ultimo download, non quella di questo secondo, e nessuna frequenza di cron risolve il problema. La risposta giusta non è chiamare di più: è pubblicare con un margine di sicurezza e accettare lo sfasamento.
Il sandbox della SP-API restituisce risposte fisse preparate da Amazon. Serve a verificare che firmi bene le richieste e poco altro: tutte le sue operazioni condividono un unico limite, quindi non riproduce quello di ogni operazione in produzione, non ti restituisce un ordine in sospeso senza indirizzo e non ti obbliga a rinnovare un token nel mezzo di una sincronizzazione lunga. Un connettore verde in sandbox non è testato. Ne parliamo in test verdi e guasto in produzione.
Gli errori che emergono solo in produzione
Sono sempre gli stessi e nessuno compare il primo giorno. Ordini in stato pending che arrivano senza importi e senza indirizzo e vanno riletti più tardi. Paginazione: la prima pagina entra e il resto si perde se nessuno segue il token di continuazione. Finestre di date calcolate male per via del fuso orario, che lasciano un buco di ordini proprio al cambio di giorno. Token che scadono durante una sincronizzazione lunga e vanno rinnovati a metà. E la regione sbagliata: l'applicazione è globale, ma l'account venditore no, e chiedere gli ordini della Germania all'endpoint del Nord America non risponde «regione errata», risponde «Access to requested resource is denied». Sembra un problema di permessi, così si rigenerano credenziali che andavano bene mentre il guasto resta nell'URL.
Dove deve vivere tutto questo dentro Odoo
Una chiamata ad Amazon non può dipendere dalla convalida di una consegna. Se l'API è lenta, l'utente resta a fissare una rotellina e, se fallisce, perde il lavoro fatto. Il posto di queste chiamate è un'azione pianificata o una coda di lavori, con il suo tentativo di ripetizione, il suo registro di cosa è stato chiesto e cosa ha risposto Amazon, e con operazioni idempotenti: ripetere una sincronizzazione non può creare l'ordine due volte. Quel registro è ciò che poi ti permette di discutere con il supporto di Amazon con i dati, invece che con le impressioni. Il resto del modello, applicato agli ordini che non compaiono, è in perché gli ordini Amazon non entrano in Odoo.
Quando non serve costruire nulla
Se vendi su un solo marketplace, con poche referenze e ti basta che gli ordini entrino, il connettore Amazon incluso di serie in Odoo Enterprise può bastarti. Vale la pena provarlo prima di pagare qualsiasi cosa. La conversazione cambia quando ci sono più paesi con le loro imposte, giacenza condivisa con altri canali, settlement da quadrare o conferme di spedizione con scadenza. È lì che il nostro connettore Amazon per Odoo fa il lavoro: SP-API con controllo dei limiti, report, FBA e FBM, su Odoo 17, 18, 19 e 20.
Domande frequenti
Serve un account sviluppatore Amazon per usare la SP-API?
L'applicazione deve essere registrata con un profilo sviluppatore, ma chi autorizza sei tu dal tuo Seller Central. L'autorizzazione è tua e puoi revocarla quando vuoi.
Si può consultare la giacenza di Amazon in tempo reale?
Non come si immagina. L'inventario arriva soprattutto tramite report, che è asincrono, quindi c'è sempre uno sfasamento di minuti. Per questo il margine di sicurezza conta più della frequenza di sincronizzazione.
Cosa succede se Amazon mi restituisce 429 in piena campagna?
Nulla di grave se l'integrazione riprova con attesa crescente e mette in coda ciò che è in sospeso. È grave se il processo muore e nessuno se ne accorge finché non mancano ordini: per questo il registro e l'avviso contano quanto la chiamata.
Link utili dentro FlexigoTech
Cosa facciamo su questo
La tua integrazione con la SP-API fallisce e non sai da dove partire?
Dicci su quali marketplace vendi, se usi FBA, FBM o entrambi e quale errore preciso vedi nel registro. Controlliamo se è autorizzazione, limiti di chiamate o una finestra di date calcolata male. Scrivi a comercial@flexigobe.com o fissa una chiamata.