CDP API — Контакты, Сегменты, События

Справочник CDP API Trigly: CRUD контактов, сегментация, отслеживание событий, RFM, импорт/экспорт.

Обзор CDP

Customer Data Platform (CDP) — ядро Trigly. CDP собирает, объединяет и обогащает данные о клиентах из всех источников в единый профиль. На основе этих данных работают сегментация, кампании, AI-скоринг и предикции.

Основные сущности:

Сущность Описание Эндпоинты
Контакты (Customers) Профили клиентов с 45+ полями 14 эндпоинтов
Сегменты (Segments) Статические и динамические группы 13 эндпоинтов
События (Events) Действия пользователей в ClickHouse 5 эндпоинтов
Импорт CSV-загрузка контактов 5 эндпоинтов
RFM Recency-Frequency-Monetary анализ 4 эндпоинта
Bulk Массовые операции 5 эндпоинтов

Базовый URL: https://api.trigly.ru/api/v1/cdp

Авторизация: Authorization: Bearer <JWT> (для всех эндпоинтов, кроме SDK)

Контакты (Customers)

Список контактов

GET /api/v1/cdp/customers?page=1&per_page=20

Параметры запроса:

Параметр Тип По умолчанию Описание
page int 1 Номер страницы
per_page int 20 Записей на страницу (макс. 100)
search string — Поиск по email, имени, телефону
tags string — Фильтр по тегам (через запятую)
lifecycle_stage string — Фильтр по стадии жизненного цикла

Пример запроса:

curl "https://api.trigly.ru/api/v1/cdp/customers?page=1&per_page=10&search=ivan" \
  -H "Authorization: Bearer $TOKEN"

Пример ответа:

{
  "items": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "email": "ivan@example.com",
      "first_name": "Иван",
      "last_name": "Петров",
      "phone": "+79161234567",
      "city": "Москва",
      "country": "RU",
      "timezone": "Europe/Moscow",
      "tags": ["vip", "новый"],
      "custom_fields": {"preferred_brand": "Nike"},
      "total_revenue": 15990.0,
      "total_orders": 3,
      "lifecycle_stage": "active",
      "ai_score": 78.5,
      "rfm_segment": "champions",
      "data_quality_score": 85,
      "is_unsubscribed": false,
      "preferred_channel": "email",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-20T08:30:00Z"
    }
  ],
  "total": 1543,
  "page": 1,
  "per_page": 10,
  "pages": 155
}

Создание контакта

POST /api/v1/cdp/customers

Тело запроса:

{
  "email": "anna@example.com",
  "first_name": "Анна",
  "last_name": "Сидорова",
  "phone": "+79167654321",
  "city": "Санкт-Петербург",
  "country": "RU",
  "timezone": "Europe/Moscow",
  "language": "ru",
  "tags": ["лид", "сайт"],
  "custom_fields": {
    "registration_source": "landing_page",
    "interest": "обувь"
  },
  "source": "website",
  "utm_source": "yandex",
  "utm_medium": "cpc",
  "utm_campaign": "spring_2026"
}

Все поля, кроме email, опциональны. Email должен быть уникальным в рамках организации.

Ответ (201 Created): полный объект контакта.

Получение контакта

GET /api/v1/cdp/customers/{customer_id}

curl https://api.trigly.ru/api/v1/cdp/customers/770e8400-... \
  -H "Authorization: Bearer $TOKEN"

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

PATCH /api/v1/cdp/customers/{customer_id}

Обновляются только переданные поля (partial update):

curl -X PATCH https://api.trigly.ru/api/v1/cdp/customers/770e8400-... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "city": "Новосибирск",
    "tags": ["vip", "постоянный"],
    "custom_fields": {"shoe_size": 43}
  }'

Удаление контакта

DELETE /api/v1/cdp/customers/{customer_id}

Управление тегами

# Добавить теги
curl -X POST https://api.trigly.ru/api/v1/cdp/customers/770e8400-.../tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["vip", "реферал"]}'

# Удалить теги
curl -X DELETE https://api.trigly.ru/api/v1/cdp/customers/770e8400-.../tags \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["лид"]}'

Отписка контакта

curl -X POST https://api.trigly.ru/api/v1/cdp/customers/770e8400-.../unsubscribe \
  -H "Authorization: Bearer $TOKEN"

