# 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.