Ръководство за интеграция с WooCommerce

Това ръководство свързва магазин на WooCommerce с Tajo. Интеграцията има две половини, които работят заедно:

• Приставката Tajo for WooCommerce: прихваща събития за ангажиране в реално време (поръчки, колички, възстановявания, отзиви, изпратени формуляри) вътре в WordPress и ги доставя до Tajo през устойчива, подписана изходяща опашка.
• WooCommerce REST връзка: Tajo чете клиентите, поръчките, продуктите, купоните, възстановяванията и отзивите на магазина Ви за исторически внос и текуща синхронизация. Вижте справочника за конектора WooCommerce за настройка само през REST.

Самата маркетингова автоматизация (имейл, SMS, WhatsApp чрез Brevo и други доставчици) се конфигурира в Tajo, а не в приставката. Задачата на приставката е да изведе надеждни събития от WordPress.

Предварителни изисквания

• WordPress 6.3+ с администраторски достъп
• PHP 7.4+
• WooCommerce 7.0+ (приставката работи и на сайтове с WordPress без WooCommerce, като адаптерите за търговия просто остават неактивни)
• Акаунт в Tajo със създадена връзка към WordPress
• HTTPS на крайната точка на Tajo (винаги е налице при хостван Tajo)

Стъпка 1: Инсталирайте приставката Tajo for WooCommerce

Ръчна инсталация

# 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

След това я активирайте от администрацията на WordPress:

1. Отидете в Plugins → Installed Plugins
2. Намерете „Tajo for WooCommerce“
3. Кликнете върху Activate

Можете също да качите zip файла директно през Plugins → Add New → Upload Plugin. Заедно с всяко издание се публикува контролна сума SHA-256 на tajo.io/downloads/woocommerce/. Приставката още не е включена в директорията на WordPress.org; ръчната инсталация е поддържаният път днес.

Стъпка 2: Конфигурирайте връзката

Отидете в WooCommerce → Tajo (на сайтове без WooCommerce: Settings → Tajo) и въведете трите стойности от Вашата WordPress връзка в Tajo:

Няма константи с API ключове, които да добавяте в wp-config.php. Събитията остават безопасно на опашка в локалната изходяща опашка, докато и трите стойности не бъдат запазени.

След това проверете целия път от край до край:

1. Кликнете върху Queue test event, след което върху Process now.
2. Таблицата на изходящата опашка трябва да покаже събитието като доставено.
3. В Tajo потвърдете, че събитието connection.test е пристигнало по връзката към WordPress.

Какво изпраща приставката

Всяко събитие е компактен плик с минимизирани данни, подписан с HMAC-SHA256. От WordPress излизат само полетата за самоличност при ангажиране (имейл, телефон, локални идентификатори) плюс ограничени метаданни за събитието, но никога имена, пощенски адреси, IP адреси, потребителски агенти, текстове на коментари, произволни полета от формуляри, бележки по поръчки или платежни данни.

Събития от WooCommerce

Събитията за поръчки носят номера на поръчката, статуса, валутата, сумите, редовете и готови за употреба адреси за отзив или повторна поръчка, което е достатъчно за автоматизации след покупка и за връщане на клиенти без допълнителна заявка към API.

Събития от WordPress

• contact.created / contact.updated / contact.deleted за потребителски акаунти
• content.published / content.updated / content.unpublished за публично съдържание
• comment.created / comment.status_changed за коментари на посетители и отзиви за продукти (вътрешните бележки по поръчки в WooCommerce, pingbacks и trackbacks никога не се изпращат)
• form.submitted за успешно изпратени формуляри през Contact Form 7, WPForms, Gravity Forms и Fluent Forms, като се извличат само типизираните полета за имейл и телефон и метаданните на формуляра; произволно изпратените полета се отхвърлят

Надеждност: изходящата опашка за доставка

Приставката никога не изстрелва събития към Tajo директно при зареждане на страница. Всяко събитие първо се записва в локална таблица на изходящата опашка и след това се доставя от WP-Cron с:

• Ограничено експоненциално изчакване (до 8 опита, със спазване на Retry-After)
• Недоставени съобщения с Replay dead letters с едно кликване в администрацията
• Ограничения за съхранение, така че недостъпна крайна точка никога да не трупа лични данни (доставени: 7 дни; на опашка: 30 дни; недоставени: 30 дни след последната промяна)
• Идемпотентни идентификатори на събития, така че повторните опити и повторните изпращания никога да не дублират надолу по веригата

Ако Вашият хостинг изключва WP-Cron (DISABLE_WP_CRON), извиквайте wp-cron.php от истински планировчик поне веднъж в минута.

Съгласието никога не се предполага

Създаването на акаунт, плащането, покупката и общите изпратени формуляри не се третират като маркетингово съгласие. Вградените събития носят празен списък със съгласия. За да запишете изрично съгласие (например от отметнато поле за бюлетин), изпратете го през 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' )
);

Същият hook позволява на всяка приставка или тема да изпраща персонализирани събития; всичко минава през същия почистващ модул, същата изходяща опашка и същия подпис.

Стъпка 3: Исторически внос

Събитията в реално време покриват всичко от инсталацията нататък. За историята отпреди приставката WooCommerce REST връзката на Tajo внася съществуващите клиенти, поръчки, продукти, купони, възстановявания и отзиви, като се конфигурира изцяло от страната на Tajo с ключ за WooCommerce REST API (WooCommerce → Settings → Advanced → REST API, права за четене). Вижте справочника за конектора WooCommerce за подробности.

Поверителност и GDPR

• Приставката се регистрира в Tools → Export Personal Data и Tools → Erase Personal Data на WordPress; запазените събития в изходящата опашка за съвпадащ имейл се експортират или изтриват локално.
• Изтриването и доставката споделят взаимно изключване, което се затваря при отказ, така че изтриване никога не може да отчете завършване, докато дадена заявка е по средата на изпращане.
• Локалното изтриване покрива само изходящата опашка на WordPress, затова подайте съответната заявка в Tajo за данните надолу по веригата.
• Деактивирането спира доставката, но запазва конфигурацията и събитията на опашката; изтриването на приставката премахва завинаги изходящата опашка, настройките, тайната и графиците.

Съвместимост

• HPOS: приставката декларира съвместимост с WooCommerce High-Performance Order Storage и използва само CRUD обекти и публични hooks.
• WooCommerce Subscriptions: промените в статуса на абонаментите се прихващат, когато разширението е активно.
• Multisite: деинсталирането почиства всеки сайт в мрежата.

Справочник за експлоатация

Откриването между сървъри и управлението на изходящата опашка са достъпни за администратори през автентикация с Application Password:

Отстраняване на проблеми

Следващи стъпки

• Справочник за конектора WooCommerce: REST синхронизация, подробности за подписа на webhook, ключове за конфигурация
• Синхронизация на клиенти: съпоставяне на клиентите от WooCommerce с Вашата система на запис
• Конфигурирайте автоматизации за изоставени колички, за след покупка и за връщане на клиенти в Tajo със събитията cart.updated, order.placed и order.fulfilled