Устанавливает is_unsubscribed = true и unsubscribed_at = now(). Отписанные контакты автоматически исключаются из рассылок.

Профиль 360°

Получение полного профиля контакта, включая метрики, каналы и историю:

GET /api/v1/cdp/customers/{customer_id}/profile

{
  "customer": { "..." },
  "metrics": {
    "total_revenue": 45990.0,
    "total_orders": 8,
    "avg_order_value": 5748.75,
    "days_since_last_purchase": 12,
    "purchase_frequency_days": 15.3
  },
  "channels": {
    "email": true,
    "telegram": true,
    "sms": false,
    "push": true
  },
  "rfm": {
    "recency": 5,
    "frequency": 4,
    "monetary": 5,
    "score": "545",
    "segment": "champions"
  }
}

Хронология контакта

GET /api/v1/cdp/customers/{customer_id}/timeline?page=1&per_page=20

Возвращает объединённую хронологию из PostgreSQL (сообщения) и ClickHouse (события), отсортированную по времени.

Каналы контакта

GET /api/v1/cdp/customers/{customer_id}/channels

Информация о подключённых каналах: email, telegram_chat_id, whatsapp_phone, push_subscription, channel_preferences.

История изменений

GET /api/v1/cdp/customers/{customer_id}/changelog?page=1&per_page=20

Аудит-лог всех изменений профиля контакта.

Сегменты (Segments)

Типы сегментов

Тип Описание
static Фиксированный список контактов. Изменяется вручную
dynamic Автоматически пересчитывается по правилам каждые 30 минут

Список сегментов

GET /api/v1/cdp/segments?page=1&per_page=20

Параметры:

Параметр Описание
search Поиск по имени
segment_type Фильтр: static или dynamic

Создание сегмента

POST /api/v1/cdp/segments

Статический сегмент

{
  "name": "VIP-клиенты (ручной)",
  "segment_type": "static"
}

Динамический сегмент

{
  "name": "Активные покупатели Москвы",
  "segment_type": "dynamic",
  "rules": {
    "operator": "and",
    "conditions": [
      {"field": "city", "operator": "equals", "value": "Москва"},
      {"field": "total_orders", "operator": "greater_than", "value": 3},
      {"field": "is_unsubscribed", "operator": "equals", "value": false}
    ]
  }
}

Доступные операторы для правил:

Оператор Описание Поддерживаемые типы
equals Точное совпадение string, number, boolean
not_equals Не равно string, number, boolean
contains Содержит подстроку string
not_contains Не содержит string
greater_than Больше number
less_than Меньше number
greater_or_equal Больше или равно number
less_or_equal Меньше или равно number
in Входит в список array
not_in Не входит в список array
is_set Поле заполнено any
is_not_set Поле пустое any
before До даты date
after После даты date

Комбинация правил:

Правила можно объединять через and/or с вложенностью:

{
  "operator": "or",
  "conditions": [
    {
      "operator": "and",
      "conditions": [
        {"field": "city", "operator": "equals", "value": "Москва"},
        {"field": "total_revenue", "operator": "greater_than", "value": 10000}
      ]
    },
    {
      "operator": "and",
      "conditions": [
        {"field": "tags", "operator": "contains", "value": "vip"},
        {"field": "total_orders", "operator": "greater_than", "value": 5}
      ]
    }
  ]
}

Предпросмотр сегмента

Проверка правил без сохранения:

POST /api/v1/cdp/segments/preview

{
  "rules": {
    "operator": "and",
    "conditions": [
      {"field": "city", "operator": "equals", "value": "Казань"}
    ]
  }
}

Ответ: {"count": 234, "sample": [...]}

Обновление сегмента

PATCH /api/v1/cdp/segments/{segment_id}

Пересчёт динамического сегмента

POST /api/v1/cdp/segments/{segment_id}/refresh

Запускает немедленный пересчёт. Автоматический пересчёт всех динамических сегментов происходит каждые 30 минут через Celery task.

Управление контактами в статическом сегменте

# Добавить контакты
curl -X POST https://api.trigly.ru/api/v1/cdp/segments/{segment_id}/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_ids": ["id1", "id2", "id3"]}'

# Удалить контакт из сегмента
curl -X DELETE https://api.trigly.ru/api/v1/cdp/segments/{segment_id}/customers/{customer_id} \
  -H "Authorization: Bearer $TOKEN"

