客户同步

自动将客户数据从您的电商平台同步到 Brevo 联系人。此 Skill 确保您的 Brevo 联系人列表始终反映当前的客户状态。

概览

属性	值
分类	数据同步
状态	稳定版
版本	2.1
触发器	`customer_created`、`customer_updated`、`customer_deleted`
操作	创建联系人、更新联系人、删除联系人

工作原理

graph LR
    A[E-commerce Platform] -->|Customer Event| B[Customer Sync Skill]
    B -->|Map Data| C[Field Mapping]
    C -->|API Call| D[Brevo Contacts API]
    D -->|Success| E[Contact Updated]
    D -->|Error| F[Retry Queue]

事件检测：监听来自您平台的客户生命周期事件
数据映射：将平台字段映射到 Brevo 联系人属性
API 同步：通过 Brevo API 创建、更新或删除联系人
错误处理：使用指数退避策略重试失败的操作

配置

基础设置

skills:
  customer-sync:
    enabled: true
    source: shopify  # 或 woocommerce、magento、custom

    # 将平台字段映射到 Brevo 属性
    field_mapping:
      email: email
      firstName: FIRSTNAME
      lastName: LASTNAME
      phone: SMS

    # 同步选项
    options:
      sync_mode: realtime  # 或 batch
      delete_behavior: soft  # 或 hard
      list_id: 5  # 添加到此列表

字段映射

将您平台的客户字段映射到 Brevo 联系人属性：

默认字段映射

Parameter	Type	Description
`email` required	string	客户邮箱地址。在 Brevo 中用作唯一标识符。
`firstName` optional	string	客户名字。映射到 FIRSTNAME 属性。 Default: `FIRSTNAME`
`lastName` optional	string	客户姓氏。映射到 LASTNAME 属性。 Default: `LASTNAME`
`phone` optional	string	E.164 格式的手机号码。映射到 SMS 属性，用于 WhatsApp/SMS。 Default: `SMS`
`acceptsMarketing` optional	boolean	营销订阅状态。控制邮件订阅状态。 Default: `true`

自定义属性

为电商数据添加自定义属性映射：

field_mapping:
  # 标准字段
  email: email
  firstName: FIRSTNAME

  # 自定义电商属性
  totalOrders: TOTAL_ORDERS
  totalSpent: TOTAL_SPENT
  lastOrderDate: LAST_ORDER_DATE
  customerTier: CUSTOMER_TIER
  tags: TAGS

Tip

请先创建属性：自定义属性必须先在 Brevo 中创建，才能进行同步。请使用 Brevo 仪表板或 API 创建它们。

触发器

customer_created

当您的平台创建新客户时触发。

{
  "event": "customer_created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+1234567890",
    "acceptsMarketing": true,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

customer_updated

当客户信息被修改时触发。

{
  "event": "customer_updated",
  "timestamp": "2024-01-15T14:45:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "changes": {
      "phone": {
        "old": null,
        "new": "+1234567890"
      }
    }
  }
}

customer_deleted

当客户从您的平台删除时触发。

{
  "event": "customer_deleted",
  "timestamp": "2024-01-15T16:00:00Z",
  "data": {
    "id": "cust_12345",
    "email": "[email protected]",
    "deletedAt": "2024-01-15T16:00:00Z"
  }
}

操作

创建联系人

当客户被创建时，在 Brevo 中创建新联系人。

在您的 Brevo 账户中创建新联系人

Query Parameters

Parameter	Description
email string required	联系人邮箱地址
attributes object optional	联系人属性
listIds array optional	要添加联系人的列表 ID
updateEnabled boolean optional	若联系人已存在则更新 Default: `false`

Responses

201 联系人创建成功

400 请求参数无效

409 联系人已存在

更新联系人

当客户数据变更时，更新现有联系人。

更新现有联系人的属性

Path Parameters

Parameter	Description
identifier string required	邮箱或联系人 ID

Query Parameters

Parameter	Description
attributes object optional	要更新的属性
listIds array optional	要添加联系人的列表
unlinkListIds array optional	要从中移除联系人的列表

