---
title: "Shopify 集成指南 | Tajo"
description: "Tajo 如何将 Shopify 商店连接到 Brevo：Shopify 应用的 webhook 同步、由代理构建并由人工审批的同步规则，以及 Shopify MCP 工具。"
url: https://tajo.io/zh-cn/docs/ecommerce-platforms/shopify/
markdown: https://tajo.io/zh-cn/docs/ecommerce-platforms/shopify.md
lang: zh-CN
author: "Set Noa"
author_url: https://tajo.io/zh-cn/set-noa/
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Shopify 集成指南

[Set Noa](https://tajo.io/zh-cn/set-noa/)

Tajo 在两个地方将 Shopify 连接到 Brevo。Tajo Shopify 应用在 Shopify webhook 到达时将其转换为对 Brevo 的写入。同步规则由代理构建、由人工审批，按计划将记录写入 Brevo。本页依次介绍这两者，然后介绍 Tajo 通过 MCP 提供的 Shopify 工具。

## 前置条件

开始集成之前，请确保你具备：

- **Shopify 商店**，任意套餐均可（Basic、Shopify、Advanced 或 Plus）
- **Tajo 账号**（Tajo 目前处于 early access 阶段）
- **Brevo 账户**，即同步的目标
- Shopify 商店的**管理员权限**

## 第 1 步：连接你的 Shopify 商店

Tajo 目前处于 early access 阶段。Shopify 应用没有上架 Shopify 应用商店，也没有自助安装链接。请[联系团队](https://tajo.io/zh-cn/contact)完成设置。Tajo 工作区准备就绪后：

1. 在 Tajo 中打开 **Connections**。
2. 输入商店的 myshopify.com 域名，然后选择 **Connect Shopify**。Shopify 会显示 Tajo 请求的权限范围，你批准后会返回 Tajo。
3. 在 [Shopify 权限说明](https://tajo.io/zh-cn/resources/help/integrations/shopify-permissions-explained/)中查看每个权限范围的用途，以及 Tajo 会写回 Shopify 的内容。

## 第 2 步：Tajo Shopify 应用向 Brevo 发送什么

应用会校验每个 Shopify webhook，将其存储、加入队列并立即处理。客户和商品主题会先等待约四秒。没有批处理时间窗口。失败的任务会按退避策略重试。

### Webhook 主题

Tajo Shopify 应用订阅以下 Shopify webhook 主题：

| Webhook 主题 | 用途 |
| --- | --- |
| `customers/create`、`customers/update`、`customers/delete` | 保持 Brevo 联系人最新 |
| `orders/create`、`orders/updated`、`orders/fulfilled`、`orders/cancelled` | 为 Brevo 提供订单事件和订单指标 |
| `orders/paid`、`refunds/create` | 发放和扣减会员积分 |
| `checkouts/create`、`checkouts/update` | 在 Brevo 中挽回弃购结账 |
| `products/create`、`products/update`、`products/delete` | 保持 Brevo 中的商品目录最新 |
| `inventory_levels/update` | 保持 Brevo 中的商品库存最新 |
| `collections/create`、`collections/update`、`collections/delete` | 保持集合最新 |
| `companies/*`、`company_contacts/*`、`company_locations/*`（create、update、delete） | B2B 公司同步 |
| `app/uninstalled`、`app/scopes_update`、`app_subscriptions/update` | 应用生命周期 |

Shopify 强制要求的隐私 webhook（客户数据请求、客户数据删除、店铺数据删除）也会被处理。该应用不订阅 `carts/*`。弃购购物车来自 `checkouts/*` 主题。

写入 Brevo 的内容：

| Shopify 事件 | 在 Brevo 中 |
| --- | --- |
| 客户创建或更新 | 创建或更新联系人，包含姓名、邮箱和营销同意状态。在付费套餐中，应用还会添加标签、订单数、消费金额和最近一笔订单。 |
| 客户删除 | 联系人被退订，而不是被删除 |
| 订单创建、更新、支付、履约或取消 | 通过 Brevo 的订单 API 写入订单，并发送事件 `order_paid`、`order_completed` 和 `order_cancelled` |
| 退款创建 | 事件 `order_refunded`。如果你通过 Tajo 运行 Brevo 会员计划，积分会按比例扣减。 |
| 订单支付，且有 Brevo 会员计划 | 按你设置的每美元积分比例发放积分 |
| 结账创建或更新，且包含邮箱和商品 | 事件 `cart_updated` 和 `cart_abandoned`。何时发送由你的 Brevo 自动化决定。 |
| 商品或集合创建、更新或删除 | Brevo 的商品目录和分类 |
| 库存水平更新 | Brevo 目录中该商品的库存。当某个变体从 0 变为大于 0 时，每位请求到货通知的顾客都会收到一次 `back_in_stock` 事件，每次补货一次。 |

应用不会在你的主题中添加“Notify me”按钮。到货通知请求必须来自你的店面，例如来自你自行添加的按钮。

### 现有数据

安装时，应用会将你的现有客户导入为 Brevo 联系人。完整的历史同步从应用的同步页面启动。在付费套餐中，它还会导入商品、集合、公司和订单。

## 第 3 步：用代理构建同步规则

同步规则是对一次同步的声明式定义：一个源资源、一个 Brevo 操作、一份字段映射和一个过滤条件。你不需要手写。你来描述，代理来构建，由人工审批。

1. 在 Tajo 中打开 **Agents**，用自然语言向 **Brevo Integration Architect** 描述所需的同步。例如：“将接受邮件营销的 Shopify 客户作为联系人发送到 Brevo。”
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** 模板：

```ts
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 个权限范围，并对 Shopify 执行少量写入，例如营销同意退出和会员标签。[Shopify 权限说明](https://tajo.io/zh-cn/resources/help/integrations/shopify-permissions-explained/)列出了每个权限范围和每项写入，以及触发它们的条件。

代理和 MCP 主机通过 Shopify 连接器访问商店：

| 读取 | 写入 |
| --- | --- |
| 店铺信息、客户（列表和搜索）、订单、商品、客户 metafield、库存水平、批量导出状态 | 客户 metafield 和客户标签，以及启动批量导出。每项写入都先暂存为提案，审批通过后才会执行。 |

连接器还声明了库存调整操作。它需要 `write_inventory` 权限范围，而 Tajo Shopify 应用并不请求该范围。

## 第 4 步：通过 MCP 使用 Shopify 工具

Tajo 将 Shopify 连接器作为 MCP 服务器提供，地址为 `https://alto.tajo.io/mcp/connectors/shopify`。将其添加到 Claude Code：

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

主机会发现 Tajo 的 OAuth 服务器并打开 Tajo 登录页。仅 early access 账号可以访问。该服务器提供 12 个工具：

| 工具 | 作用 |
| --- | --- |
| `preview_tajo_shopify_app` | Tajo Shopify 应用的交互式预览，以 MCP UI 呈现 |
| `get_shop` | 店铺信息 |
| `search_customers` | 使用 Shopify 查询语法搜索客户，例如 `tag:tajo-vip` 或 `total_spent:>100` |
| `list_customers` | 分页列出客户 |
| `list_orders` | 分页列出订单 |
| `list_products` | 列出商品及其变体、图片和库存 |
| `get_customer_metafields` | 读取客户的 metafield |
| `get_inventory_levels` | 读取某个变体在各地点的库存 |
| `poll_bulk_export` | 检查批量导出，完成后获取下载链接 |
| `calculate_rewards_profile` | 根据已同步的商务数据计算客户的等级、积分和奖励余额 |
| `shopify_propose` | 将一项 Shopify 写入暂存为提案。不会发送任何内容。 |
| `shopify_apply` | 执行已审批的提案 |

## 问题排查

- 联系人没有出现在 Brevo 中：请参阅 [Brevo 中缺少联系人](https://tajo.io/zh-cn/resources/help/troubleshooting/contacts-missing-in-brevo/)。
- 规则不运行或已自动暂停：请参阅[数据未同步](https://tajo.io/zh-cn/resources/help/troubleshooting/data-not-syncing/)。

## 下一步

- [了解数据同步](https://tajo.io/zh-cn/resources/help/getting-started/understanding-data-sync/)：同步规则如何运作
- [Shopify 权限说明](https://tajo.io/zh-cn/resources/help/integrations/shopify-permissions-explained/)：每个权限范围和每项写入
- [Shopify + Brevo](https://tajo.io/zh-cn/docs/integrations/shopify-brevo)：集成指南
- [联系团队](https://tajo.io/zh-cn/contact)完成设置