---
title: "Guida all’integrazione con Shopify | Tajo"
description: "Come Tajo collega un negozio Shopify a Brevo: la sincronizzazione via webhook dell’app Shopify, le regole di sincronizzazione che un agente costruisce e una persona approva, e gli strumenti MCP di Shopify."
url: https://tajo.io/it/docs/ecommerce-platforms/shopify/
markdown: https://tajo.io/it/docs/ecommerce-platforms/shopify.md
lang: it-IT
author: "Set Noa"
author_url: https://tajo.io/it/set-noa/
robots: noindex
---

Richiedi l’accesso anticipato

Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo.

# Guida all’integrazione con Shopify

[Set Noa](https://tajo.io/it/set-noa/)

Tajo collega Shopify a Brevo in due punti. L’app Shopify di Tajo trasforma i webhook di Shopify in scritture su Brevo appena arrivano. Le regole di sincronizzazione, che un agente costruisce e una persona approva, spostano i record in Brevo secondo una pianificazione. Questa pagina copre entrambi, poi gli strumenti Shopify che Tajo offre via MCP.

## Prerequisiti

Prima di iniziare l’integrazione, assicurati di avere:

- **Negozio Shopify** con qualsiasi piano (Basic, Shopify, Advanced o Plus)
- **Account Tajo** (Tajo è in early access)
- **Account Brevo**, la destinazione della sincronizzazione
- **Accesso amministratore** al tuo negozio Shopify

## Passo 1: collega il tuo negozio Shopify

Tajo è in early access. L’app Shopify non è presente nello Shopify App Store e non esiste un link di installazione self-service. [Contatta il team](https://tajo.io/it/contact) per la configurazione. Quando il tuo workspace Tajo è pronto:

1. In Tajo, apri **Connections**.
2. Inserisci il dominio myshopify.com del tuo negozio e scegli **Connect Shopify**. Shopify mostra gli scope richiesti da Tajo e ti riporta a Tajo quando li approvi.
3. Verifica a cosa serve ogni scope, e cosa Tajo riscrive in Shopify, in [Autorizzazioni Shopify spiegate](https://tajo.io/it/resources/help/integrations/shopify-permissions-explained/).

## Passo 2: cosa invia a Brevo l’app Shopify di Tajo

L’app verifica ogni webhook di Shopify, lo memorizza, lo mette in coda e lo elabora subito. I topic dei clienti e dei prodotti attendono prima circa quattro secondi. Non c’è una finestra batch. Un job non riuscito viene ritentato con backoff.

### Topic webhook

L’app Shopify di Tajo si iscrive a questi topic webhook di Shopify:

| Topic webhook | Scopo |
| --- | --- |
| `customers/create`, `customers/update`, `customers/delete` | Mantenere aggiornati i contatti Brevo |
| `orders/create`, `orders/updated`, `orders/fulfilled`, `orders/cancelled` | Eventi degli ordini e metriche degli ordini per Brevo |
| `orders/paid`, `refunds/create` | Assegnare e detrarre punti fedeltà |
| `checkouts/create`, `checkouts/update` | Recupero dei checkout abbandonati in Brevo |
| `products/create`, `products/update`, `products/delete` | Mantenere aggiornato il catalogo prodotti in Brevo |
| `inventory_levels/update` | Mantenere aggiornate in Brevo le scorte dei prodotti |
| `collections/create`, `collections/update`, `collections/delete` | Mantenere aggiornate le collezioni |
| `companies/*`, `company_contacts/*`, `company_locations/*` (create, update, delete) | Sincronizzazione delle aziende B2B |
| `app/uninstalled`, `app/scopes_update`, `app_subscriptions/update` | Ciclo di vita dell’app |

Vengono gestiti anche i webhook obbligatori di Shopify per la privacy (richiesta dei dati del cliente, cancellazione dei dati del cliente, cancellazione dei dati del negozio). L’app non si iscrive a `carts/*`. I carrelli abbandonati arrivano dai topic `checkouts/*`.

Cosa arriva in Brevo:

| Evento Shopify | In Brevo |
| --- | --- |
| Cliente creato o aggiornato | Il contatto viene creato o aggiornato con nome, email e consenso al marketing. Nei piani a pagamento l’app aggiunge tag, numero di ordini, importo speso e ultimo ordine. |
| Cliente eliminato | Il contatto viene disiscritto, non eliminato |
| Ordine creato, aggiornato, pagato, evaso o annullato | L’ordine tramite l’API degli ordini di Brevo, e gli eventi `order_paid`, `order_completed` e `order_cancelled` |
| Rimborso creato | L’evento `order_refunded`. Se gestisci un programma fedeltà Brevo tramite Tajo, i punti vengono detratti in proporzione. |
| Ordine pagato, con un programma fedeltà Brevo | Punti assegnati in base al tuo tasso di punti per dollaro |
| Checkout creato o aggiornato, con un’email e degli articoli | Gli eventi `cart_updated` e `cart_abandoned`. È la tua automazione Brevo a decidere quando inviare. |
| Prodotto o collezione creati, aggiornati o eliminati | Il catalogo prodotti e le categorie di Brevo |
| Livello delle scorte aggiornato | Le scorte del prodotto nel catalogo di Brevo. Quando una variante passa da 0 a più di 0, ogni acquirente che ha chiesto di essere avvisato riceve un evento `back_in_stock`, una volta per ogni rifornimento. |

L’app non aggiunge un pulsante “Avvisami” al tuo tema. Una richiesta di ritorno in magazzino deve arrivare dalla tua vetrina, per esempio da un pulsante che aggiungi tu.

### Dati esistenti

All’installazione, l’app importa i tuoi clienti esistenti come contatti Brevo. Una sincronizzazione storica completa si avvia dalla pagina di sincronizzazione dell’app. Nei piani a pagamento importa anche prodotti, collezioni, aziende e ordini.

## Passo 3: costruisci una regola di sincronizzazione con l’agente

Una regola di sincronizzazione è la definizione dichiarativa di una sincronizzazione: una risorsa sorgente, un’azione Brevo, una mappatura dei campi e un filtro. Non la scrivi a mano. La descrivi, un agente la costruisce e una persona la approva.

1. In Tajo, apri **Agents** e chiedi la sincronizzazione al **Brevo Integration Architect** in linguaggio naturale. Per esempio: “Invia a Brevo come contatti i clienti Shopify che hanno accettato il marketing via email.”
2. L’agente ispeziona il connettore Shopify. Il suo campione restituisce nomi e tipi dei campi, mai i valori dei clienti.
3. Propone una regola con una mappatura dei campi e un filtro, poi convalida la mappatura dei campi rispetto all’azione Brevo ed esegue una prova della bozza. Nessuno dei due passaggi legge record dei clienti.
4. Salva la regola come bozza. Puoi anche partire da un template in **Connections > Syncs and mappings > New sync from template**.
5. **Request publish approval** avvia un’anteprima sul tuo negozio. Legge al massimo 10 record, non scrive nulla in Brevo e non sposta il cursore. Registra solo conteggi: record letti, idonei, mappati e scartati dal filtro, più gli errori di mappatura. Se l’anteprima fallisce, non viene creata alcuna approvazione.
6. Una persona approva la richiesta nella pagina **Approvals**, con una motivazione scritta. L’approvazione è legata a un digest SHA-256 della regola e scade dopo 30 minuti. La pagina della regola mostra allora **Publish approved version**.

Modificare una regola pubblicata la riporta in bozza. Deve ripassare da anteprima e approvazione prima di essere eseguita di nuovo.

### Una regola reale

Questo è il template **Shopify customers -> Brevo contacts** come lo definisce Tajo:

```ts
sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",
```

Il filtro è il controllo del consenso. Tajo ricava entrambi i valori da `email_marketing_consent.state` di Shopify, o dal vecchio flag `accepts_marketing`. Una regola che scrive contatti in Brevo non può essere pubblicata senza questo filtro. L’altro template Shopify, **Shopify orders → Brevo orders**, registra gli ordini in Brevo per gli acquirenti che hanno accettato il marketing al checkout.

### Quando viene eseguita una regola

- Le regole di sincronizzazione dei contatti vengono eseguite ogni 15 minuti per impostazione predefinita. Ogni esecuzione parte dal cursore della regola.
- La pagina di una regola attiva ha un pulsante **Test run (1 batch)**.
- Una regola **Shopify orders → Brevo orders** attiva e pubblicata viene eseguita anch’essa ogni 15 minuti. La sua prima esecuzione pianificata parte da qualche minuto prima di quel momento e non invia ordini più vecchi. Ogni esecuzione successiva invia gli ordini aggiornati dopo quella precedente.
- Gli ordini passati arrivano in Brevo solo quando esegui tu la regola: con **Test run (1 batch)**, oppure chiedendo all’agente **Sync Operator** di eseguirla.
- Una regola degli ordini viene eseguita secondo la pianificazione solo con il filtro di opt-in al marketing dell’acquirente previsto dal template. Una regola con il filtro modificato viene eseguita solo quando la avvii tu.
- Dopo cinque esecuzioni consecutive non riuscite, la regola si mette in pausa e la sua pagina mostra l’ultimo errore. Risolvi la causa, poi pubblica di nuovo.

Ogni esecuzione compare nella cronologia delle esecuzioni della regola, con i record letti, scritti e non riusciti, e la sua durata.

## Cosa legge e scrive il connettore Shopify

Le regole di sincronizzazione scrivono solo nella destinazione, qui Brevo. Non scrivono mai in Shopify.

L’app Shopify di Tajo richiede 12 scope ed esegue un breve elenco di scritture in Shopify, come le revoche del consenso e i tag fedeltà. [Autorizzazioni Shopify spiegate](https://tajo.io/it/resources/help/integrations/shopify-permissions-explained/) elenca ogni scope e ogni scrittura, con ciò che la attiva.

Agenti e host MCP raggiungono il negozio tramite il connettore Shopify:

| Letture | Scritture |
| --- | --- |
| Dettagli del negozio, clienti (elenco e ricerca), ordini, prodotti, metafield dei clienti, livelli delle scorte, stato dell’esportazione bulk | Metafield e tag dei clienti, e avvio di un’esportazione bulk. Ogni scrittura viene preparata come proposta e viene eseguita solo dopo l’approvazione. |

Il connettore dichiara anche una rettifica delle scorte. Richiede lo scope `write_inventory`, che l’app Shopify di Tajo non richiede.

## Passo 4: usa gli strumenti Shopify via MCP

Tajo offre il connettore Shopify come server MCP su `https://alto.tajo.io/mcp/connectors/shopify`. Aggiungilo a Claude Code:

```bash
claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify
```

L’host individua il server OAuth di Tajo e apre l’accesso a Tajo. L’accesso è limitato agli account in early access. Il server espone 12 strumenti:

| Strumento | Cosa fa |
| --- | --- |
| `preview_tajo_shopify_app` | Anteprima interattiva dell’app Shopify di Tajo, resa come MCP UI |
| `get_shop` | I dettagli del negozio |
| `search_customers` | Cerca clienti con la sintassi di query di Shopify, come `tag:tajo-vip` o `total_spent:>100` |
| `list_customers` | Elenca i clienti, con paginazione |
| `list_orders` | Elenca gli ordini, con paginazione |
| `list_products` | Elenca i prodotti con varianti, immagini e scorte |
| `get_customer_metafields` | Legge i metafield di un cliente |
| `get_inventory_levels` | Legge le scorte di una variante in tutte le sedi |
| `poll_bulk_export` | Controlla un’esportazione bulk e ottiene il link di download quando è completata |
| `calculate_rewards_profile` | Calcola livello, punti e saldo premi di un cliente dai dati commerce sincronizzati |
| `shopify_propose` | Prepara una scrittura su Shopify come proposta. Non viene inviato nulla. |
| `shopify_apply` | Esegue una proposta approvata |

## Risoluzione dei problemi

- Contatti che non compaiono in Brevo: vedi [contatti mancanti in Brevo](https://tajo.io/it/resources/help/troubleshooting/contacts-missing-in-brevo/).
- Una regola che non viene eseguita, o che si è messa in pausa: vedi [dati non sincronizzati](https://tajo.io/it/resources/help/troubleshooting/data-not-syncing/).

## Prossimi passi

- [Capire la sincronizzazione dei dati](https://tajo.io/it/resources/help/getting-started/understanding-data-sync/), come si comportano le regole di sincronizzazione
- [Autorizzazioni Shopify spiegate](https://tajo.io/it/resources/help/integrations/shopify-permissions-explained/), ogni scope e ogni scrittura
- [Shopify + Brevo](https://tajo.io/it/docs/integrations/shopify-brevo), la guida all’integrazione
- [Contatta il team](https://tajo.io/it/contact) per la configurazione