Documentazione

Multicanale / Sedi

Con la funzione sedi puoi raccogliere e analizzare le recensioni separatamente per filiale, canale di vendita o regione. Ogni sede ha un proprio nome, uno slug, un dominio facoltativo e una lingua predefinita.

Quando usare le sedi?

Le sedi sono ideali se:

• gestisci più filiali o sedi operative
• hai diversi negozi online o domini
• vuoi separare le recensioni per regione o reparto
• vuoi incorporare un widget dedicato per ogni sede sul rispettivo sito web

Gestire le sedi

In Impostazioni → Sedi puoi creare, modificare ed eliminare le sedi.

• Nome: nome visualizzato (ad es. «Filiale Milano Centro»)
• Slug: identificativo univoco, generato automaticamente dal nome
• Dominio: facoltativo, l'URL del sito web della sede
• Lingua: lingua predefinita di questa sede
• Sede predefinita: la sede contrassegnata come predefinita viene usata per le nuove recensioni senza assegnazione esplicita

Se elimini una sede, tutte le recensioni assegnate vengono mantenute: perdono soltanto l'assegnazione alla sede.

Come vengono assegnate le recensioni a una sede?

Ci sono tre modi:

1. Automaticamente tramite il modulo di recensione: se la tua azienda ha più sedi, nella pagina del profilo compare un menu «Quale sede vuoi recensire?» e il cliente sceglie la sede.
2. Tramite gli inviti: quando invii un invito puoi indicare la sede. La recensione viene poi assegnata automaticamente.
3. Tramite API: passa il locationId quando crei una recensione.

Widget per sede

Nel widget builder, in Impostazioni → Filtro sede, puoi limitare un widget a una sede specifica. Il widget mostrerà soltanto le recensioni di quella sede.

Ad esempio, il sito della filiale di Milano può mostrare solo le recensioni di Milano e quello di Roma solo quelle di Roma.

Riferimento API

Creare una sede:

{
  "name": "Negozio online IT",
  "slug": "shop-it",
  "domain": "https://www.il-mio-negozio.it",
  "language": "it"
}

Creare una recensione assegnata a una sede:

{
  "companyId": "...",
  "locationId": "clx...",
  "rating": 5,
  "content": "Servizio eccellente!",
  "reviewerName": "Mario Rossi"
}

Filtrare le recensioni per sede:

// Restituisce solo le recensioni della sede indicata
// Senza locationId vengono restituite tutte le recensioni

Creare un widget con filtro sede:

{
  "companyId": "...",
  "locationId": "clx...",
  "name": "Widget filiale Milano",
  "type": "CAROUSEL",
  "config": { "maxReviews": 5 }
}

Widget multilingue

Il widget incorporato supporta 5 lingue: Deutsch, English, Français, Español e Italiano. Tutti i testi dell'interfaccia (pulsanti, indicazioni temporali, campi del modulo) vengono mostrati automaticamente nella lingua rilevata.

Rilevamento della lingua (priorità)

1. Attributo data-lang sul contenitore del widget (esplicito)
2. Campo locale nella configurazione del widget (dashboard)
3. document.documentElement.lang (lingua HTML della pagina)
4. Valore predefinito: de

Opzione 1: esplicitamente tramite attributo HTML

Ideale per negozi multilingue in cui la lingua di ogni pagina è nota:

<!-- Widget in tedesco -->
<div data-zoom-widget="WIDGET_ID" data-lang="de"></div>

<!-- Widget in inglese -->
<div data-zoom-widget="WIDGET_ID" data-lang="en"></div>

<!-- Widget in francese -->
<div data-zoom-widget="WIDGET_ID" data-lang="fr"></div>

<script src="https://zoom.reviews/widget.js" async></script>

Opzione 2: automaticamente in base alla lingua del negozio

Se il template del tuo negozio imposta correttamente l'attributo lang sul tag <html>, il widget rileva la lingua automaticamente:

<html lang="fr">
  ...
  <div data-zoom-widget="WIDGET_ID"></div>
  <script src="https://zoom.reviews/widget.js" async></script>
</html>

Opzione 3: tramite la configurazione della dashboard

In Widget → Modifica → Impostazioni puoi impostare una lingua fissa per ogni widget. È utile se crei un widget dedicato per ogni negozio o canale linguistico.

Esempio Shopware / Twig

