Introduzione
Come illustrato nelle mie puntate precedenti (vedi qui e qui), hai imparato come autenticarti alle nuovissime SP-API di Amazon, il nuovo gateway offerto da Amazon per consentire ai partner di vendita (ovvero ai venditori) di connettersi alla loro attività su Amazon in modo programmatico.
In questo articolo voglio analizzare in dettaglio ciò che abbiamo imparato in MarketRock, durante la migrazione del complesso flusso per pubblicare i prodotti su Amazon da MWS a SP-API.
Se ti accosti ora alle API di Amazon, sappi che una volta (abbiamo realizzato la nostra prima integrazione con Amazon MWS e il catalogo nel 2010) c'era solo MWS (Marketplace Web Services), un sistema complesso, basato principalmente sul concetto di scambio di file, chiamati feed (quando il flusso era dal venditore ad Amazon) o Report (quando il flusso era nella direzione opposta). Considerati molto fortunato che Amazon abbia rilasciato queste nuove SP-API poiché vendere su Amazon utilizzando MWS è stato un incubo totale :)
Immagina di scambiare tonnellate di messaggi basati su XML, con schemi XSD completamente inutili e difficili da trovare (qualcuno ha creato un repository su GitHub per condividerli, perché erano completamente nascosti agli sviluppatori) per validarli. E dopo che sei riuscito a costruire il tuo brillante messaggio XML, ricco di dettagli di prodotto, totalmente valido e testato, immagina di ricevere un messaggio vago, magari dopo 5 o 10 minuti, in cui si afferma che per tutti i tuoi prodotti “manca un attributo”. Quale attributo? Dove? Perché? Argh!
Gli schemi XML erano inutili, probabilmente per il fatto che i requisiti nel catalogo di Amazon cambiano molto velocemente, ed è quindi davvero difficile per la loro organizzazione mantenere aggiornati questi schemi. Quindi gli schemi erano enormi e convalidavano positivamente qualsiasi documento XML :(
È stato un incubo per noi e, sicuramente, lo è stato anche per i nostri clienti, poiché la percezione che avevano del nostro software è che non funzionasse. E puoi immaginare cosa può fare un cliente, quando pensa di sperperare denaro.
Devo ammettere che Amazon probabilmente ha ascoltato molti di noi - partner sviluppatori - e ha deciso di investire in un nuovissimo set di API, che ti consentirà di pubblicare i prodotti su Amazon in un modo più efficiente e soddisfacente, sia per te che per i tuoi clienti.
Catalogo Amazon "for dummies"
Quando vuoi pubblicare un prodotto su Amazon devi sapere che in realtà lavorerai su un catalogo di prodotti enorme, distribuito e complesso. Non so esattamente quanti prodotti siano contenuti, ma devono essere miliardi.
Quindi non sei obbligato a creare la pagina di un nuovo prodotto, a meno che non esista ancora nel catalogo Amazon. Se un prodotto esiste nel loro catalogo, sicuramente ha un ASIN (Amazon Standard Identification Number), un codice alfanumerico di 10 caratteri, che identifica in modo univoco quel prodotto sul catalogo.
Indipendentemente dal fatto che il prodotto esista già o meno, dovrai inserire un'inserzione per quel prodotto, per semplicità ciò significa il tuo prezzo, le quantità di cui disponi e lo SKU per quel particolare prodotto (in altre parole le tue condizioni di vendita).
Quindi, come fai a sapere se un prodotto esiste già in questo enorme catalogo? La risposta è: grazie agli "Identificatori". Ogni prodotto normalmente ha un codice univoco chiamato GTIN (Global Trade Identification Number) ed è normalmente rappresentato con il codice a barre (quello scansionato alla cassa del supermercato). In Europa i codici EAN sono uno standard, mentre negli Stati Uniti gli standard sono UPC ed in Giappone sono JAN.
Difficoltà iniziali: benvenuto all'inferno!
In questo momento potresti pensare: “Non credevo fosse così semplice! Cercherò il mio EAN/UPC/JAN su Amazon. Se il prodotto è lì, inserirò semplicemente un'offerta. Altrimenti creerò il prodotto e poi invierò l'offerta". Ma andiamo per gradi prima di giungere alle conclusioni. Lasciami approfondire questo aspetto.
Innanzitutto non tutti i prodotti hanno un identificatore. Averli è un costo che si deve sobbarcare l’azienda produttrice e soprattutto le realtà più piccole rischiano di non valorizzare davvero il fatto di possederli. Ricorda che ogni prodotto deve avere il proprio identificatore ed il costo da sostenere è per l'appunto per ogni identificatore.
In secondo luogo, potrebbero esserci differenze simili, ma sottili, per lo stesso prodotto (ad esempio un iPhone sbloccato o lo stesso iPhone legato a un particolare operatore telefonico). In questo caso è del tutto normale avere diversi ASIN collegati allo stesso identificatore. Idealmente si tratta sempre di una relazione uno a uno, ma nel mondo reale è una relazione molti a molti.
Infine, il catalogo Amazon è costruito da input umani. Ciò significa che i venditori “furbetti”, potrebbero provare a creare prodotti utilizzando identificatori errati, magari presi da prodotti già esistenti, per essere più veloci, o magari per pigrizia, o per evitare il problema di non avere un'identificatore. Da qualche tempo a questa parte, in forza di un accordo tra Amazon e GS1 (il consorzio che eroga e detiene i codici EAN), è difficile usare un EAN in questo modo perché Amazon effettua una ricerca incrociata. Ma questa prassi è stata adottata in passato e ci sono ancora molti codici ASIN che sono correlati ad un EAN "sbagliato".
Sporchiamoci le mani
Quindi quello che dovresti chiederti è: voglio creare nuovi prodotti su Amazon (ovvero prodotti che non sono ancora nel loro catalogo) o mi basta solo collegarmi a quelli già esistenti? Le differenze tra le due implementazioni sono enormi, poiché, come vedremo, creare un prodotto completamente nuovo sul catalogo è un'attività molto complessa.
Per utilizzare queste API, la tua APP su Seller Central deve disporre dell'autorizzazione "Product Listing". Se al momento non la possiedi, dovrai richiederla e superare i controlli di sicurezza che Amazon eseguirà.
Capire se un prodotto è nel catalogo Amazon
Per cercare un particolare prodotto è possibile utilizzare la chiamata searchCatalogItems, eseguendo questa chiamata:
GET catalog/2022-04-01/items?marketplaceIds={MarketplaceId}&identifiers={Identifiers}&identifiersType=EAN&includedData=identifiers
Ovviamente {MarketplaceId} è il codice del marketplace in cui si vuole effettuare la ricerca, mentre {Identifiers} è una lista di massimo 20 identificatori. Nell'esempio ho specificato “EAN” e identifierType, ma puoi usare “UPC” o “JAN” e pochi altri. Il parametro "includedData" ti consente di chiedere ad Amazon aspetti particolari del prodotto, come immagini, attributi, classifiche di vendita e così via. In questo caso vogliamo solo capire se un determinato GTIN è conosciuto oppure no, quindi basteranno gli “identificatori”.
La risposta che otterrai sarà qualcosa del genere, se nessuno degli identificatori passati è noto:
{
"numberOfResults": 0,
"items": []
}
Altrimenti potresti ottenere qualcosa del genere che vedi qui sotto, se c'è una corrispondenza. Nota che “numberOfResults” è uguale a 1, significa che c'è un solo ASIN (B0CCS9BP25) collegato a quel particolare EAN.
{
"numberOfResults": 1,
"items": [
{
"asin": "B0CCS9BP25",
"identifiers": [
{
"marketplaceId": "APJ6JRA9NG5V4",
"identifiers": [
{
"identifierType": "EAN",
"identifier": "8054147069422"
}
]
}
]
}
]
}
Ma se sei sfortunato, potresti ricevere qualcosa del genere. Da notare che “numberOfResults” è uguale a 2 e, infatti, esistono due ASIN diversi (B01555CJ6C e B08FRPSYYN) per lo stesso codice EAN.
{
"numeroRisultati": 2,
"elementi": [
{
"asin": "B01555CJ6C",
"identificatori": [
{
"marketplaceId": "APJ6JRA9NG5V4",
"identificatori": [
{
"identifierType": "EAN",
"identificatore": "8002131034130"
}
]
}
]
},
{
"asin": "B08FRPSYYN",
"identificatori": [
{
"marketplaceId": "APJ6JRA9NG5V4",
"identificatori": [
{
"identifierType": "EAN",
"identificatore": "8002131034130"
}
]
}
]
}
]
}
Se vuoi distinguere tra i due (o più) ASIN, puoi richiedere maggiori dettagli con il parametro “includedData”.
Verifica se il tuo Account venditore è idoneo a vendere quell'articolo
Un venditore potrebbe non essere idoneo a vendere un particolare prodotto (ASIN) in uno specifico marketplace Amazon. Questo perché potrebbero esserci restrizioni imposte dal proprietario del marchio. In questo caso, anche se il prodotto è già sul catalogo Amazon, non sarai in grado di pubblicare un’offerta e l’acquirente semplicemente non potrà acquistarlo.
Pertanto, prima di inviare un'offerta, è altamente consigliabile verificare se si è idonei effettuando una chiamata getListingsRestrictions.
GET listings/2021-08-01/restrictions?marketplaceIds={MarketplaceId}&sellerId={SellerId}&asin={Asin}&conditionType={Condition}
Dove {MarketplaceId} è il valore precedente di Amazon, {SellerId} è il token del venditore, {Asin} è l'ASIN che desideri controllare e {Condition} è la condizione facoltativa dell'articolo. Per gli articoli nuovi di zecca, conditionType è "new_new", ma Amazon offre diversi tipi di condizioni.
Una risposta come la seguente significa che non puoi pubblicare questo articolo. Posso dirlo perché l'array "reasons" non è vuoto.
{
"restrictions": [
{
"marketplaceId": "APJ6JRA9NG5V4",
"conditionType": "new_new",
"reasons": [
{
"reasonCode": "APPROVAL_REQUIRED",
"message": "Per inserire i tuoi prodotti nella categoria \"Vino\" devi ottenere un'autorizzazione.",
"links": [
{
"resource": "https://sellercentral.amazon.it/hz/approvalrequest/restrictions/approve?asin=B0046EP7NQ",
"verb": "GET",
"title": "Request Approval via Seller Central.",
"type": "text/html"
}
]
}
]
}
]
}
Un bell'array "reasons" vuoto, significa che hai il via libera e puoi passare al passaggio successivo nella pubblicazione.
{
"restrictions": []
}
È ora di pubblicare l'offerta su Amazon: let's dance!
Se il prodotto è già nel catalogo di Amazon e non ci sono restrizioni sul tuo account per iniziare a vendere, è il momento di pubblicare l'offerta (ovvero il prezzo e la quantità).
Questa parte può essere semplice ma implica la conoscenza degli di schemi JSON. Dato che questo è molto importante, in particolare per la creazione di nuovi prodotti che ancora non esistono a catalogo, lo terrò per la parte 2.
Arrivederci!
