---
title: "Klaviyo 连接器"
description: "完整的 Klaviyo 集成指南，通过 Tajo 将用户档案、事件、列表、细分和营销活动数据与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/marketing/klaviyo/
markdown: https://tajo.io/zh-cn/docs/connectors/marketing/klaviyo.md
lang: zh-CN
robots: noindex
---

申请抢先体验

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

# Klaviyo 连接器

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

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

通过 Tajo 将 Klaviyo 连接到 Brevo，实现平台间营销数据的迁移或同步。同步用户档案、事件、列表、细分、流程和营销活动数据，构建统一的多渠道营销策略。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Klaviyo |
| **类别** | 营销 |
| **设置复杂度** | 中等 |
| **官方集成** | 否 |
| **同步数据** | 用户档案、事件、列表、细分、营销活动 |
| **可用技能** | 10 |
| **API 标准** | JSON:API |

## 功能

- **档案同步** - Klaviyo 和 Brevo 之间的双向客户档案同步
- **事件转发** - 将 Klaviyo 跟踪事件转发到 Brevo 触发自动化
- **列表迁移** - 将 Klaviyo 列表同步到 Brevo 联系人列表
- **细分同步** - 将 Klaviyo 细分导出为 Brevo 列表或细分
- **流程数据导出** - 提取流程绩效数据用于跨平台分析
- **营销活动同步** - 协调 Klaviyo 和 Brevo 渠道的营销活动
- **目录同步** - 在平台间镜像产品目录
- **优惠券管理** - 同步优惠券代码和使用数据

## 前提条件

开始之前，请确保您已具备：

1. 具有 API 访问权限的 Klaviyo 账户
2. 具有适当范围的私有 API 密钥
3. 您的 Klaviyo 公共 API 密钥（6 字符公司 ID）
4. 具有 API 访问权限的 Brevo 账户
5. 具有 API 凭据的 Tajo 账户

## 认证

### 私有 API 密钥

Klaviyo 使用具有范围访问的私有 API 密钥进行服务器端认证。在 `Authorization` 请求头中设置密钥：

```bash
curl https://a.klaviyo.com/api/profiles/ \
  -H "Authorization: Klaviyo-API-Key your-private-api-key" \
  -H "revision: 2026-01-15"
```

### API 密钥范围

创建私有密钥时配置范围：

| 范围 | 访问权限 | 描述 |
| --- | --- | --- |
| `profiles` | 读取/完全 | 访问联系人档案 |
| `events` | 读取/完全 | 访问跟踪事件 |
| `lists` | 读取/完全 | 访问联系人列表 |
| `segments` | 读取 | 访问细分 |
| `campaigns` | 读取 | 访问营销活动数据 |
| `metrics` | 读取 | 访问指标定义 |
| `flows` | 读取 | 访问流程配置 |
| `catalogs` | 读取 | 访问产品目录 |

### 公共 API 密钥

用于客户端跟踪，使用 6 字符公司 ID：

```bash
curl -X POST "https://a.klaviyo.com/client/events/?company_id=COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d '{"data": {...}}'
```

### OAuth（合作伙伴集成）

Klaviyo 为技术合作伙伴提供 OAuth，提供更好的安全性和更高的速率限制：

```bash
curl https://a.klaviyo.com/api/profiles/ \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
  -H "revision: 2026-01-15"
```

## 配置

### 基础设置

```yaml
connectors:
  klaviyo:
    enabled: true
    private_api_key: "your-klaviyo-private-key"
    public_api_key: "XXXXXX"
    api_revision: "2026-01-15"

    # Data sync options
    sync:
      profiles: true
      events: true
      lists: true
      segments: true
      catalogs: false

    # Brevo list assignment
    lists:
      all_contacts: 20
      subscribers: 21
      high_value: 22
```

### 档案映射

将 Klaviyo 档案属性映射到 Brevo 联系人属性：

```yaml
profile_mapping:
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone_number: SMS
  city: CITY
  region: REGION
  country: COUNTRY
  zip: ZIP
  organization: COMPANY
  title: JOB_TITLE

  # Custom properties
  lifetime_value: LTV
  total_orders: ORDER_COUNT
  last_order_date: LAST_ORDER_DATE
  preferred_channel: CHANNEL_PREF
```

### 事件映射

将 Klaviyo 指标映射到 Brevo 事件：

```yaml
event_mapping:
  "Placed Order": "order_completed"
  "Ordered Product": "product_purchased"
  "Started Checkout": "checkout_started"
  "Added to Cart": "cart_updated"
  "Viewed Product": "product_viewed"
  "Subscribed to List": "customer_subscribed"
  "Received Email": "email_received"
  "Opened Email": "email_opened"
  "Clicked Email": "email_clicked"
```

## API 端点

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/api/profiles/` | 列出档案 |
| `POST` | `/api/profiles/` | 创建档案 |
| `PATCH` | `/api/profiles/{id}/` | 更新档案 |
| `POST` | `/api/profile-merge/` | 合并重复档案 |
| `GET` | `/api/events/` | 列出事件 |
| `POST` | `/api/events/` | 创建事件 |
| `GET` | `/api/lists/` | 列出所有列表 |
| `POST` | `/api/lists/{id}/relationships/profiles/` | 将档案添加到列表 |
| `GET` | `/api/segments/` | 列出细分 |
| `GET` | `/api/campaigns/` | 列出营销活动 |
| `GET` | `/api/flows/` | 列出流程 |
| `GET` | `/api/metrics/` | 列出指标 |
| `POST` | `/api/metric-aggregates/` | 查询指标聚合 |
| `GET` | `/api/catalog-items/` | 列出目录项目 |

## 代码示例

### 初始化 Klaviyo 连接器

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

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

// Connect Klaviyo account
await tajo.connectors.connect('klaviyo', {
  privateApiKey: process.env.KLAVIYO_PRIVATE_KEY,
  publicApiKey: process.env.KLAVIYO_PUBLIC_KEY
});
```

