Richiedi l’accesso anticipato

Inserisci il tuo nome e un indirizzo email o un numero di telefono. Ti contatteremo con tutte le informazioni per accedere a Tajo.

In questa pagina

Guida all’integrazione WooCommerce

Questa guida collega un negozio WooCommerce a Tajo. L’integrazione ha due metà che lavorano insieme:

Plugin Tajo for WooCommerce: cattura gli eventi di engagement in tempo reale (ordini, carrelli, rimborsi, recensioni, invii di moduli) dentro WordPress e li consegna a Tajo attraverso un outbox durevole e firmato.
Connessione REST WooCommerce: Tajo legge clienti, ordini, prodotti, coupon, rimborsi e recensioni del tuo negozio per l’importazione storica e la sincronizzazione continua. Vedi il riferimento del connettore WooCommerce per la configurazione solo REST.

L’automazione del marketing vera e propria (email, SMS, WhatsApp tramite Brevo e altri provider) si configura in Tajo, non nel plugin. Il compito del plugin è far uscire da WordPress eventi affidabili.

Prerequisiti

WordPress 6.3+ con accesso amministratore
PHP 7.4+
WooCommerce 7.0+ (il plugin funziona anche su siti WordPress senza WooCommerce: gli adattatori commerce restano semplicemente inattivi)
Account Tajo con una connessione WordPress già creata
HTTPS sull’endpoint Tajo (sempre vero per Tajo in hosting)

Passaggio 1: installa il plugin Tajo for WooCommerce

Installazione manuale

# Download the plugin
cd wp-content/plugins
wget https://tajo.io/downloads/woocommerce/tajo-woocommerce-latest.zip

# Verify and unzip
unzip tajo-woocommerce-latest.zip

Poi attivalo dall’amministrazione di WordPress:

Vai su Plugins → Installed Plugins
Cerca “Tajo for WooCommerce”
Clicca su Activate

Puoi anche caricare lo zip direttamente da Plugins → Add New → Upload Plugin. Insieme a ogni release viene pubblicato un checksum SHA-256 su tajo.io/downloads/woocommerce/. Il plugin non è ancora presente nella directory di WordPress.org; oggi l’installazione manuale è il percorso supportato.

Passaggio 2: configura la connessione

Vai su WooCommerce → Tajo (sui siti senza WooCommerce: Settings → Tajo) e inserisci i tre valori della tua connessione WordPress in Tajo:

Campo	Valore
Endpoint Tajo	L’URL HTTPS del webhook mostrato in Tajo, per esempio `https://alto.tajo.io/api/connectors/wordpress/webhooks/engagement`
Binding ID	Il binding ID della connessione, preso da Tajo
Segreto di firma	Il segreto condiviso (da 32 a 256 caratteri). All’attivazione il plugin genera un segreto locale robusto: incollalo in Tajo, oppure incolla qui il segreto di Tajo

Non ci sono costanti con API key da aggiungere a wp-config.php. Gli eventi restano in coda in sicurezza nell’outbox locale finché non salvi tutti e tre i valori.

Poi verifica il flusso da un capo all’altro:

Clicca su Queue test event, poi su Process now.
La tabella dell’outbox di consegna deve mostrare l’evento come consegnato.
In Tajo, verifica che l’evento connection.test sia arrivato sulla connessione WordPress.

Cosa invia il plugin

Ogni evento è una busta compatta e ridotta al minimo dei dati, firmata con HMAC-SHA256. Da WordPress escono solo i campi identificativi di engagement (email, telefono, ID locali) più metadati di evento limitati, mai nomi, indirizzi postali, indirizzi IP, user agent, testi dei commenti, campi arbitrari dei moduli, note d’ordine o dettagli di pagamento.

Eventi WooCommerce

Hook	Evento
`woocommerce_created_customer` / `woocommerce_update_customer`	`customer.created` / `customer.updated`
`woocommerce_new_product` / `woocommerce_update_product`	`product.created` / `product.updated`
`woocommerce_add_to_cart`, rimozione di un articolo, applicazione/rimozione di un coupon	`cart.updated` (con riepilogo del carrello per i flussi di abbandono)
`woocommerce_cart_emptied`	`cart.emptied`
`woocommerce_new_order` / `woocommerce_update_order`	`order.placed` / `order.updated`
`woocommerce_order_status_changed`	`order.status_changed` (+ `order.fulfilled` al completamento)
`woocommerce_payment_complete`	`order.paid`
`woocommerce_order_refunded`	`refund.created`
Aggiornamenti di stato di WooCommerce Subscriptions	`subscription.status_changed`

Gli eventi d’ordine portano con sé numero d’ordine, stato, valuta, totali, righe d’ordine e URL pronti all’uso per recensione e riordino: abbastanza per automazioni post-acquisto e di win-back senza una seconda chiamata API.

Eventi WordPress

contact.created / contact.updated / contact.deleted per gli account utente
content.published / content.updated / content.unpublished per i contenuti pubblici
comment.created / comment.status_changed per i commenti dei visitatori e le recensioni dei prodotti (le note d’ordine interne di WooCommerce, i pingback e i trackback non vengono mai emessi)
form.submitted per gli invii riusciti di Contact Form 7, WPForms, Gravity Forms e Fluent Forms: vengono estratti solo i campi identificativi tipizzati di email e telefono più i metadati del modulo; i campi arbitrari inviati vengono scartati

