Руководство по интеграции с Shopify

Tajo соединяет Shopify с Brevo в двух местах. Приложение Tajo для Shopify превращает вебхуки Shopify в записи в Brevo по мере их поступления. Правила синхронизации, которые строит агент и одобряет человек, переносят записи в Brevo по расписанию. На этой странице описано и то и другое, а затем инструменты Shopify, которые Tajo предоставляет через MCP.

Предварительные требования

Перед началом интеграции убедитесь, что у вас есть:

• Магазин Shopify на любом тарифе (Basic, Shopify, Advanced или Plus)
• Аккаунт Tajo (Tajo находится в раннем доступе)
• Аккаунт Brevo, получатель синхронизации
• Права администратора в вашем магазине Shopify

Шаг 1: подключите магазин Shopify

Tajo находится в раннем доступе. Приложение Shopify не опубликовано в Shopify App Store, и ссылки для самостоятельной установки нет. Свяжитесь с командой, чтобы вас подключили. Когда рабочее пространство Tajo будет готово:

1. В Tajo откройте Connections.
2. Введите домен магазина на myshopify.com и выберите Connect Shopify. Shopify покажет scopes, которые запрашивает Tajo, и вернёт вас в Tajo, когда вы их одобрите.
3. Для чего нужен каждый scope и что Tajo записывает обратно в Shopify, описано в статье о разрешениях Shopify.

Шаг 2: что приложение Tajo для Shopify отправляет в Brevo

Приложение проверяет каждый вебхук Shopify, сохраняет его, ставит в очередь и сразу обрабатывает. Темы клиентов и товаров сначала ждут около четырёх секунд. Пакетного окна нет. Неудачное задание повторяется с нарастающей задержкой (backoff).

Темы вебхуков

Приложение Tajo для Shopify подписывается на такие темы вебхуков Shopify:

