---
title: "Shopify 连接器"
description: "完整的 Shopify 集成指南,实现客户、订单、产品和购物车事件与 Brevo 的同步。"
url: https://tajo.io/zh-cn/docs/connectors/ecommerce/shopify/
markdown: https://tajo.io/zh-cn/docs/connectors/ecommerce/shopify.md
lang: zh-CN
robots: noindex
---

申请抢先体验

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

# Shopify 连接器

连接器状态: 开发中 正在构建，尚未验证。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

将你的 Shopify 店铺连接到 Brevo,实现完整的客户数据同步、弃单召回和自动化营销 campaign。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Shopify |
| **类别** | 电商 |
| **部署复杂度** | 简单 |
| **官方集成** | 否 |
| **同步数据** | 客户、订单、产品、购物车、事件 |
| **可用 Skill** | 12 |

## 功能特性

- **实时客户同步** - 客户数据即时同步到 Brevo 联系人
- **订单追踪** - 订单事件用于购后流程
- **产品目录同步** - 产品可用于推荐
- **弃单追踪** - 追踪并召回被放弃的购物车
- **浏览行为** - 追踪页面浏览和产品兴趣
- **多店铺支持** - 连接多个 Shopify 店铺

## 先决条件

开始前,请确认你具备:

1. 拥有 admin 权限的 Shopify 店铺
2. 具备 API 访问权限的 Brevo 账户
3. Tajo 账户

## 安装

### 方式 1:Shopify App Store(推荐)