Responses

204 联系人更新成功

400 请求参数无效

404 联系人不存在

删除联系人

当客户被删除时，移除对应联系人。

从 Brevo 中永久删除联系人

Path Parameters

Parameter	Description
identifier string required	邮箱或联系人 ID

Responses

204 联系人删除成功

404 联系人不存在

代码示例

JavaScript (Node.js)

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

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

// 启用客户同步 Skill
await tajo.skills.enable('customer-sync', {
  source: 'shopify',
  fieldMapping: {
    email: 'email',
    firstName: 'FIRSTNAME',
    lastName: 'LASTNAME',
    totalOrders: 'TOTAL_ORDERS',
    totalSpent: 'TOTAL_SPENT'
  },
  options: {
    syncMode: 'realtime',
    listId: 5
  }
});

// 手动触发同步
await tajo.skills.trigger('customer-sync', {
  event: 'customer_created',
  data: {
    email: '[email protected]',
    firstName: 'Jane',
    lastName: 'Smith'
  }
});

Python

from tajo import TajoClient

tajo = TajoClient(
    api_key=os.environ['TAJO_API_KEY'],
    brevo_api_key=os.environ['BREVO_API_KEY']
)

# 启用客户同步 Skill
tajo.skills.enable('customer-sync', {
    'source': 'woocommerce',
    'field_mapping': {
        'email': 'email',
        'first_name': 'FIRSTNAME',
        'last_name': 'LASTNAME',
        'total_orders': 'TOTAL_ORDERS'
    },
    'options': {
        'sync_mode': 'realtime',
        'list_id': 5
    }
})

# 手动触发同步
tajo.skills.trigger('customer-sync', {
    'event': 'customer_updated',
    'data': {
        'email': '[email protected]',
        'total_orders': 10,
        'total_spent': 1250.00
    }
})

监控

同步状态仪表板

在 Tajo 仪表板中监控同步性能：

同步成功率：成功同步的百分比
平均延迟：从事件到 Brevo 更新的时间
错误率：同步失败次数
队列深度：待处理的同步操作数量

Webhook 通知

接收同步事件通知：

notifications:
  webhook_url: https://your-app.com/webhooks/tajo
  events:
    - sync_completed
    - sync_failed
    - batch_completed

故障排查

常见问题

联系人已存在 (409)

在配置中启用 updateEnabled: true，将对现有联系人进行更新而非报错。

错误	原因	解决方案
`Contact already exists`	该邮箱的联系人已存在	启用 `updateEnabled: true`
`Invalid attribute`	属性在 Brevo 中不存在	先在 Brevo 中创建该属性
`Rate limit exceeded`	API 请求过多	使用批量同步模式
`Invalid email format`	邮箱地址格式错误	同步前验证邮箱格式

调试模式

启用调试日志以进行故障排查：

skills:
  customer-sync:
    debug: true
    log_level: verbose

后续步骤

为您的平台配置字段映射
在 Brevo 中设置自定义属性
启用实时同步以获得即时更新

客户同步

客户同步

概览

工作原理

配置

基础设置

字段映射

默认字段映射

自定义属性

触发器

customer_created

customer_updated

customer_deleted

操作

创建联系人

Query Parameters

Responses

更新联系人

Path Parameters

Query Parameters

Responses

删除联系人

Path Parameters

Responses

代码示例

JavaScript (Node.js)

Python

监控

同步状态仪表板

Webhook 通知

故障排查

常见问题

调试模式

相关 Skills

后续步骤

Thanks — you're subscribed.

客户同步

客户同步

概览

工作原理

配置

基础设置

字段映射

默认字段映射

自定义属性

触发器

customer_created

customer_updated

customer_deleted

操作

创建联系人

Query Parameters

Responses

更新联系人

Path Parameters

Query Parameters

Responses

删除联系人

Path Parameters

Responses

代码示例

JavaScript (Node.js)

Python

监控

同步状态仪表板

Webhook 通知

故障排查

常见问题

调试模式

相关 Skills

后续步骤

Subscribe to updates

Thanks — you're subscribed.