Connettore WooCommerce

Connettore WooCommerce

Collega il tuo negozio WooCommerce a Brevo tramite Tajo per una sincronizzazione completa dei dati e-commerce. Sfrutta la WooCommerce REST API per sincronizzare clienti, ordini, prodotti e dati coupon per campagne di marketing mirate e workflow automatizzati.

Panoramica

Funzionalità

• Sincronizzazione clienti - Sincronizzazione in tempo reale dei dati cliente con i contatti Brevo
• Tracciamento ordini - Tracciamento completo degli eventi del ciclo di vita dell’ordine per flussi post-acquisto
• Sincronizzazione catalogo prodotti - Sincronizza prodotti e variazioni per raccomandazioni email
• Gestione coupon - Sincronizza i codici coupon per le campagne promozionali
• Supporto webhook - Aggiornamenti in tempo reale tramite i webhook di WooCommerce
• Abbandono del carrello - Traccia e recupera i carrelli abbandonati
• Supporto multi-sito - Collega installazioni WooCommerce su WordPress multisite
• Meta field personalizzati - Mappa i meta personalizzati di WooCommerce agli attributi Brevo

Prerequisiti

Prima di iniziare, assicurati di avere:

1. Un sito WordPress con il plugin WooCommerce installato e attivato
2. WooCommerce REST API abilitata (Impostazioni > Avanzate > REST API)
3. Consumer Key e Consumer Secret API generati
4. Il tuo sito deve usare HTTPS per l’autenticazione API
5. Un account Brevo con accesso API
6. Un account Tajo con credenziali API

Autenticazione

Chiavi REST API

WooCommerce utilizza coppie Consumer Key e Consumer Secret per l’autenticazione. Generale in WooCommerce > Impostazioni > Avanzate > REST API.

OAuth 1.0a (siti HTTPS)

curl https://yourstore.com/wp-json/wc/v3/orders \
  -u "consumer_key:consumer_secret"

Autenticazione tramite query string (HTTPS)

curl "https://yourstore.com/wp-json/wc/v3/orders?consumer_key=ck_xxx&consumer_secret=cs_xxx"

Livelli di permesso

Configurazione

Setup di base

connectors:
  woocommerce:
    enabled: true
    store_url: "https://yourstore.com"
    consumer_key: "ck_your_consumer_key"
    consumer_secret: "cs_your_consumer_secret"
    api_version: "wc/v3"
    verify_ssl: true

    # Data sync options
    sync:
      customers: true
      orders: true
      products: true
      coupons: true

    # Brevo list assignment
    lists:
      all_customers: 50
      buyers: 51
      abandoned_cart: 52

Mappatura campi cliente

Mappa i campi cliente WooCommerce agli attributi Brevo:

customer_mapping:
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  billing.phone: SMS
  billing.company: COMPANY
  billing.city: CITY
  billing.state: STATE
  billing.country: COUNTRY
  billing.postcode: ZIP

  # E-commerce metrics (computed)
  orders_count: ORDER_COUNT
  total_spent: TOTAL_SPENT
  date_created: SIGNUP_DATE

  # Meta fields
  meta_data.loyalty_points: LOYALTY_POINTS
  meta_data.preferred_category: PREF_CATEGORY

Configurazione webhook

Registra i webhook in WooCommerce > Impostazioni > Avanzate > Webhook:

webhooks:
  - topic: "customer.created"
    event: "customer_created"
  - topic: "customer.updated"
    event: "customer_updated"
  - topic: "order.created"
    event: "order_placed"
  - topic: "order.updated"
    event: "order_updated"
  - topic: "order.completed"
    event: "order_fulfilled"
  - topic: "order.refunded"
    event: "order_refunded"
  - topic: "coupon.created"
    event: "coupon_created"
  - topic: "product.created"
    event: "product_added"
  - topic: "product.updated"
    event: "product_updated"

Endpoint API

Esempi di codice

Inizializza il connettore WooCommerce

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

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

// Connect WooCommerce store
await tajo.connectors.connect('woocommerce', {
  storeUrl: 'https://yourstore.com',
  consumerKey: process.env.WC_CONSUMER_KEY,
  consumerSecret: process.env.WC_CONSUMER_SECRET
});

Recupera e sincronizza i clienti

// Fetch customers using WooCommerce REST API
const WooCommerce = require('@woocommerce/woocommerce-rest-api').default;

const api = new WooCommerce({
  url: 'https://yourstore.com',
  consumerKey: process.env.WC_CONSUMER_KEY,
  consumerSecret: process.env.WC_CONSUMER_SECRET,
  version: 'wc/v3'
});

// List customers with pagination
const response = await api.get('customers', {
  per_page: 100,
  page: 1,
  orderby: 'registered_date',
  order: 'desc'
});

const customers = response.data;
// [{ id, email, first_name, last_name, billing, shipping, ... }]

// Pagination info from headers
const totalPages = response.headers['x-wp-totalpages'];
const totalItems = response.headers['x-wp-total'];

Gestisci eventi webhook

// WooCommerce webhook handler
app.post('/webhooks/woocommerce', async (req, res) => {
  const topic = req.headers['x-wc-webhook-topic'];
  const signature = req.headers['x-wc-webhook-signature'];

  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('base64');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

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

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

Operazioni batch

// Batch create, update, and delete products
const batchResponse = await api.post('products/batch', {
  create: [
    { name: 'New Product', type: 'simple', regular_price: '19.99' }
  ],
  update: [
    { id: 123, regular_price: '24.99' }
  ],
  delete: [456]
});

Limiti di velocità

WooCommerce non impone di per sé limiti di velocità API, ma il server WordPress sottostante e il provider di hosting possono imporre limiti:

Risoluzione dei problemi

Best practice

1. Usa i webhook per la sync in tempo reale - Configura i webhook WooCommerce invece di fare polling dell’API
2. Verifica le firme dei webhook - Convalida sempre l’header X-WC-Webhook-Signature
3. Pagina tutte le richieste di elenco - Usa i parametri page e per_page; controlla l’header X-WP-TotalPages
4. Usa il parametro _fields - Richiedi solo i campi necessari per ridurre la dimensione della risposta e migliorare le performance
5. Operazioni batch - Usa gli endpoint batch per operazioni massive di creazione/aggiornamento/eliminazione (fino a 100 elementi)
6. Pianifica sync grandi - Esegui le sync iniziali complete fuori dagli orari di punta per evitare stress sul server
7. Abilita HTTPS - La WooCommerce API richiede HTTPS per l’autenticazione OAuth

Sicurezza

• OAuth 1.0a - Autenticazione sicura tramite coppie Consumer Key/Secret
• Firme webhook HMAC - Verifica firma SHA-256 per i webhook in entrata
• HTTPS richiesto - L’API richiede cifratura TLS per l’autenticazione
• Scoping dei permessi - Le chiavi API possono essere impostate su Read, Write o Read/Write
• Sicurezza WordPress - Beneficia degli aggiornamenti di sicurezza del core WordPress
• Considerazioni PCI - I dati di pagamento sono gestiti dai gateway di pagamento WooCommerce, non esposti tramite API

Risorse correlate

• Connettore Shopify
• Connettore BigCommerce
• Skill Customer Sync
• Skill Abandoned Cart