Обязательные вебхуки Shopify о конфиденциальности (запрос данных клиента, удаление данных клиента, удаление данных магазина) тоже обрабатываются. Приложение не подписывается на carts/*. Брошенные корзины приходят из тем checkouts/*.

Что попадает в Brevo:

Приложение не добавляет кнопку «Notify me» в вашу тему. Запрос на уведомление о поступлении должен приходить с вашей витрины, например с кнопки, которую вы добавите.

Существующие данные

При установке приложение импортирует существующих клиентов как контакты Brevo. Полная историческая синхронизация запускается со страницы синхронизации в приложении. На платных тарифах она также импортирует товары, коллекции, компании и заказы.

Шаг 3: создайте правило синхронизации с помощью агента

Правило синхронизации представляет собой декларативное определение одной синхронизации: исходный ресурс, действие в Brevo, сопоставление полей и фильтр. Вы не пишете его вручную. Вы его описываете, агент строит, а человек одобряет.

1. В Tajo откройте Agents и опишите Brevo Integration Architect нужную синхронизацию обычным языком. Например: «Отправляй в Brevo как контакты тех клиентов Shopify, которые согласились на email-маркетинг».
2. Агент изучает коннектор Shopify. Его выборка возвращает названия и типы полей, но никогда не возвращает значения данных клиентов.
3. Он предлагает правило с сопоставлением полей и фильтром, затем проверяет сопоставление полей на соответствие действию Brevo и выполняет пробный прогон черновика. Ни один из этих шагов не читает записи клиентов.
4. Он сохраняет правило как черновик. Можно также начать с шаблона в разделе Connections > Syncs and mappings > New sync from template.
5. Request publish approval запускает предварительный просмотр на данных вашего магазина. Он читает не более 10 записей, ничего не записывает в Brevo и не сдвигает курсор. Он фиксирует только счётчики: полученные записи, подходящие, сопоставленные и отклонённые фильтром, а также ошибки сопоставления. Если предварительный просмотр завершается ошибкой, запрос на одобрение не создаётся.
6. Человек одобряет запрос на странице Approvals с письменным обоснованием. Одобрение привязано к дайджесту SHA-256 правила и истекает через 30 минут. После этого на странице правила появляется кнопка Publish approved version.

Редактирование опубликованного правила возвращает его в черновик. Прежде чем снова запуститься, оно опять проходит предварительный просмотр и одобрение.

Реальное правило

Так Tajo определяет шаблон Shopify customers -> Brevo contacts:

sourceSlug: "shopify",
sourceResource: "customers",
destinationSlug: "brevo",
destinationAction: "upsert_contact",
fieldMap: [
  { source: "email", destination: "email", transform: "toLowerCase" },
  { source: "first_name", destination: "attributes.FIRSTNAME" },
  { source: "last_name", destination: "attributes.LASTNAME" },
  { source: "phone", destination: "attributes.PHONE" },
  { source: "total_spent", destination: "attributes.TOTAL_SPENT", transform: "toNumber" },
  { source: "orders_count", destination: "attributes.ORDERS_COUNT", transform: "toNumber" },
  { source: "tajo_email_marketing_consent", destination: "attributes.OPT_IN", transform: "toBoolean" },
  { source: "tags", destination: "attributes.SHOPIFY_TAGS" },
  { source: "id", destination: "attributes.SHOPIFY_ID", transform: "toString" },
  { source: "created_at", destination: "attributes.SHOPIFY_CREATED_AT" },
  { source: "updated_at", destination: "attributes.SHOPIFY_UPDATED_AT" },
],
filterExpression:
  "($json.tajo_email_marketing_consent === true) && ($json.tajo_email_suppressed === false)",

Фильтр и есть проверка согласия. Оба значения Tajo выводит из поля Shopify email_marketing_consent.state или из более старого флага accepts_marketing. Правило, которое записывает контакты в Brevo, нельзя опубликовать без этого фильтра. Другой шаблон Shopify, Shopify orders → Brevo orders, фиксирует в Brevo заказы покупателей, которые согласились на маркетинг при оформлении заказа.

Когда выполняется правило

• Правила синхронизации контактов по умолчанию запускаются каждые 15 минут. Каждый запуск начинается с курсора правила.
• На странице активного правила есть кнопка Test run (1 batch).
• Активное опубликованное правило Shopify orders → Brevo orders тоже запускается каждые 15 минут. Первый запуск по расписанию начинается за несколько минут до этого момента и не отправляет более ранние заказы. Каждый следующий запуск отправляет заказы, обновлённые после предыдущего.
• Прошлые заказы попадают в Brevo, только когда вы запускаете правило сами: кнопкой Test run (1 batch) или попросив агента Sync Operator его запустить.
• По расписанию правило для заказов запускается, только если в нём стоит фильтр согласия покупателя на маркетинг из шаблона. Правило с отредактированным фильтром выполняется, только когда вы сами его запускаете.
• После пяти неудачных запусков подряд правило само приостанавливается, а на его странице отображается последняя ошибка. Устраните причину и опубликуйте правило снова.

Каждый запуск отображается в истории запусков правила с числом прочитанных, записанных и ошибочных записей, а также с длительностью.

Что коннектор Shopify читает и записывает

Правила синхронизации записывают только в получатель, в данном случае в Brevo. В Shopify они никогда не записывают.

Приложение Tajo для Shopify запрашивает 12 scopes и выполняет короткий список записей в Shopify, например отзыв согласия и теги лояльности. В статье о разрешениях Shopify перечислены все scopes и все записи, а также то, что их запускает.

Агенты и MCP-хосты обращаются к магазину через коннектор Shopify:

Коннектор также объявляет корректировку запасов. Для неё нужен scope write_inventory, который приложение Tajo для Shopify не запрашивает.

Шаг 4: используйте инструменты Shopify через MCP

Tajo предоставляет коннектор Shopify как MCP-сервер по адресу https://alto.tajo.io/mcp/connectors/shopify. Добавьте его в Claude Code:

claude mcp add --transport http tajo-shopify https://alto.tajo.io/mcp/connectors/shopify

Хост находит OAuth-сервер Tajo и открывает вход в Tajo. Доступ есть только у аккаунтов раннего доступа. Сервер предоставляет 12 инструментов:

Устранение неполадок

• Контакты не появляются в Brevo: см. контакты не появляются в Brevo.
• Правило не запускается или само приостановилось: см. данные не синхронизируются.

Дальнейшие шаги

• Как устроена синхронизация данных, как ведут себя правила синхронизации
• Разрешения Shopify, каждый scope и каждая запись
• Shopify + Brevo, руководство по интеграции
• Свяжитесь с командой, чтобы вас подключили