Аналитика сегмента

GET /api/v1/cdp/segments/{segment_id}/analytics

Возвращает метрики сегмента: размер, рост, средний чек, RFM-распределение, активность.

Пересечение сегментов

GET /api/v1/cdp/segments/overlap?segment_ids=id1,id2

Показывает количество и список контактов, входящих в оба сегмента.

События (Events)

События хранятся в ClickHouse для обеспечения высокой производительности при больших объёмах данных. TTL — 365 дней.

Отправка события (через JWT)

POST /api/v1/cdp/events

{
  "customer_id": "770e8400-...",
  "event_type": "custom",
  "event_name": "purchase",
  "properties": {
    "order_id": "ORD-12345",
    "amount": 4990,
    "currency": "RUB",
    "products": [
      {"sku": "NIKE-AM90", "name": "Nike Air Max 90", "price": 4990}
    ]
  },
  "page_url": "https://myshop.ru/checkout/success",
  "revenue": 4990.0
}

Отправка события (через SDK)

POST /api/v1/sdk/track

curl -X POST https://api.trigly.ru/api/v1/sdk/track \
  -H "X-API-Key: tgl_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "770e8400-...",
    "event_name": "add_to_cart",
    "properties": {"product": "Nike Air Max", "price": 4990}
  }'

Пакетная отправка

POST /api/v1/sdk/batch

{
  "events": [
    {"customer_id": "id1", "event_name": "page_view", "properties": {"page": "/"}},
    {"customer_id": "id1", "event_name": "page_view", "properties": {"page": "/products"}},
    {"customer_id": "id2", "event_name": "signup", "properties": {}}
  ]
}

Список событий

GET /api/v1/cdp/events?customer_id=770e8400-...&page=1&per_page=50

Статистика событий

GET /api/v1/cdp/events/stats?period=30d

Ответ:

{
  "total_events": 156432,
  "unique_customers": 8923,
  "top_events": [
    {"event_name": "page_view", "count": 98234},
    {"event_name": "purchase", "count": 3421},
    {"event_name": "add_to_cart", "count": 12567}
  ]
}

Стандартные типы событий

Тип Описание
page_view Просмотр страницы
purchase Покупка (с revenue)
add_to_cart Добавление в корзину
remove_from_cart Удаление из корзины
signup Регистрация
login Авторизация
search Поиск
custom Произвольное событие

Вы также можете определить собственные типы событий через Event Definitions API:

POST /api/v1/cdp/event-definitions

{
  "event_name": "webinar_attended",
  "display_name": "Посетил вебинар",
  "description": "Пользователь посетил вебинар",
  "properties_schema": {
    "webinar_id": "string",
    "duration_minutes": "number"
  }
}

RFM-анализ

RFM (Recency, Frequency, Monetary) — метод сегментации по покупательскому поведению. Trigly автоматически рассчитывает RFM-скоры каждую ночь в 3:00 через Celery task.

Распределение по сегментам

GET /api/v1/cdp/rfm/distribution

Ответ:

{
  "segments": [
    {"name": "champions", "count": 234, "percentage": 15.2},
    {"name": "loyal_customers", "count": 456, "percentage": 29.6},
    {"name": "at_risk", "count": 123, "percentage": 8.0},
    {"name": "hibernating", "count": 89, "percentage": 5.8},
    {"name": "lost", "count": 67, "percentage": 4.3}
  ],
  "total_scored": 1543
}

RFM-скор контакта

GET /api/v1/cdp/rfm/customer/{customer_id}

Ручной пересчёт

POST /api/v1/cdp/rfm/recalculate

Запускает полный пересчёт RFM, lifecycle, computed fields и data quality.

Импорт и экспорт

CSV-импорт

Процесс состоит из 4 шагов:

  1. Загрузка — POST /imports/upload (multipart/form-data)
  2. Предпросмотр — GET /imports/{id}/preview (маппинг полей)
  3. Запуск — POST /imports/{id}/start (дедупликация по email)
  4. Статус — GET /imports/{id}/status (прогресс)

Экспорт

# Создание задачи экспорта
curl -X POST https://api.trigly.ru/api/v1/cdp/exports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "segment_id": "SEGMENT_ID",
    "fields": ["email", "first_name", "last_name", "city", "total_revenue"]
  }'

