Automatizzare l’estrazione dei dati da Amazon Seller Central: un approccio basato sulla CLI
Amazon Seller Central rende disponibile una parte consistente dei suoi dati tramite la SP-API e una parte più piccola, ma rilevante sul piano operativo, soltanto tramite la propria interfaccia: report da richiedere nel browser, attendere che vengano generati e scaricare in un passaggio separato. Automatizzare questa procedura in modo affidabile è più complesso di quanto sembri, e molti approcci che funzionano nelle dimostrazioni falliscono in produzione nel giro di pochi giorni.
La difficoltà non è principalmente tecnica. L’automazione del browser è matura, gli endpoint dei report sono documentati e i formati dei dati sono ben conosciuti. La difficoltà è operativa: l’interfaccia di Amazon cambia senza preavviso, i limiti di frequenza delle richieste sono restrittivi, la disponibilità dei report varia in base al marketplace e al tipo di account, e lo stato della sessione su cui si basa l’automazione del browser si deteriora in modi difficili da rilevare finché una pipeline non smette silenziosamente di produrre dati.
API o browser: i compromessi reali
La SP-API copre la maggior parte dei report necessari per i dati operativi: ordini, inventario, liquidazioni, gestione degli ordini FBA e prestazioni del catalogo. Per questi report, un approccio basato esclusivamente sulle API è chiaramente preferibile: è più rapido, più affidabile e non risente delle modifiche all’interfaccia. L’investimento in una corretta autenticazione SP-API, con credenziali LWA, rinnovo dei token e limitazione della frequenza delle richieste, si ripaga rapidamente.
Tuttavia, alcune categorie di report non sono affatto disponibili tramite la SP-API. I report pubblicitari che vanno oltre quanto esposto dall’Advertising API, alcuni documenti di conformità e diversi formati di riepilogo finanziario richiedono l’interazione con il browser. L’automazione del browser va scelta solo per questi casi, con cautela e piena consapevolezza del costo operativo.
L’alternativa, esportare manualmente i dati quando servono, non è così irragionevole per i report poco frequenti. La domanda giusta è se l’onere dell’automazione, tra manutenzione delle sessioni, gestione degli accessi, CAPTCHA e MFA, sia davvero inferiore a quello del lavoro manuale nell’orizzonte temporale considerato. Per i dati operativi giornalieri, l’automazione conviene chiaramente. Per i report mensili di conformità, il calcolo è meno scontato.
Nomi di file deterministici come base
La decisione progettuale più importante in una pipeline di estrazione dei dati non riguarda il meccanismo di estrazione, ma il modo in cui i file estratti vengono denominati e archiviati. Le pipeline che usano nomi basati su timestamp o numerazioni progressive creano problemi operativi che si accumulano nel tempo: non è possibile capire a colpo d’occhio se un report copre l’intervallo di date previsto, la deduplicazione diventa inaffidabile e i processi a valle che dipendono da file specifici devono essere aggiornati a ogni modifica della convenzione di denominazione.
Una convenzione deterministica inserisce direttamente nel nome del file le proprietà rilevanti di ciascun report: tipo di report, identificativo del marketplace, intervallo di date e hash del contenuto per la deduplicazione. Un report delle liquidazioni per il marketplace UE relativo a un determinato periodo dovrebbe produrre lo stesso nome di file indipendentemente da quando è stato richiesto o scaricato. Questa proprietà, l’idempotenza nel file system, elimina un’intera categoria di errori nelle pipeline e rende la directory dei dati comprensibile senza documentazione aggiuntiva.
L’implementazione richiede una rappresentazione canonica delle proprietà principali di ciascun report prima della scrittura del file. Per la maggior parte dei report è semplice. La complicazione riguarda quelli in cui Amazon non include nel file tutti i metadati rilevanti: in questi casi, la convenzione di denominazione deve ricavarli dal contesto della richiesta, che va quindi mantenuto fino al download.
Tracciamento dello stato in YAML
Una CLI di estrazione dei dati che funziona senza supervisione diretta ha bisogno di uno stato persistente: quali report sono stati richiesti, quali sono in attesa, quali sono stati scaricati correttamente e quali sono falliti, con il relativo errore. Registrare lo stato in un database è la scelta più ovvia, ma introduce una dipendenza che complica la distribuzione e crea un onere operativo sproporzionato rispetto al problema.
File YAML per tipo di report, o per marketplace nelle configurazioni che ne gestiscono più di uno, offrono gran parte delle funzionalità necessarie con un’infrastruttura minima. Il file di stato registra ogni richiesta con i suoi parametri, il timestamp, l’orario previsto di disponibilità, lo stato del download e gli eventuali errori. Questo basta per riprendere una pipeline dall’ultimo stato riuscito, ricostruire quali dati sono stati raccolti e quando, e rilevare gli intervalli di date mancanti.
Il limite pratico dello stato in YAML è l’accesso concorrente: se la pipeline viene eseguita da più processi o macchine, lo stato basato su file crea condizioni di competizione (race condition). Per pipeline eseguite in sequenza su una sola macchina, il problema non si pone. Per configurazioni distribuite, un database leggero è la scelta corretta; quando la migrazione diventa necessaria, la struttura YAML si traduce facilmente in uno schema.
Il flusso in due passaggi per i report notturni
Diversi report Amazon vengono generati in modo asincrono: richiedi il report, Amazon lo mette in coda e il report diventa disponibile dopo un intervallo che va da pochi minuti a diverse ore. Il metodo più affidabile è un flusso di lavoro in due passaggi: uno invia tutte le richieste di report ancora da inoltrare, l’altro scarica i report diventati disponibili dall’ultimo controllo.
Il passaggio di richiesta viene eseguito a un orario definito, in genere in tarda serata, e invia le richieste per tutti i tipi di report relativi all’ultimo periodo completo. Il file di stato YAML registra l’ID di ogni richiesta e il timestamp di invio. Il passaggio di download viene eseguito la mattina successiva, controlla lo stato di tutte le richieste in attesa, scarica i report pronti e li contrassegna come completati. Quelli non ancora disponibili restano in attesa e vengono ricontrollati nel passaggio di download successivo.
Questa separazione ha una proprietà operativa importante: svincola la latenza di generazione dei report dalle obiettivi di disponibilità della pipeline. Invece di bloccare l’esecuzione in attesa dei report, introducendo ritardi variabili e complessità nella gestione dei timeout, la pipeline punta a una finestra definita il giorno successivo per i report richiesti prima di un orario limite; quelli che Amazon non ha ancora completato restano in attesa per il passaggio successivo. L’orario esatto all’interno di quella finestra dipende dalla coda di Amazon, non dal comportamento della pipeline.
Occorre prevedere due possibili problemi: la scadenza dei report, che l’API dei report conserva per un massimo di 90 giorni, rendendo necessario rilevare i download in ritardo; e la deduplicazione delle richieste, perché richieste duplicate per lo stesso periodo generano file ridondanti e consumano la quota API. Il file di stato YAML gestisce entrambi: registra i periodi con richieste attive e impedisce di inviarne altre finché la richiesta esistente non scade o fallisce definitivamente.
Cosa smette di funzionare in produzione
Il problema più comune in produzione non è l’estrazione dei report, ma la gestione delle credenziali. La SP-API usa token di accesso LWA (Login With Amazon) che scadono ogni ora e devono essere aggiornati tramite un refresh token, che a sua volta ha una durata più lunga ma finita. Le pipeline che gestiscono correttamente il rinnovo dei token in sviluppo spesso falliscono quando vengono eseguite senza supervisione per lunghi periodi in produzione e il refresh token scade senza essere rinnovato.
L’estrazione tramite browser presenta problemi diversi: i cookie di sessione scadono, Amazon introduce nuove verifiche e le modifiche all’interfaccia rendono inutilizzabili i selettori CSS o i percorsi di navigazione. Questi errori restano silenziosi se la pipeline non verifica esplicitamente che il file scaricato contenga la struttura dati prevista, anziché limitarsi a controllare che sia stato scaricato un file.
La disciplina operativa che previene gran parte degli errori in produzione consiste nel validare ogni passaggio. Verifica che le credenziali di autenticazione siano valide prima di avviare la pipeline. Verifica che ogni report richiesto restituisca lo schema previsto. Verifica che gli intervalli di date nei file scaricati corrispondano a quelli richiesti. Le pipeline che validano sistematicamente falliscono in modo evidente e immediato. Quelle che si fidano degli input falliscono silenziosamente e con costi elevati.
Approfondimenti correlati
- Pipeline di dati per più marketplace: gestire gli account venditore tra regioni — estendere l’estrazione da un singolo marketplace a US, JP e DE, con configurazione e stato YAML per ciascun marketplace.
- Costruire un’infrastruttura dati pronta per la produzione per i venditori Amazon — l’architettura di tva-fetch e i modelli di integrazione SP-API su cui si basa.
- Costruire un data warehouse Amazon con FastAPI e TimescaleDB — come utilizzare i dati estratti una volta salvati su disco.