176 lines
9.1 KiB
Markdown
176 lines
9.1 KiB
Markdown
# Amazon Creators API e canale offerte
|
|
|
|
## Stato attuale nel codice
|
|
|
|
NetGescon aveva gia una base catalogo con prodotti, identificativi, media, seriali e offerte.
|
|
Questa slice aggiunge:
|
|
|
|
- configurazione ambiente per Amazon Creators API in `config/services.php`;
|
|
- servizio `AmazonCreatorsApiService` per token OAuth e chiamate configurabili;
|
|
- servizio `AmazonCreatorsCatalogSyncService` per mappare item Amazon su `ProductOffer`, `ProductIdentifier`, `ProductMedia` e snapshot strutturato del prodotto;
|
|
- comando artisan `catalog:sync-amazon-creators` per sincronizzare un prodotto singolo.
|
|
|
|
In piu la pagina fornitore/prodotti puo ora:
|
|
|
|
- cercare Amazon dalla UI;
|
|
- salvare un singolo candidato Amazon nel catalogo interno;
|
|
- salvare in massa tutti i risultati della query corrente nel catalogo del fornitore.
|
|
|
|
## Variabili ambiente da valorizzare
|
|
|
|
Queste chiavi vanno messe solo in `.env` locale o staging, mai nel repository:
|
|
|
|
```env
|
|
AMAZON_REFERRAL_TAG=netgescon-21
|
|
AMAZON_MARKETPLACE=www.amazon.it
|
|
|
|
AMAZON_CREATORS_ENABLED=true
|
|
AMAZON_CREATORS_CREDENTIAL_ID=
|
|
AMAZON_CREATORS_CREDENTIAL_SECRET=
|
|
AMAZON_CREATORS_CREDENTIAL_VERSION=v3.2
|
|
|
|
AMAZON_CREATORS_TOKEN_URL=
|
|
AMAZON_CREATORS_API_BASE_URL=
|
|
AMAZON_CREATORS_SEARCH_PATH=
|
|
AMAZON_CREATORS_GET_ITEMS_PATH=
|
|
AMAZON_CREATORS_TIMEOUT=20
|
|
|
|
TELEGRAM_OFFERS_BOT_TOKEN=
|
|
TELEGRAM_OFFERS_CHAT_ID=
|
|
TELEGRAM_OFFERS_CHANNEL_NAME=
|
|
TELEGRAM_OFFERS_WEBHOOK_SECRET=
|
|
```
|
|
|
|
## Cosa manca per il collegamento live
|
|
|
|
Le credenziali ci sono gia, ma per la chiamata HTTP reale servono ancora dal materiale Amazon ufficiale:
|
|
|
|
- endpoint OAuth preciso per il token;
|
|
- base URL API Creators per il marketplace Italia;
|
|
- path esatti delle operazioni `SearchItems` e `GetItems`;
|
|
- un esempio reale di request e response, oppure direttamente lo zip dello SDK PHP Creators API.
|
|
|
|
Appena ci sono questi quattro dati, il client puo essere puntato ai path reali senza inventare nulla.
|
|
|
|
## Uso del comando
|
|
|
|
Sincronizzazione da API, quando gli endpoint sono configurati:
|
|
|
|
```bash
|
|
php artisan catalog:sync-amazon-creators ART-000123
|
|
php artisan catalog:sync-amazon-creators 123 --asin=B0ABCDEF12
|
|
php artisan catalog:sync-amazon-creators ART-000123 --query="detergente caldaia"
|
|
```
|
|
|
|
Sincronizzazione da JSON esportato dallo SDK Amazon, utile anche prima del collegamento live completo:
|
|
|
|
```bash
|
|
php artisan catalog:sync-amazon-creators ART-000123 --json=/tmp/amazon-item.json
|
|
php artisan catalog:sync-amazon-creators ART-000123 --json=/tmp/amazon-response.json --dry-run
|
|
```
|
|
|
|
## Dati che il sync salva
|
|
|
|
- offerta `product_offers.source_type = amazon_creators_api`;
|
|
- ASIN come `ProductIdentifier` primario, se presente;
|
|
- EAN come `ProductIdentifier`, se presente;
|
|
- immagine Amazon come `ProductMedia` remoto;
|
|
- referral URL con `tag=netgescon-21` se il tag e configurato;
|
|
- snapshot in `products.meta.amazon` con almeno ASIN, EAN, titolo, marca, modello se presente, detail URL, referral URL, prezzo, listino, valuta, disponibilita, immagini, feature points e timestamp sync;
|
|
- snapshot offerta in `product_offers.meta.payload` con i dati prezzo e contesto di sync, inclusa la query di ricerca quando l'import nasce dalla UI;
|
|
- `products.description` popolata con i feature points Amazon quando il prodotto interno e ancora vuoto;
|
|
- `products.model` valorizzato quando Amazon espone un modello o gruppo prodotto utile.
|
|
|
|
## Workflow operativo consigliato
|
|
|
|
1. Apri la pagina catalogo fornitore.
|
|
2. Cerca il prodotto su Amazon con una query libera o con ASIN/EAN.
|
|
3. Se il risultato e corretto puoi scegliere:
|
|
- `Salva candidato` per importare solo quella scheda;
|
|
- `Salva tutti i risultati nel catalogo` per costruire rapidamente un mini catalogo interno da una query.
|
|
4. I prezzi Amazon salvati restano disponibili nelle offerte prodotto e possono essere riaggiornati con una nuova sync quando serve.
|
|
5. Le procedure interne devono leggere prima il catalogo interno NetGescon e le relative `product_offers`, senza interrogare Amazon ogni volta.
|
|
|
|
Questo consente di usare il catalogo Amazon come sorgente di acquisizione e aggiornamento, ma di lavorare poi sempre su dati interni gia normalizzati e riusabili.
|
|
|
|
## Pagina pubblica di abilitazione e demo
|
|
|
|
La pagina pubblica `public/amazon` non e piu solo un apri-link con tag affiliato.
|
|
Ora serve anche come vetrina condivisibile per mostrare:
|
|
|
|
- offerte Amazon gia importate nel catalogo interno;
|
|
- stato delle integrazioni in corso;
|
|
- prerequisiti per collegare il canale Telegram offerte;
|
|
- limiti attuali su messaggi privati Telegram, carrello Amazon, fattura e provenienza venditore.
|
|
|
|
Questo aiuta a rendere visibile il lavoro a chi ha contribuito all abilitazione API e a tenere allineati partner e operatori senza entrare subito nel pannello interno.
|
|
|
|
La pagina ora puo essere usata anche come mini sito vetrina per brand selezionati:
|
|
|
|
- filtro brand via query string, per esempio `public/amazon?brand=EPSON`;
|
|
- cards prodotto piu compatte, pensate per stare bene affiancate in griglia;
|
|
- cards prodotto con gallery immagini quando Amazon o `product_media` le rendono disponibili;
|
|
- esposizione pubblica del codice produttore, EAN o UPC al posto dell ASIN quando disponibili;
|
|
- import del codice produttore da `itemInfo.manufactureInfo.itemPartNumber` quando Amazon lo restituisce;
|
|
- pubblicazione governata dal flag interno `meta.catalog.public_showcase`, cosi il sito espone solo i prodotti scelti esplicitamente;
|
|
- esposizione del solo prezzo Amazon pubblico nella pagina pubblica, senza mostrare il prezzo interno del gestionale;
|
|
- casi guida gia riallineati con payload ricco Amazon per EPSON `B0CPPKNRLJ`, Samsung `B0B9C3ZVHR` e Samsung `B087DFLF9S`, con immagini, brand, codice produttore ed EAN quando disponibili.
|
|
|
|
Se il payload Creators non espone ancora immagini o prezzo, la pagina continua a funzionare ma mostra il dato come da completare. Questo evita di bloccare il mini sito mentre continuiamo le prove API.
|
|
|
|
La pagina include anche un carrello interno lato browser: raccoglie i prodotti selezionati nel mini sito e apre le relative schede referral Amazon. Non corrisponde ancora a un carrello Amazon ufficiale condiviso, ma prepara il passaggio dal sito NetGescon all acquisto finale su Amazon.
|
|
|
|
## Telegram canale offerte
|
|
|
|
Per pubblicare le offerte Amazon sul canale Telegram servono:
|
|
|
|
- un bot Telegram creato con BotFather;
|
|
- il bot aggiunto come admin del canale target;
|
|
- `TELEGRAM_OFFERS_BOT_TOKEN` valorizzato;
|
|
- `TELEGRAM_OFFERS_CHAT_ID` valorizzato con id o riferimento compatibile del canale;
|
|
- `TELEGRAM_OFFERS_CHANNEL_NAME` valorizzato per mostrare il canale in UI e documentazione;
|
|
- opzionalmente `TELEGRAM_OFFERS_WEBHOOK_SECRET` se si usa anche la ricezione webhook.
|
|
|
|
Nota importante: un bot non puo inviare messaggi privati a un semplice iscritto del canale se quell utente non ha prima aperto una chat diretta col bot o inviato almeno un comando come `/start`.
|
|
|
|
Per il primo invio operativo c e ora anche un comando Artisan dedicato:
|
|
|
|
```bash
|
|
php artisan offers:publish-telegram 2917 --dry-run
|
|
php artisan offers:publish-telegram B0B9C3ZVHR
|
|
php artisan offers:publish-telegram ART-003315 --chat=@nethomestorelettronica
|
|
```
|
|
|
|
Il comando cerca una offerta `amazon_creators_api` per ID offerta, ASIN o `internal_code` prodotto e pubblica titolo, prezzo, disponibilita e referral URL sul canale configurato.
|
|
|
|
## Carrello Amazon, fattura e priorita venditori
|
|
|
|
- Carrello interno NetGescon: fattibile, possiamo costruirlo noi con selezione multipla e riepilogo.
|
|
- Passaggio diretto di piu prodotti al carrello Amazon: da trattare come non garantito finche non troviamo un endpoint o un meccanismo ufficiale stabile; i link referral di prodotto restano la via affidabile.
|
|
- Fattura: va verificato se il segnale e davvero presente e affidabile nei dati Amazon disponibili.
|
|
- Priorita venditori italiani, europei, cinesi: possibile solo se otteniamo e persistiamo un dato attendibile su merchant o paese venditore.
|
|
|
|
## KB operativo per la macchina vetrina prodotti
|
|
|
|
Per preparare una macchina dedicata al sito vetrina prodotti Amazon servono almeno questi passaggi:
|
|
|
|
1. configurare le variabili `AMAZON_CREATORS_*`, `AMAZON_REFERRAL_TAG` e, se serve, `TELEGRAM_OFFERS_*`;
|
|
2. importare i prodotti candidati dal catalogo fornitore interno;
|
|
3. usare `public/amazon?brand=EPSON` o altri brand come vetrina iniziale del sito;
|
|
4. marcare come pubblici solo i prodotti scelti impostando `meta.catalog.public_showcase = true`;
|
|
5. pubblicare solo prodotti e brand selezionati, lasciando l acquisto finale su Amazon tramite referral URL o carrello interno di handoff;
|
|
6. tenere l eventuale confronto economico col fornitore come informazione interna di NetGescon, senza esporlo nella pagina pubblica.
|
|
|
|
## Cosa serve per il canale Telegram offerte
|
|
|
|
Per pubblicare offerte in automatico dal catalogo NetGescon servono:
|
|
|
|
- un bot Telegram creato con BotFather;
|
|
- il bot aggiunto come admin del canale offerte;
|
|
- `chat_id` o username del canale;
|
|
- una regola chiara di pubblicazione, per esempio solo offerte Amazon con prezzo valido e prodotto attivo;
|
|
- una frequenza di invio, per esempio push immediato o digest orario;
|
|
- un criterio anti-spam, per esempio non ripubblicare lo stesso ASIN nelle ultime 24 ore.
|
|
|
|
La prossima slice naturale e un publisher che prende le offerte attive dal catalogo e invia il post al canale con titolo, prezzo, immagine e referral URL.
|