Affidabilità: l’outbox di consegna

Il plugin non spara mai eventi verso Tajo direttamente durante il caricamento di una pagina. Ogni evento viene prima scritto in una tabella di outbox locale, poi consegnato da WP-Cron con:

Backoff esponenziale limitato (fino a 8 tentativi, rispettando Retry-After)
Dead letter con Replay dead letters in un clic nell’amministrazione
Limiti di conservazione, così un endpoint irraggiungibile non può mai accumulare dati personali (consegnati: 7 giorni; in coda: 30 giorni; dead letter: 30 giorni dall’ultimo aggiornamento)
ID evento idempotenti, così ritentativi e replay non generano mai duplicati a valle

Se il tuo hosting disattiva WP-Cron (DISABLE_WP_CRON), invoca wp-cron.php da uno scheduler reale almeno una volta al minuto.

Il consenso non viene mai dedotto

La creazione di un account, il checkout, l’acquisto e gli invii generici di moduli non vengono trattati come consenso al marketing. Gli eventi integrati portano una lista di consensi vuota. Per registrare un consenso esplicito (per esempio da una casella newsletter selezionata), emettilo tramite l’hook di estensione:

do_action(
    'tajo_engagement_emit',
    'consent.updated',
    array( 'email' => $email ),
    array( 'policyVersion' => '2026-07' ),
    array(
        array(
            'channel'  => 'email',
            'status'   => 'opt_in',        // or 'opt_out'
            'purpose'  => 'marketing',
            'source'   => 'newsletter_checkbox',
            'evidence' => array( 'formId' => 'newsletter-footer', 'field' => 'marketing_email' ),
        ),
    ),
    gmdate( 'c' )
);

Lo stesso hook permette a qualsiasi plugin o tema di emettere eventi personalizzati; tutto passa attraverso lo stesso sanitizzatore, lo stesso outbox e la stessa firma.

Passaggio 3: importazione storica

Gli eventi in tempo reale coprono tutto a partire dall’installazione. Per la storia precedente al plugin, la connessione REST WooCommerce di Tajo importa clienti, ordini, prodotti, coupon, rimborsi e recensioni già esistenti, configurata interamente lato Tajo con una API key REST di WooCommerce (WooCommerce → Settings → Advanced → REST API, permesso di lettura). Vedi il riferimento del connettore WooCommerce per i dettagli.

Il plugin si registra con Tools → Export Personal Data e Tools → Erase Personal Data di WordPress; gli eventi conservati nell’outbox per un’email corrispondente vengono esportati o cancellati localmente.
Cancellazione e consegna condividono un mutex fail-closed, quindi una cancellazione non può mai dichiararsi completata mentre un payload è in corso di invio.
La cancellazione locale copre solo l’outbox di WordPress: invia la richiesta corrispondente in Tajo per i dati a valle.
La disattivazione mette in pausa la consegna ma conserva configurazione ed eventi in coda; eliminare il plugin rimuove definitivamente outbox, impostazioni, segreto e pianificazioni.

Compatibilità

HPOS: il plugin dichiara la compatibilità con WooCommerce High-Performance Order Storage e usa solo oggetti CRUD e hook pubblici.
WooCommerce Subscriptions: i cambi di stato degli abbonamenti vengono catturati quando l’estensione è attiva.
Multisito: la disinstallazione fa pulizia su ogni sito della rete.

Riferimento operativo

La discovery server-to-server e il controllo dell’outbox sono disponibili agli amministratori tramite autenticazione con Application Password:

Metodo	Rotta	Scopo
`GET`	`/wp-json/tajo/v1/capabilities`	Versione del plugin, adattatori rilevati, inventario degli eventi, stato di salute dell’outbox
`GET`	`/wp-json/tajo/v1/outbox`	Conteggi dell’outbox (i payload non vengono mai esposti)
`POST`	`/wp-json/tajo/v1/outbox/process`	Elabora subito un batch
`POST`	`/wp-json/tajo/v1/outbox/replay`	Rigioca le dead letter

Risoluzione dei problemi

Sintomo	Causa e soluzione
Gli eventi restano su “Queued”	Endpoint, binding ID o segreto non ancora salvati: la consegna è in pausa finché non sono configurati tutti e tre
Gli eventi restano su “Retrying”	L’endpoint Tajo non è raggiungibile dal tuo host, oppure WP-Cron non è in esecuzione: controlla la colonna degli errori nella tabella dell’outbox e la configurazione del cron
Le dead letter si accumulano	Un errore non ritentabile (di solito un binding ID o un segreto sbagliato): correggi la configurazione, poi usa Replay dead letters
“Enter a valid HTTPS Tajo webhook endpoint”	L’endpoint deve essere HTTPS e senza credenziali incorporate
Evento di test consegnato ma niente in Tajo	Verifica di aver incollato il binding ID dello stesso workspace o della stessa connessione Tajo a cui appartiene l’endpoint

Passaggi successivi

Riferimento del connettore WooCommerce: sincronizzazione REST, dettagli sulla firma dei webhook, chiavi di configurazione
Sincronizzazione clienti: come mappare i clienti WooCommerce nel tuo sistema di riferimento
Configura in Tajo le automazioni di carrello abbandonato, post-acquisto e win-back usando gli eventi cart.updated, order.placed e order.fulfilled