### 将档案同步到 Brevo

```javascript
// Fetch Klaviyo profiles and sync to Brevo
const response = await fetch('https://a.klaviyo.com/api/profiles/', {
  headers: {
    'Authorization': `Klaviyo-API-Key ${PRIVATE_KEY}`,
    'revision': '2026-01-15',
    'Accept': 'application/vnd.api+json'
  }
});

const { data } = await response.json();

// Each profile follows JSON:API format
// {
//   "type": "profile",
//   "id": "01ABCDEF",
//   "attributes": {
//     "email": "jane@example.com",
//     "first_name": "Jane",
//     "last_name": "Kim",
//     "phone_number": "+15551234567",
//     "properties": { "lifetime_value": 450.00 }
//   }
// }
```

### 创建事件

```javascript
// Track an event in Klaviyo (forwarded to Brevo via Tajo)
await fetch('https://a.klaviyo.com/api/events/', {
  method: 'POST',
  headers: {
    'Authorization': `Klaviyo-API-Key ${PRIVATE_KEY}`,
    'revision': '2026-01-15',
    'Content-Type': 'application/vnd.api+json',
    'Accept': 'application/vnd.api+json'
  },
  body: JSON.stringify({
    data: {
      type: 'event',
      attributes: {
        metric: {
          data: { type: 'metric', attributes: { name: 'Placed Order' } }
        },
        profile: {
          data: { type: 'profile', attributes: { email: 'jane@example.com' } }
        },
        properties: {
          OrderId: 'ORD-1234',
          Value: 89.99,
          Items: [
            { ProductName: 'Widget Pro', Price: 89.99, Quantity: 1 }
          ]
        },
        value: 89.99
      }
    }
  })
});
```

### 查询指标聚合

```javascript
// Get aggregate metric data for reporting
await fetch('https://a.klaviyo.com/api/metric-aggregates/', {
  method: 'POST',
  headers: {
    'Authorization': `Klaviyo-API-Key ${PRIVATE_KEY}`,
    'revision': '2026-01-15',
    'Content-Type': 'application/vnd.api+json'
  },
  body: JSON.stringify({
    data: {
      type: 'metric-aggregate',
      attributes: {
        metric_id: 'METRIC_ID',
        measurements: ['count', 'sum_value'],
        interval: 'day',
        filter: ['greater-or-equal(datetime,2024-01-01)',
                 'less-than(datetime,2024-02-01)']
      }
    }
  })
});
```

## 速率限制

| 认证方式 | 突发限制 | 稳定限制 |
| --- | --- | --- |
| **私有 API 密钥** | 75 请求/秒 | 700 请求/分钟 |
| **OAuth** | 150 请求/秒 | 1,500 请求/分钟 |
| **客户端 API** | 100 请求/秒 | 无 |
| **批量操作** | 10 请求/秒 | 100 请求/分钟 |

需要 API 修订版本

所有 Klaviyo API 请求都需要将 `revision` 请求头设置为有效的 API 版本日期（例如 `2026-01-15`）。没有此请求头的请求将被拒绝。

## 故障排除

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| `400 Bad Request` | API 密钥无效或缺失 | 验证私有 API 密钥是否正确 |
| `403 Forbidden` | 范围不足 | 检查 API 密钥范围是否与所需权限匹配 |
| 缺少 `revision` 请求头 | 未设置请求头 | 在所有请求中添加 `revision: 2026-01-15` |
| 找不到档案 | 标识符错误 | 查找时使用 Klaviyo 档案 ID，而非邮箱 |
| 事件未同步 | 指标名称错误 | 与 Klaviyo 中定义的指标名称完全匹配 |
| `429 Too Many Requests` | 超出速率限制 | 实施指数退避，考虑使用 OAuth 获得更高限制 |
| JSON:API 格式错误 | 内容类型错误 | Content-Type 和 Accept 请求头使用 `application/vnd.api+json` |

## 最佳实践

1. **使用 JSON:API 格式** - 所有请求和响应负载遵循 JSON:API 规范
2. **设置修订版本请求头** - 始终包含最新 API 版本日期的 `revision` 请求头
3. **使用稀疏字段集** - 使用 `?fields[profile]=email,first_name` 只请求所需字段，减少负载大小
4. **利用关联关系** - 使用 JSON:API `include` 参数在单次请求中获取相关资源
5. **使用游标分页** - 使用 `page[cursor]` 参数浏览大型结果集
6. **实施批量操作** - 使用批量端点进行批量档案导入和事件创建
7. **使用 OAuth 获得更高限制** - OAuth 认证提供比私有密钥高 2 倍的速率限制

## 安全

- **私有 API 密钥范围** - 每种资源类型的细粒度读取/完全访问控制
- **OAuth 支持** - 合作伙伴集成的安全基于令牌的认证
- **公共密钥隔离** - 客户端密钥仅限于创建操作
- **TLS 1.2+** - 所有 API 通信在传输中加密
- **SOC 2 Type II** - Klaviyo 通过 SOC 2 Type II 认证
- **GDPR 合规** - 数据隐私 API 用于档案删除请求

## 相关资源

- [Brevo 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/brevo)
- [Google Ads 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/google-ads)
- [Meta Ads 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/meta-ads)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)