# Проверка статуса и получение файла
curl https://api.trigly.ru/api/v1/cdp/exports/{export_id} \
  -H "Authorization: Bearer $TOKEN"

Массовые операции (Bulk)

Массовое обновление

POST /api/v1/cdp/contacts/bulk/update

{
  "customer_ids": ["id1", "id2", "id3"],
  "update": {
    "city": "Москва",
    "tags": ["оптовик"]
  }
}

Массовое удаление

POST /api/v1/cdp/contacts/bulk/delete

{
  "customer_ids": ["id1", "id2", "id3"]
}

Массовое добавление тегов

POST /api/v1/cdp/contacts/bulk/tag

{
  "customer_ids": ["id1", "id2"],
  "tags": ["акция_март", "скидка_20"]
}

Массовое удаление тегов

POST /api/v1/cdp/contacts/bulk/untag

Массовое добавление в сегмент

POST /api/v1/cdp/contacts/bulk/assign-segment

{
  "customer_ids": ["id1", "id2"],
  "segment_id": "SEGMENT_ID"
}

Дополнительные API

Объединение контактов (Merge)

Обнаружение дубликатов и слияние:

# Поиск дубликатов
curl https://api.trigly.ru/api/v1/cdp/contacts/duplicates \
  -H "Authorization: Bearer $TOKEN"

# Слияние
curl -X POST https://api.trigly.ru/api/v1/cdp/contacts/merge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"primary_id": "id1", "secondary_id": "id2"}'

Идентификаторы контакта (Identity)

Управление множественными идентификаторами (email, phone, external_id):

GET /api/v1/cdp/customers/{id}/identities
POST /api/v1/cdp/customers/{id}/identities
DELETE /api/v1/cdp/customers/{id}/identities/{identity_id}
POST /api/v1/cdp/contacts/resolve

Список подавления (Suppression)

# Добавить в список подавления
curl -X POST https://api.trigly.ru/api/v1/cdp/suppression \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "spam@example.com", "reason": "hard_bounce"}'

# Проверить
curl -X POST https://api.trigly.ru/api/v1/cdp/suppression/check \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user1@example.com", "spam@example.com"]}'

Коннекторы (CRM-интеграции)

# Доступные коннекторы
curl https://api.trigly.ru/api/v1/cdp/connectors/available \
  -H "Authorization: Bearer $TOKEN"

# Подключение
curl -X POST https://api.trigly.ru/api/v1/cdp/connectors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_type": "retailcrm",
    "credentials": {"api_url": "https://shop.retailcrm.ru", "api_key": "..."}
  }'

# Синхронизация
curl -X POST https://api.trigly.ru/api/v1/cdp/connectors/{connector_id}/sync \
  -H "Authorization: Bearer $TOKEN"

CDP-аналитика

# Тепловая карта активности
curl https://api.trigly.ru/api/v1/cdp/analytics/heatmap?period=30d \
  -H "Authorization: Bearer $TOKEN"

# Качество данных
curl https://api.trigly.ru/api/v1/cdp/analytics/data-quality \
  -H "Authorization: Bearer $TOKEN"

# Источники контактов
curl https://api.trigly.ru/api/v1/cdp/analytics/sources \
  -H "Authorization: Bearer $TOKEN"

Жизненный цикл контакта

# Распределение по стадиям
curl https://api.trigly.ru/api/v1/cdp/lifecycle/distribution \
  -H "Authorization: Bearer $TOKEN"

# Переходы между стадиями
curl https://api.trigly.ru/api/v1/cdp/lifecycle/transitions?period=30d \
  -H "Authorization: Bearer $TOKEN"

Стадии жизненного цикла: new → active → loyal → at_risk → churned. Переходы рассчитываются автоматически на основе активности.

Коды ошибок

Код Описание
400 Некорректный запрос (невалидные данные)
401 Не авторизован (невалидный/истёкший токен)
403 Запрещено (недостаточно прав)
404 Ресурс не найден
409 Конфликт (дубликат email)
429 Превышен rate limit
500 Внутренняя ошибка сервера

Формат ошибки:

{
  "detail": "Customer with email ivan@example.com already exists"
}
Назад
Аутентификация API
Далее
Campaigns API

Не нашли ответ?

Swagger UI с интерактивной документацией и поддержка в Telegram.

Swagger UIНаписать в поддержку