Connettore Shopify

Connettore Shopify

Collega il tuo negozio Shopify a Brevo per una sincronizzazione completa dei dati cliente, il recupero dei carrelli abbandonati e campagne di marketing automatizzate.

Panoramica

Funzionalità

• Sincronizzazione clienti in tempo reale - I dati dei clienti vengono sincronizzati istantaneamente con i contatti Brevo
• Tracciamento ordini - Eventi degli ordini per flussi post-acquisto
• Sincronizzazione catalogo prodotti - Prodotti disponibili per raccomandazioni
• Abbandono carrello - Traccia e recupera i carrelli abbandonati
• Comportamento di navigazione - Tracciamento visualizzazioni pagina e interesse sui prodotti
• Supporto multi-store - Collega più negozi Shopify

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un negozio Shopify con accesso admin
2. Un account Brevo con accesso API
3. Un account Tajo

Installazione

Opzione 1: Shopify App Store (consigliata)

1. Visita l’app Tajo nello Shopify App Store
2. Clicca su “Aggiungi app”
3. Concedi i permessi richiesti
4. Collega il tuo account Brevo

Opzione 2: Installazione manuale

Passo 1: Crea un’app Shopify

1. Vai nell’admin Shopify → Impostazioni → App e canali di vendita
2. Clicca su “Sviluppa app” → “Crea un’app”
3. Chiamala “Tajo Integration”

Passo 2: Configura gli scope API

Abilita questi scope:

read_customers
write_customers
read_orders
read_products
read_checkouts
write_script_tags

Passo 3: Installa l’app

# Using Tajo CLI
tajo connectors install shopify \
  --shop-url your-store.myshopify.com \
  --api-key $SHOPIFY_API_KEY \
  --api-secret $SHOPIFY_API_SECRET

Passo 4: Configura i webhook

Tajo registra automaticamente questi webhook:

Configurazione

Setup di base

connectors:
  shopify:
    enabled: true
    shop_url: "your-store.myshopify.com"
    api_version: "2024-01"

    # Data sync options
    sync:
      customers: true
      orders: true
      products: true
      carts: true
      inventory: false  # Optional

    # List assignment
    lists:
      all_customers: 5
      buyers: 6
      abandoned_cart: 7

Mappatura dei campi

Mappa i campi Shopify agli attributi di contatto Brevo:

Mappatura attributi personalizzati

field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # E-commerce metrics
  orders_count: ORDER_COUNT
  total_spent: TOTAL_SPENT
  last_order_date: LAST_ORDER_DATE

  # Custom fields
  customer_type: CUSTOMER_TYPE
  preferred_language: LANGUAGE
  loyalty_tier: VIP_TIER

  # Computed fields
  average_order_value: AOV
  days_since_last_order: RECENCY

Sincronizzazione prodotti

Sincronizza i prodotti per le raccomandazioni email:

sync:
  products:
    enabled: true
    include_variants: true
    include_images: true
    categories_as_tags: true

    # Filter products
    filter:
      status: active
      exclude_tags: ["hidden", "wholesale-only"]

Tracciamento inventario

Abilita la sincronizzazione dei livelli di stock:

sync:
  inventory:
    enabled: true
    low_stock_threshold: 10
    out_of_stock_events: true

Eventi

Eventi cliente

Eventi ordine

Eventi carrello

Skill abilitate

Il connettore Shopify abilita queste skill:

Esempi di codice

Inizializza il connettore

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Shopify store
await tajo.connectors.connect('shopify', {
  shopUrl: 'your-store.myshopify.com',
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecret: process.env.SHOPIFY_API_SECRET
});

Esegui la sincronizzazione iniziale

// Full historical sync
await tajo.connectors.sync('shopify', {
  type: 'full',
  resources: ['customers', 'orders', 'products'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('shopify');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   customersCount: 15420,
//   ordersCount: 8234,
//   productsCount: 342
// }

Traccia eventi del carrello

Aggiungi lo script Tajo al tuo tema Shopify:

<!-- Add to theme.liquid before </head> -->
{% if customer %}
<script>
  window.tajoConfig = {
    customerId: "{{ customer.id }}",
    customerEmail: "{{ customer.email }}",
    customerName: "{{ customer.first_name }}"
  };
</script>
{% endif %}
<script src="https://cdn.tajo.io/shopify.js"></script>

Handler webhook personalizzato

// Handle Shopify webhooks manually
app.post('/webhooks/shopify', async (req, res) => {
  const hmac = req.get('X-Shopify-Hmac-SHA256');

  // Verify webhook signature
  if (!verifyShopifyWebhook(req.body, hmac)) {
    return res.status(401).send('Unauthorized');
  }

  const topic = req.get('X-Shopify-Topic');

  // Forward to Tajo
  await tajo.connectors.handleWebhook('shopify', {
    topic,
    payload: req.body
  });

  res.status(200).send('OK');
});

Monitoraggio

Metriche della dashboard

Monitora la tua connessione Shopify nella dashboard Tajo:

• Stato sincronizzazione: Salute della connessione in tempo reale
• Clienti sincronizzati: Totale contatti da Shopify
• Ordini tracciati: Eventi ordine elaborati
• Recupero carrello: Performance del recupero carrelli abbandonati
• Tasso di errore: Tentativi di sincronizzazione falliti

Log dei webhook

Visualizza lo stato di consegna dei webhook:

tajo connectors logs shopify --type webhook --last 24h

Cronologia sincronizzazioni

Controlla le operazioni di sincronizzazione storiche:

tajo connectors history shopify --limit 10

Risoluzione dei problemi

Problemi comuni

Modalità debug

Abilita il logging dettagliato:

connectors:
  shopify:
    debug: true
    log_level: verbose
    log_webhooks: true

Testa la connessione

tajo connectors test shopify
# ✓ API connection successful
# ✓ Webhooks registered
# ✓ Products accessible
# ✓ Customers readable
# ✓ Orders readable

Best practice

1. Inizia con un negozio di test - Usa prima un development store
2. Esegui la sincronizzazione iniziale fuori orario - Le sync grandi possono essere lente
3. Mappa attributi personalizzati - Non affidarti solo alle mappature predefinite
4. Abilita il tracciamento del carrello - Fondamentale per il recupero carrelli abbandonati
5. Monitora la salute dei webhook - Imposta alert per consegne fallite
6. Usa importazioni batch - Per dati storici oltre 10.000 record

Sicurezza

• OAuth 2.0 - Autenticazione sicura basata su token
• Verifica webhook - Validazione firma HMAC
• Storage cifrato - Credenziali API cifrate a riposo
• Accesso con scope - Solo i permessi minimi richiesti

Risorse correlate

• Connettore WooCommerce
• Skill Customer Sync
• Skill Abandoned Cart
• API Contatti Brevo