Синхронизация клиентов

Автоматически синхронизирует данные клиентов из вашей e-commerce-платформы в контакты Brevo. Этот навык гарантирует, что список контактов Brevo всегда отражает вашу актуальную клиентскую базу.

Обзор

Свойство	Значение
Категория	Синхронизация данных
Статус	Stable
Версия	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: создание, обновление или удаление контактов через API Brevo
Обработка ошибок: повтор неудачных операций с экспоненциальной задержкой

Настройка

Базовая настройка

skills:
  customer-sync:
    enabled: true
    source: shopify  # or woocommerce, magento, custom

    # Map platform fields to Brevo attributes
    field_mapping:
      email: email
      firstName: FIRSTNAME
      lastName: LASTNAME
      phone: SMS

    # Sync options
    options:
      sync_mode: realtime  # or batch
      delete_behavior: soft  # or hard
      list_id: 5  # Add to this list

Маппинг полей

Сопоставляйте поля клиента вашей платформы с атрибутами контакта Brevo:

Маппинг полей по умолчанию

Parameter	Type	Description
`email` required	string	Email-адрес клиента. Используется как уникальный идентификатор в 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	Статус согласия на маркетинг. Управляет подпиской на email-рассылки. Default: `true`

Пользовательские атрибуты

Добавляйте пользовательские атрибуты для e-commerce-данных:

field_mapping:
  # Standard fields
  email: email
  firstName: FIRSTNAME

  # Custom e-commerce attributes
  totalOrders: TOTAL_ORDERS
  totalSpent: TOTAL_SPENT
  lastOrderDate: LAST_ORDER_DATE
  customerTier: CUSTOMER_TIER
  tags: TAGS

Сначала создайте атрибуты

Пользовательские атрибуты нужно создать в 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	Email-адрес контакта
attributes object optional	Атрибуты контакта
listIds array optional	ID списков для добавления контакта
updateEnabled boolean optional	Обновить, если контакт уже существует Default: `false`

Responses

201 Контакт успешно создан

400 Неверные параметры запроса

409 Контакт уже существует

Обновление контакта

Обновляет существующий контакт при изменении данных клиента.

Обновить атрибуты существующего контакта

Path Parameters

Parameter	Description
identifier string required	Email или 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	Email или 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
});

// Enable customer sync 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
  }
});

// Manually trigger a sync
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']
)

# Enable customer sync 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
    }
})

# Manually trigger a sync
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`	Контакт с таким email уже существует	Включите `updateEnabled: true`
`Invalid attribute`	Атрибут не существует в Brevo	Сначала создайте атрибут в Brevo
`Rate limit exceeded`	Слишком много запросов к API	Используйте пакетный режим синхронизации
`Invalid email format`	Некорректный email-адрес	Проверяйте email перед синхронизацией

Режим отладки

Включите подробное логирование для диагностики:

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

Связанные навыки

События заказов, синхронизация данных заказов
Каталог товаров, синхронизация товаров
События корзины, отслеживание активности корзины

Следующие шаги

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

Синхронизация клиентов