michele/netgescon-day0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
c4f8c827b4
netgescon-day0/docs/AMAZON-CREATORS-API.md

9.1 KiB
Raw Blame History

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:

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:

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:

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:

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.