Integrazione Magento

Collega il tuo negozio Magento 2 (Open Source / Adobe Commerce) a Conviro così che il tuo chatbot possa tracciare gli ordini, gestire annullamenti e resi e rispondere alle domande sui prodotti direttamente nella chat.

Ci sono due modi per collegarsi, ed entrambi sbloccano le stesse funzionalità di flusso:

1. Con l’estensione ufficiale Conviro – un’installazione automatizzata con un clic. Consigliata per la maggior parte dei merchant.
2. Senza alcuna estensione – una configurazione manuale che usa l’API REST nativa di Magento più un piccolo snippet del widget. Usala se non puoi (o non vuoi) installare moduli di terze parti.

> Punto chiave: l’estensione è un livello di comodità, non un requisito. Tracciamento ordini, annullamento, resi e ricerca prodotti passano per l’API REST nativa di Magento sul backend di Conviro, quindi funzionano in entrambi i casi. L’estensione automatizza soltanto la configurazione, l’iniezione del widget e i webhook degli eventi.

Requisiti

• Piano Pro o superiore
• Magento 2.4+ (Open Source / Community o Adobe Commerce)
• Accesso amministratore al tuo negozio Magento
• La tua chiave API Conviro (generane una in Dashboard -> Settings -> API Keys)

Metodo A – Con l’estensione ufficiale (consigliato)

La via più rapida. Un campo, un clic e tutto è collegato.

Installazione

1. Installa il modulo via Composer:

composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <YOUR_CONVIRO_API_KEY>
composer require conviro/module-aichat
php bin/magento module:enable Conviro_AiChat
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

(Oppure carica lo ZIP dell’estensione dalla dashboard Conviro se non usi Composer.)

1. Nell’admin di Magento vai su Stores -> Configuration -> Conviro -> AI Chat.
2. Incolla la tua chiave API Conviro e fai clic su Save Config.

Cosa accade automaticamente

Quando salvi la chiave API, l’estensione:

• Crea un’integrazione Magento chiamata «Conviro AI Chat» con permessi REST a privilegio minimo (Sales orders, Catalog products, Customers, Carts) e genera un token di accesso.
• Registra il tuo negozio su Conviro (URL del negozio + token) così che i flussi possano leggere i tuoi dati.
• Inietta automaticamente il widget di chat su ogni pagina del negozio – senza modifiche al tema.
• Invia webhook di eventi (ordine effettuato, stato ordine cambiato, prodotto salvato, cliente registrato) così che i dati restino aggiornati quasi in tempo reale.
• Memorizza un segreto webhook firmato così che gli eventi in entrata/uscita vengano verificati.

Tutto qui – i tuoi flussi sono attivi.

Metodo B – Senza l’estensione (configurazione manuale)

Nessuna installazione di moduli necessaria. In ~5 minuti farai ciò che l’estensione fa automaticamente: creare un token API e incollare lo snippet del widget.

Passo 1 – Creare un’integrazione Magento (per i flussi)

1. Nell’admin di Magento vai su System -> Extensions -> Integrations.
2. Fai clic su Add New Integration.
3. Assegna un nome (es. «Conviro») e inserisci la password di amministratore.
4. Apri la scheda API e concedi l’accesso a queste risorse:

• Sales -> Operations -> Orders (ricerca ordini, stato, annullamento)
• Catalog -> Inventory -> Products (ricerca prodotti)
• Customers -> Customer (verifica della titolarità cliente/ordine)
• (opzionale) Sales -> Operations -> Returns se usi il flusso dei resi

1. Fai clic su Save, poi Activate l’integrazione.
2. Copia l’Access Token mostrato dopo l’attivazione.

Passo 2 – Collegare in Conviro

1. Vai su Dashboard -> Settings -> Integrations -> Magento.
2. Inserisci l’URL del tuo negozio (es. https://your-store.com) e incolla l’Access Token.
3. Fai clic su Connect. Conviro verifica il token e abilita i flussi e-commerce.

Passo 3 – Aggiungere il widget di chat

Poiché non c’è un’estensione che inietta il widget automaticamente, aggiungi lo snippet tu stesso. Inseriscilo subito prima del tag body di chiusura del tuo tema, oppure caricalo tramite Google Tag Manager:

<script src="https://cdn.conviro.io/widget/widget.iife.js"></script>
<script>
  cw('init', { publicKey: 'pk_YOUR_PUBLIC_KEY' });
</script>

In Magento, il punto più pulito è Content -> Design -> Configuration -> [il tuo tema] -> HTML Head / Footer, oppure un blocco HTML vario. Anche GTM funziona e sopravvive agli aggiornamenti del tema.

Cosa ti offre ciascun metodo

In sintesi: tutti i flussi rivolti al cliente funzionano in entrambe le modalità. Senza l’estensione rinunci solo alla configurazione con un clic, all’iniezione automatica del widget e alla sincronizzazione webhook in tempo reale – tutto ciò ha semplici equivalenti manuali.

Sicurezza: verifica della titolarità dell’ordine

Entrambi i metodi includono la stessa protezione contro l’indovinare i numeri d’ordine. Prima di rivelare qualsiasi dettaglio dell’ordine, il flusso chiede al cliente l’e-mail dell’ordine:

1. Il cliente fornisce un numero d’ordine.
2. Il bot chiede l’e-mail usata al checkout.
3. Conviro rivela i dettagli dell’ordine solo se l’e-mail corrisponde all’ordine.
4. Se non corrisponde, il bot risponde esattamente come se l’ordine non fosse stato trovato – così un malintenzionato non può capire se un numero d’ordine è reale.

Questo viene applicato nel backend di Conviro, indipendentemente dall’estensione, tramite il passaggio di verifica e-mail del flusso ordini. I modelli di flusso e-commerce predefiniti raccolgono già l’e-mail prima di qualsiasi ricerca.

Flussi e-commerce

Usa i modelli predefiniti in Dashboard -> Flows -> New Flow -> Use Template -> E-Commerce:

• Order Status – cercare stato, spedizione e tracking per numero d’ordine + e-mail.
• Cancel & Refund – verificare la titolarità, poi annullare un ordine idoneo.
• Returns & Exchanges – verificare la titolarità, raccogliere il motivo e avviare un RMA.
• Product Search – trovare prodotti per nome/SKU e condividere i dettagli nella chat.

Tutto questo richiama l’API REST nativa di Magento usando il token del Metodo A o B – nessun endpoint personalizzato richiesto.

Suggerimenti

• Usa l’estensione se puoi – elimina ogni passaggio manuale e mantiene i dati aggiornati tramite webhook.
• Usa la modalità manuale su negozi blindati, marketplace, o quando una policy di sicurezza vieta nuovi moduli.
• Concedi all’integrazione solo le risorse minime che usi davvero – puoi sempre aggiungere Returns in seguito.
• Inizia con il flusso Order Status; risponde alla domanda e-commerce n. 1 e dimostra che la connessione funziona.
• Dopo il collegamento, prova chiedendo al bot un ordine reale (con l’e-mail corrispondente) e un prodotto/SKU reale.