{# Nel template del tuo tema #}
<div data-zoom-widget="WIDGET_ID" 
     data-lang="{{ app.request.locale[:2] }}"></div>
<script src="https://zoom.reviews/widget.js" async></script>

Controllo di integrità (SRI)

Se le tue policy di sicurezza lo richiedono, puoi incorporare una versione fissa con Subresource Integrity invece del widget.js che si aggiorna da solo. Prima di eseguirlo, il browser verifica tramite hash che lo script corrisponda esattamente alla versione pubblicata e, in caso contrario, lo blocca.

<div data-zoom-widget="WIDGET_ID"></div>
<script src="https://zoom.reviews/widget/v1.js"
        integrity="sha384-b+jQQNJZZso+gHv6OrEFQWf3CnUlnPR95LwStglzZ9EDIhLlhwIEMunoVr+X1GKT"
        crossorigin="anonymous" async></script>

Inviti alle recensioni (post-acquisto)

Invia automaticamente inviti alle recensioni ai tuoi clienti dopo l'acquisto. Le email sono multilingue (DE/EN/FR/ES/IT) e contengono un link personalizzato.

Creare un singolo invito

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "email": "cliente@example.com",
  "customerName": "Mario Rossi",
  "orderId": "ORD-10042",
  "orderDate": "2026-07-28T14:30:00Z",
  "locale": "it",
  "locationId": "clx...",
  "delayDays": 7
}

Inviti in blocco (fino a 100 alla volta)

{
  "invitations": [
    { "email": "a@example.com", "customerName": "Anna", "locale": "de" },
    { "email": "b@example.com", "customerName": "Bob", "locale": "en" },
    { "email": "c@example.com", "customerName": "Claire", "locale": "fr" }
  ]
}

Cosa succede per il cliente

1. Il cliente riceve un'email personalizzata con il link alla recensione
2. Il link apre la tua pagina delle recensioni con il nome già compilato
3. La recensione viene contrassegnata automaticamente come verificata (senza captcha)
4. Il token può essere usato una sola volta

Elencare gli inviti

// Status: PENDING, SENT, OPENED, COMPLETED, EXPIRED

Webhook in uscita

Ricevi notifiche in tempo reale su nuove recensioni e inviti. I webhook sono firmati con HMAC-SHA256.

Eventi disponibili

Creare un webhook

{
  "url": "https://your-server.com/webhooks/zoom-reviews",
  "events": ["review.created", "review.approved"]
}

La risposta contiene un secret (visibile una sola volta!) che serve a verificare la firma.

Formato del payload

// Headers:
// X-Webhook-Signature: <HMAC-SHA256 of body>
// X-Webhook-Event: review.created
// X-Webhook-Timestamp: 2026-07-29T18:30:00.000Z

{
  "event": "review.created",
  "data": {
    "id": "clx...",
    "rating": 5,
    "reviewerName": "Mario Rossi",
    "source": "WIDGET",
    "locationId": "clx..."
  },
  "timestamp": "2026-07-29T18:30:00.000Z"
}

Verificare la firma

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Gestione

In Impostazioni → Webhook (in arrivo) oppure tramite API:

• GET /api/webhooks/outgoing — Elencare tutti gli endpoint
• PATCH /api/webhooks/outgoing — Modificare URL, eventi o stato
• DELETE /api/webhooks/outgoing?id=... — Eliminare un endpoint

Integrazione Shopware 6

Inviti automatici alle recensioni dopo il completamento di un ordine nel tuo negozio Shopware 6. L'integrazione rileva automaticamente la lingua dell'ordine e il canale di vendita.

Panoramica

Metodo A: Shopware Flow Builder (consigliato)

1. Nell'amministrazione di Shopware vai su Impostazioni → Flow Builder
2. Crea un nuovo flow con il trigger Order placed oppure Order status changed → Completed
3. Aggiungi un'azione Send HTTP request
4. Metodo: POST
5. URL: il tuo URL webhook (vedi impostazioni di integrazione)
6. Content-Type: application/json

Metodo B: chiamare direttamente l'API REST

In alternativa puoi chiamare direttamente l'API degli inviti da un plugin personalizzato o da un'app:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "email": "{{ order.orderCustomer.email }}",
  "customerName": "{{ order.orderCustomer.firstName }} {{ order.orderCustomer.lastName }}",
  "orderId": "{{ order.orderNumber }}",
  "locale": "it",
  "delayDays": 7
}

Multi-negozio / multicanale

Se gestisci più canali di vendita Shopware:

• Crea in Zoom.Reviews una sede per ogni canale di vendita
• Passa il locationId nella richiesta API
• Le recensioni vengono raccolte separatamente e mostrate per canale

Rilevamento della lingua

L'integrazione Shopware rileva automaticamente la lingua dell'ordine dal campo locale. Lingue supportate: de, en, fr, es, it. In mancanza viene usata la lingua predefinita configurata.

Incorporare il widget nel tema Shopware

{# Widget con rilevamento automatico della lingua #}
<div data-zoom-widget="WIDGET_ID" 
     data-lang="{{ app.request.locale[:2] }}">
</div>
<script src="https://zoom.reviews/widget.js" async></script>