1. 访问 [Shopify App Store 中的 Tajo 应用](https://apps.shopify.com/tajo)
2. 点击 “Add app”
3. 授予所请求的权限
4. 连接你的 Brevo 账户

### 方式 2:手动安装

#### 第 1 步:创建 Shopify 应用

1. 进入 Shopify 后台 → Settings → Apps and sales channels
2. 点击 “Develop apps” → “Create an app”
3. 将其命名为 “Tajo Integration”

#### 第 2 步:配置 API 权限范围

启用以下 scope:

```
read_customers
write_customers
read_orders
read_products
read_checkouts
write_script_tags
```

#### 第 3 步:安装应用

```bash
# Using Tajo CLI
tajo connectors install shopify \
  --shop-url your-store.myshopify.com \
  --api-key $SHOPIFY_API_KEY \
  --api-secret $SHOPIFY_API_SECRET
```

#### 第 4 步:配置 Webhook

Tajo 会自动注册以下 webhook:

| Webhook | 用途 |
| --- | --- |
| `customers/create` | 新客户同步 |
| `customers/update` | 客户数据变更 |
| `customers/delete` | 删除客户 |
| `orders/create` | 下单事件 |
| `orders/updated` | 订单状态变更 |
| `checkouts/create` | 创建购物车 |
| `checkouts/update` | 购物车更新 |

## 配置

### 基础设置

```yaml
connectors:
  shopify:
    enabled: true
    shop_url: "your-store.myshopify.com"
    api_version: "2024-01"

    # Data sync options
    sync:
      customers: true
      orders: true
      products: true
      carts: true
      inventory: false  # Optional

    # List assignment
    lists:
      all_customers: 5
      buyers: 6
      abandoned_cart: 7
```

### 字段映射

将 Shopify 字段映射到 Brevo 联系人属性:

#### 默认映射

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | 客户邮箱(唯一标识) |
| `first_name` optional | string | 映射到 FIRSTNAME 属性 |
| `last_name` optional | string | 映射到 LASTNAME 属性 |
| `phone` optional | string | 映射到 SMS 属性,用于 WhatsApp/SMS |
| `accepts_marketing` optional | boolean | 控制订阅状态 |
| `orders_count` optional | integer | 订单总数 |
| `total_spent` optional | number | 客户终身价值 |
| `tags` optional | array | 来自 Shopify 的客户标签 |

#### 自定义属性映射

```yaml
field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone: SMS

  # E-commerce metrics
  orders_count: ORDER_COUNT
  total_spent: TOTAL_SPENT
  last_order_date: LAST_ORDER_DATE

  # Custom fields
  customer_type: CUSTOMER_TYPE
  preferred_language: LANGUAGE
  loyalty_tier: VIP_TIER

  # Computed fields
  average_order_value: AOV
  days_since_last_order: RECENCY
```

### 产品同步

同步产品用于邮件推荐:

```yaml
sync:
  products:
    enabled: true
    include_variants: true
    include_images: true
    categories_as_tags: true

    # Filter products
    filter:
      status: active
      exclude_tags: ["hidden", "wholesale-only"]
```

### 库存追踪

启用库存水位同步:

```yaml
sync:
  inventory:
    enabled: true
    low_stock_threshold: 10
    out_of_stock_events: true
```

## 事件

### 客户事件

| 事件 | 触发条件 | 适用场景 |
| --- | --- | --- |
| `customer_created` | 新客户注册 | 欢迎系列 |
| `customer_updated` | 资料变更 | 数据同步 |
| `customer_tags_added` | 标签被分配 | 分群更新 |

### 订单事件

| 事件 | 触发条件 | 适用场景 |
| --- | --- | --- |
| `order_placed` | 完成结算 | 订单确认 |
| `order_fulfilled` | 订单发货 | 发货通知 |
| `order_cancelled` | 订单取消 | 取消邮件 |
| `order_refunded` | 处理退款 | 退款确认 |

### 购物车事件

| 事件 | 触发条件 | 适用场景 |
| --- | --- | --- |
| `cart_created` | 商品加入购物车 | 浏览追踪 |
| `cart_updated` | 购物车变更 | 购物车金额追踪 |
| `cart_abandoned` | 30 分钟内未结算 | 召回邮件 |

## 启用的 Skill

Shopify 连接器可启用以下 skill:

| Skill | 说明 |
| --- | --- |
| [客户同步](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync) | 实时客户同步 |
| 订单事件 | 订单生命周期追踪 |
| [弃单召回](https://tajo.io/zh-cn/docs/skills/email-marketing/abandoned-cart) | 购物车召回邮件 |
| 欢迎系列 | 新客户引导 |
| 购后跟进 | 订单后续跟进 |
| 赢回流失 | 重新激活沉默客户 |
| 浏览召回 | 产品兴趣跟进 |
| 补货提醒 | 再购买提醒 |

## 代码示例

### 初始化连接器

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Shopify store
await tajo.connectors.connect('shopify', {
  shopUrl: 'your-store.myshopify.com',
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecret: process.env.SHOPIFY_API_SECRET
});
```

### 运行初始同步

```javascript
// Full historical sync
await tajo.connectors.sync('shopify', {
  type: 'full',
  resources: ['customers', 'orders', 'products'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('shopify');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   customersCount: 15420,
//   ordersCount: 8234,
//   productsCount: 342
// }
```

### 追踪购物车事件

将 Tajo 脚本添加到你的 Shopify 主题中:

```liquid
<!-- Add to theme.liquid before </head> -->
{% if customer %}
<script>
  window.tajoConfig = {
    customerId: "{{ customer.id }}",
    customerEmail: "{{ customer.email }}",
    customerName: "{{ customer.first_name }}"
  };
</script>
{% endif %}
<script src="https://cdn.example.com/shopify.js"></script>
```

Caution

上面的 `example.com` 地址是占位值，在 Tajo 端点可用之前仅作示例。

### 自定义 Webhook 处理器

```javascript
// Handle Shopify webhooks manually
app.post('/webhooks/shopify', async (req, res) => {
  const hmac = req.get('X-Shopify-Hmac-SHA256');

  // Verify webhook signature
  if (!verifyShopifyWebhook(req.body, hmac)) {
    return res.status(401).send('Unauthorized');
  }

  const topic = req.get('X-Shopify-Topic');

  // Forward to Tajo
  await tajo.connectors.handleWebhook('shopify', {
    topic,
    payload: req.body
  });

  res.status(200).send('OK');
});
```

## 监控

### 仪表盘指标

在 Tajo 仪表盘中监控你的 Shopify 连接:

- **同步状态**:实时连接健康度
- **已同步客户数**:来自 Shopify 的总联系人数
- **追踪订单数**:已处理的订单事件数
- **购物车召回**:弃单召回表现
- **错误率**:同步失败尝试数

### Webhook 日志

查看 webhook 送达状态:

```bash
tajo connectors logs shopify --type webhook --last 24h
```

### 同步历史

查看历史同步记录:

```bash
tajo connectors history shopify --limit 10
```

## 故障排查

### 常见问题

API 速率限制

Shopify 的 API 速率限制为 2 请求/秒。对大批量历史导入请使用批量同步。

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 未收到 webhook | 应用权限不足 | 使用正确的 scope 重新安装应用 |
| 客户未同步 | 缺少邮箱 | Shopify 要求客户必须有邮箱 |
| 产品缺失 | 产品状态问题 | 确认产品为 “active” 状态 |
| 购物车未追踪 | 脚本未加载 | 核实 theme.liquid 中已添加脚本 |

### 调试模式

开启详细日志:

```yaml
connectors:
  shopify:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### 连接测试

```bash
tajo connectors test shopify
# ✓ API connection successful
# ✓ Webhooks registered
# ✓ Products accessible
# ✓ Customers readable
# ✓ Orders readable
```

## 最佳实践

1. **先用测试店铺** - 建议先用开发店铺
2. **在非高峰时段运行初始同步** - 大批量同步会比较慢
3. **映射自定义属性** - 不要只依赖默认映射
4. **开启购物车追踪** - 对弃单召回至关重要
5. **监控 webhook 健康** - 为送达失败设置告警
6. **使用批量导入** - 超过 10,000 条的历史数据应使用批量方式

## 安全

- **OAuth 2.0** - 基于 token 的安全认证
- **Webhook 验证** - HMAC 签名校验
- **加密存储** - API 凭证静态加密
- **最小权限** - 仅授予必要的 scope

## 相关资源

- [WooCommerce 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/woocommerce)
- [客户同步 Skill](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [弃单召回 Skill](https://tajo.io/zh-cn/docs/skills/email-marketing/abandoned-cart)
- [Brevo Contacts API](https://tajo.io/zh-cn/docs/contact-management)