WooCommerce-Integrationsleitfaden

Dieser Leitfaden verbindet einen WooCommerce-Store mit Tajo. Die Integration besteht aus zwei Hälften, die zusammenarbeiten:

• Plugin Tajo for WooCommerce: erfasst Echtzeit-Engagement-Events (Bestellungen, Warenkörbe, Rückerstattungen, Bewertungen, Formularübermittlungen) innerhalb von WordPress und liefert sie über eine dauerhafte, signierte Outbox an Tajo.
• WooCommerce-REST-Verbindung: Tajo liest Kund:innen, Bestellungen, Produkte, Gutscheine, Rückerstattungen und Bewertungen deines Stores für den historischen Import und den laufenden Sync. Das reine REST-Setup beschreibt die WooCommerce-Connector-Referenz.

Die Marketing-Automatisierung selbst (E-Mail, SMS, WhatsApp über Brevo und andere Anbieter) richtest du in Tajo ein, nicht im Plugin. Die Aufgabe des Plugins ist es, verlässliche Events aus WordPress herauszubekommen.

Voraussetzungen

• WordPress 6.3+ mit Admin-Zugang
• PHP 7.4+
• WooCommerce 7.0+ (das Plugin funktioniert auch auf WordPress-Sites ohne WooCommerce, die Commerce-Adapter bleiben dann einfach inaktiv)
• Tajo-Konto mit einer angelegten WordPress-Verbindung
• HTTPS auf dem Tajo-Endpunkt (bei gehostetem Tajo immer gegeben)

Schritt 1: Das Plugin Tajo for WooCommerce installieren

Manuelle Installation

# 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

Aktiviere es anschließend im WordPress-Admin:

1. Gehe zu Plugins → Installed Plugins
2. Suche „Tajo for WooCommerce“
3. Klicke auf Activate

Du kannst die ZIP-Datei auch direkt über Plugins → Add New → Upload Plugin hochladen. Zu jedem Release wird unter tajo.io/downloads/woocommerce/ eine SHA-256-Prüfsumme veröffentlicht. Das Plugin ist noch nicht im WordPress.org-Verzeichnis gelistet; die manuelle Installation ist heute der unterstützte Weg.

Schritt 2: Die Verbindung konfigurieren

Gehe zu WooCommerce → Tajo (auf Sites ohne WooCommerce: Settings → Tajo) und trage die drei Werte aus deiner Tajo-WordPress-Verbindung ein:

Es gibt keine API-Key-Konstanten, die du in wp-config.php ergänzen musst. Events bleiben sicher in der lokalen Outbox in der Warteschlange, bis alle drei Werte gespeichert sind.

Prüfe danach die Strecke von Anfang bis Ende:

1. Klicke auf Queue test event und dann auf Process now.
2. Die Tabelle der Zustell-Outbox sollte das Event als zugestellt anzeigen.
3. Prüfe in Tajo, dass das Event connection.test an der WordPress-Verbindung angekommen ist.

Was das Plugin sendet

Jedes Event ist ein kompakter, datensparsamer Umschlag, signiert mit HMAC-SHA256. WordPress verlassen nur Engagement-Identitätsfelder (E-Mail, Telefon, lokale IDs) sowie begrenzte Event-Metadaten, nie Namen, Postadressen, IP-Adressen, User Agents, Kommentartexte, beliebige Formularfelder, Bestellnotizen oder Zahlungsdaten.

WooCommerce-Events

Bestell-Events enthalten Bestellnummer, Status, Währung, Summen, Positionen und fertige URLs für Bewertung und Nachbestellung, genug für Automationen nach dem Kauf und zur Rückgewinnung, ganz ohne weiteren API-Aufruf.

WordPress-Events

• contact.created / contact.updated / contact.deleted für Benutzerkonten
• content.published / content.updated / content.unpublished für öffentliche Inhalte
• comment.created / comment.status_changed für Besucherkommentare und Produktbewertungen (interne WooCommerce-Bestellnotizen, Pingbacks und Trackbacks werden nie gesendet)
• form.submitted für erfolgreiche Übermittlungen von Contact Form 7, WPForms, Gravity Forms und Fluent Forms, extrahiert werden nur typisierte Identitätsfelder für E-Mail und Telefon sowie Formular-Metadaten; beliebige übermittelte Felder werden verworfen

