Клиенты

Клиенты — основная сущность платформы: на них строятся сегменты, сценарии и рассылки. Всё остальное (заказы, визиты, корзина, цели) привязывается к клиенту по вашему идентификатору.

Клиенты — единственная сущность, которая привязывается к конкретному коннектору. Платформа запоминает, каким ключом пришла запись, и сопоставление полей для клиентов настраивается отдельно для каждого коннектора. У остальных сущностей сопоставление одно на проект.

Как обрабатываются данные

Приём клиента идёт в два этапа, и это объясняет большинство неожиданных ответов:

Сырые данные. Платформа сохраняет присланный объект целиком, как есть, со всеми вашими названиями полей.
Сопоставление. К сохранённым данным применяется карта соответствия «поле платформы ← ваше поле», которую маркетолог задал в кабинете. Только после этого создаётся или обновляется карточка клиента.

Пока сопоставление не настроено, данные принимаются и накапливаются, а в ответе приходит статус raw_saved. Это нормальное состояние на старте интеграции: сначала вы присылаете данные, маркетолог видит в кабинете список ваших полей и настраивает соответствие, после чего платформа пересобирает все накопленные карточки.

В первой отправке передайте все поля

Список ваших полей на экране сопоставления строится по последней принятой записи клиента. Если в первом клиенте не было, например, поля PERSONAL_PHONE, сопоставить его будет не с чем. Передавайте полный набор полей в каждом клиенте, а отсутствующие значения — пустой строкой "", а не пропускайте ключ.

Отправка клиентов

POST /users/sync HTTP/1.1
Host: api.octopuscdp.ru
Authorization: Bearer oct-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
Content-Type: application/json

{
  "users": [
    {
      "ID": "1042",
      "EMAIL": "ivanov@example.ru",
      "NAME": "Иван",
      "LAST_NAME": "Иванов",
      "SECOND_NAME": "",
      "PERSONAL_PHONE": "+7 912 345-67-89",
      "PERSONAL_GENDER": "M",
      "PERSONAL_BIRTHDAY": "1988-04-17",
      "PERSONAL_CITY": "Казань",
      "DATE_REGISTER": "2024-11-03 14:22:08",
      "LAST_LOGIN": "2026-09-15 09:41:00",
      "LOYALTY_LEVEL": ""
    }
  ]
}

Поле	Обязательно	Описание
`users`	да	Непустой массив клиентов. При пустом — ошибка, `"code": 400`
`ID`	да	Ваш идентификатор клиента. Без него запись не принимается
Ключевое поле	да, для создания	Поле, по которому платформа ищет дубликаты, по умолчанию `EMAIL`. Без значения новый клиент не создастся, существующий обновится. Подробнее — ниже
Остальные поля	нет	Произвольный состав: что есть в вашей системе, включая собственные поля вроде `LOYALTY_LEVEL` или `MANAGER_NAME`

Требования и особенности:

регистр имён полей не важен: EMAIL, Email и email платформа считает одним и тем же полем. Главное — писать одинаково во всех записях;
за один запрос отправляйте не больше 50 клиентов — на таких пачках работает готовый коннектор;
даты передавайте строкой в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС или ГГГГ-ММ-ДД;
телефон можно присылать в любом виде, платформа приводит его к единому формату сама.

Ответ

{
  "success": true,
  "code": 200,
  "data": {
    "results": [
      { "xml_id": "1042", "status": "updated", "user_id": 317 }
    ]
  }
}

Значение `status`	Что означает
`created`	Клиент создан, в `user_id` — его номер в CDP
`created_and_merged_as_master`	Клиент создан и стал основной карточкой для найденных дубликатов. Номера подчинённых карточек — в `linked_slaves`
`created_and_merged_as_slave`	Клиент создан и привязан к уже существующей основной карточке
`updated`	Клиент найден по вашему `ID` и обновлён
`raw_saved`	Данные сохранены, но карточка не собрана. Причина в `message`: не настроено сопоставление полей либо не сопоставлено ключевое поле
`error`	Клиент не принят. Частые причины: не указан `ID`, пустое значение ключевого поля

Ключевое поле

У проекта есть ключевое поле — по нему платформа ищет дубликаты и без него не может создать карточку. По умолчанию это EMAIL.

Правила такие:

ключевое поле обязательно должно быть сопоставлено, иначе новые клиенты не создаются (raw_saved с текстом «Требуется настройка маппинга»);
если поле сопоставлено, но значение в конкретном клиенте пустое, этот клиент не создастся (error);
на обновление уже существующего клиента это не влияет — он находится по вашему ID и обновляется, даже если ключевое поле пустое.

Если у части клиентов нет e-mail

Ключевое поле проекта можно сменить, например на телефон: «Настройки» → «Общие», настройка «Поле уникальности клиента». Сделайте это до начала выгрузки: смена ключа после загрузки базы перестраивает дедупликацию.

Объединение дубликатов

При создании клиента платформа сама проверяет, нет ли у него дубликатов:

точное совпадение по ключевому полю — карточки связываются сразу;
вероятное совпадение — если точного нет, работает скоринг по совокупности признаков (имя, телефон, город и другие).

Связанные карточки объединяются в одну «мастер-карточку», при этом каждая исходная запись остаётся привязанной к своему коннектору. Ваш ID не меняется, данные клиента передаются по нему как раньше. В ответе на создание такой клиент получает статус created_and_merged_as_master или created_and_merged_as_slave.

В методах чтения подчинённые карточки по умолчанию скрыты — видна только основная. Чтобы найти по вашему ID клиента с подчинённой карточкой, добавьте к запросу include_slaves=true.

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

Отправлять одного и того же клиента повторно безопасно и правильно — это штатный способ обновления.

Платформа сравнивает присланные значения с тем, что вы передавали в прошлый раз, и обновляет только те поля, которые действительно изменились на вашей стороне. Поэтому:

присылайте полный объект клиента, а не только изменённые поля — это проще и не приводит к лишним записям в журнале изменений;
правки, которые маркетолог сделал в карточке руками, не затираются при пересборке карточек после изменения сопоставления;

Что дальше

Передать заказы клиентов — «Заказы».
Связать визиты с клиентом — «Визиты и корзина».

Как обрабатываются данные​

Отправка клиентов​

Ответ​

Ключевое поле​

Объединение дубликатов​

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

Что дальше​