Zuverlässigkeit: die Zustell-Outbox

Das Plugin feuert Events nie direkt beim Seitenaufruf an Tajo. Jedes Event wird zuerst in eine lokale Outbox-Tabelle geschrieben und dann per WP-Cron zugestellt, mit:

• Begrenztem exponentiellem Backoff (bis zu 8 Versuche, mit Beachtung von Retry-After)
• Dead Letters mit Replay dead letters per Klick im Admin
• Aufbewahrungsgrenzen, damit ein nicht erreichbarer Endpunkt nie personenbezogene Daten anhäuft (zugestellt: 7 Tage; in der Warteschlange: 30 Tage; Dead Letters: 30 Tage nach der letzten Aktualisierung)
• Idempotenten Event-IDs, damit Wiederholungen und Replays nie Duplikate im nachgelagerten System erzeugen

Wenn dein Hoster WP-Cron deaktiviert (DISABLE_WP_CRON), rufe wp-cron.php mindestens einmal pro Minute über einen echten Scheduler auf.

Einverständnis wird nie abgeleitet

Kontoerstellung, Checkout, Kauf und allgemeine Formularübermittlungen gelten nicht als Marketing-Einverständnis. Eingebaute Events tragen eine leere Einverständnisliste. Um ein ausdrückliches Einverständnis festzuhalten (zum Beispiel aus einer angehakten Newsletter-Box), sende es über den Erweiterungs-Hook:

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' )
);

Derselbe Hook erlaubt jedem Plugin und jedem Theme, eigene Events zu senden; alles läuft durch denselben Sanitizer, dieselbe Outbox und dieselbe Signatur.

Schritt 3: Historischer Import

Echtzeit-Events decken alles ab der Installation ab. Für die Historie vor dem Plugin importiert die WooCommerce-REST-Verbindung von Tajo bestehende Kund:innen, Bestellungen, Produkte, Gutscheine, Rückerstattungen und Bewertungen, vollständig auf der Tajo-Seite konfiguriert mit einem WooCommerce-REST-API-Key (WooCommerce → Settings → Advanced → REST API, Leseberechtigung). Details findest du in der WooCommerce-Connector-Referenz.

Datenschutz und DSGVO

• Das Plugin registriert sich bei WordPress unter Tools → Export Personal Data und Tools → Erase Personal Data; aufbewahrte Outbox-Events zu einer passenden E-Mail-Adresse werden lokal exportiert oder gelöscht.
• Löschung und Zustellung teilen sich einen fail-closed Mutex, damit eine Löschung nie den Abschluss meldet, während ein Payload gerade versendet wird.
• Die lokale Löschung umfasst nur die WordPress-Outbox, für nachgelagerte Daten reiche die entsprechende Anfrage in Tajo ein.
• Eine Deaktivierung pausiert die Zustellung, behält aber Konfiguration und Events in der Warteschlange; das Löschen des Plugins entfernt Outbox, Einstellungen, Secret und Zeitpläne dauerhaft.

Kompatibilität

• HPOS: Das Plugin erklärt Kompatibilität mit WooCommerce High-Performance Order Storage und nutzt ausschließlich CRUD-Objekte und öffentliche Hooks.
• WooCommerce Subscriptions: Statusänderungen von Abos werden erfasst, wenn die Extension aktiv ist.
• Multisite: Die Deinstallation räumt jede Site im Netzwerk auf.

Referenz für den Betrieb

Server-zu-Server-Discovery und Outbox-Steuerung stehen Admins über die Authentifizierung mit Application Password zur Verfügung:

Fehlerbehebung

Nächste Schritte

• WooCommerce-Connector-Referenz: REST-Sync, Details zur Webhook-Signatur, Konfigurationsschlüssel
• Kundensynchronisation: WooCommerce-Kund:innen in dein System of Record übernehmen
• Richte in Tajo Automationen für Warenkorbabbrüche, nach dem Kauf und zur Rückgewinnung ein, auf Basis der Events cart.updated, order.placed und order.fulfilled