Получение данных

Ключ коннектора открывает не только запись, но и чтение: из Октопуса можно забрать карточки клиентов, состав сегментов, достижения целей и сводную аналитику. Так собранный маркетологом сегмент попадает в вашу CRM, учётную систему или BI.

Все методы здесь — GET, кроме запуска экспорта сегмента. Адрес, авторизация и формат ответа — как у остальных методов, см. введение.

GET /api/users?limit=50 HTTP/1.1
Host: api.octopuscdp.ru
Authorization: Bearer oct-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

Параметры-массивы

Параметры filter, order и select у клиентов передаются в строке запроса в виде массива: filter[SEGMENT_ID]=12, order[DATE_REGISTER]=DESC, select[]=ID&select[]=EMAIL.

Два идентификатора клиента

У клиента два идентификатора, и в методах чтения их важно не путать:

Идентификатор	Откуда	Где используется
`XML_ID`	Ваш `ID`, который вы передали в `/users/sync`	Во всех методах передачи данных
`ID`	Номер карточки в CDP. Приходит в ответе `/users/sync` в поле `user_id`	В методах чтения: адрес `/api/users/{id}`, состав сегмента `USERS`, `USER_ID` в достижениях целей

Клиент по вашему идентификатору ищется фильтром: GET /api/users?filter[XML_ID]=1042&include_slaves=true&select[]=ID&select[]=XML_ID. Запрашивайте XML_ID в select — по нему полученные карточки сопоставляются с вашими записями.

Кого список не показывает

По умолчанию в выдаче нет двух групп клиентов:

подчинённых карточек — если карточка объединена с дубликатом, показывается только основная. Чтобы получить и подчинённые, добавьте include_slaves=true;
клиентов в стоп-листе — их количество приходит в blocked_total, а при фильтре по сегменту скрываются и клиенты, вручную исключённые из этого сегмента.

Клиенты

Список клиентов

GET /api/users?limit=50&offset=0&filter[SEGMENT_ID]=12&select[]=ID&select[]=XML_ID&select[]=EMAIL&select[]=NAME&select[]=SEGMENTS

Параметр	Обязательно	Описание
`limit`	нет	Сколько записей вернуть. По умолчанию `50`
`offset`	нет	Смещение для постраничной выборки. По умолчанию `0`
`select`	нет	Какие поля вернуть. По умолчанию `ID`, `LOGIN`, `NAME`, `LAST_NAME`, `EMAIL`. `` — все стандартные и дополнительные поля (`UF_`)
`filter`	нет	Условия отбора по полям карточки. Перед именем поля можно ставить операторы сравнения: `=`, `!`, `<`, `>`, `%` (частичное совпадение)
`search`	нет	Поиск по имени, телефону, e-mail, логину и названию сегментов, без учёта регистра
`order`	нет	Сортировка. По умолчанию — сначала новые: `order[DATE_REGISTER]=DESC`
`include_slaves`	нет	`true` — показывать и подчинённые карточки объединённых клиентов. По умолчанию они скрыты

Полезные фильтры:

Фильтр	Что отбирает
`filter[SEGMENT_ID]=12`	Клиентов сегмента с номером `12`
`filter[XML_ID]=1042`	Клиента по вашему идентификатору
`filter[EMAIL]=ivanov`	По e-mail, частичное совпадение
`filter[PHONE]=9123456789`	По телефону
`filter[>=DATE_REGISTER]=2026-09-01`	Зарегистрированных начиная с даты

Вычисляемые поля, которые можно запросить в select:

Поле	Что возвращает
`SEGMENTS`	Сегменты, в которых состоит клиент: номер, название, цвет
`AGE`	Возраст по дате рождения
`DAYS_UNTIL_BIRTHDAY`	Сколько дней до ближайшего дня рождения
`LAST_ACTIVITY_DATETIME`	Время последнего визита на сайт
`SESSID`, `IP_ADDRESS`, `USER_AGENT`	Данные последнего визита

{
  "success": true,
  "data": {
    "items": [
      {
        "ID": "317",
        "XML_ID": "1042",
        "EMAIL": "ivanov@example.ru",
        "NAME": "Иван",
        "IN_STOP_LIST": false,
        "EXCLUDED_FROM_SEGMENT": false,
        "SEGMENTS": [
          { "id": 12, "name": "Покупали куртки", "color": "#3B82F6" }
        ]
      }
    ],
    "count": 1,
    "total": 1,
    "blocked_total": 0
  }
}

Поле ответа	Описание
`items`	Карточки клиентов с запрошенными полями
`count`	Сколько записей в этом ответе
`total`	Сколько всего клиентов подходит под фильтр, без учёта стоп-листа
`blocked_total`	Сколько подходящих клиентов в стоп-листе — в `items` их нет
`IN_STOP_LIST`, `EXCLUDED_FROM_SEGMENT`	Служебные флаги глобального стоп-листа и исключения из сегмента. Такие клиенты в выдачу не попадают, поэтому в `items` флаги всегда `false`

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

выбирайте постранично: увеличивайте offset на limit, пока не получите все total записей;
даты в ответе приходят в формате ISO 8601: 2026-09-15T09:41:00+03:00;
запрашивайте в select только нужные поля — ответ получится быстрее и меньше.

Один клиент

GET /api/users/317

Возвращает карточку клиента по его номеру в CDP (ID), не по вашему идентификатору. Параметр select — как у списка; по умолчанию возвращаются все поля карточки.

HTTP-код	Причина
`400`	Некорректный номер клиента
`404`	Клиент не найден

Сегменты

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

GET /api/segments?select=ID,NAME,SEGMENT_TYPE,USER_COUNT&active=Y

Параметр	Обязательно	Описание
`select`	нет	Поля через запятую. По умолчанию все. `USER_COUNT` — число клиентов в сегменте, `USERS` — массив их номеров в CDP
`active`	нет	`Y` — только активные сегменты, `N` — только неактивные
`search`	нет	Поиск по названию
`filter`	нет	Отбор по полям сегмента, например `filter[IS_ARCHIVED]=N`
`order`	нет	Сортировка, например `order[NAME]=ASC`. Можно сортировать и по `USER_COUNT`
`limit`, `offset`	нет	Постраничная выборка. По умолчанию `50` и `0`

{
  "success": true,
  "data": {
    "items": [
      { "ID": "12", "NAME": "Покупали куртки", "SEGMENT_TYPE": "online", "USER_COUNT": 150 }
    ],
    "count": 1,
    "total": 10
  }
}

Поле	Описание
`ID`	Номер сегмента — его передают в `filter[SEGMENT_ID]` при выборке клиентов
`NAME`, `DESCRIPTION`	Название и описание
`ACTIVE`	Активен ли сегмент: `Y`/`N`
`SEGMENT_TYPE`	`online` — пересчитывается сам, `static` — фиксированный список, `recalculated` — пересчитывается по расписанию
`LAST_RECALCULATION_DATE`	Когда сегмент пересчитывался последний раз
`IS_ARCHIVED`, `IS_TEST`	Сегмент в архиве; тестовый сегмент для проверки рассылок
`USER_COUNT`, `USERS`	Число клиентов и их номера в CDP — только если запрошены в `select`

Один сегмент

GET /api/segments/12?select=ID,NAME,USER_COUNT,USERS

Возвращает сегмент с запрошенными полями. Ошибки: 400 — не указан номер, 404 — сегмент не найден.

Как забрать клиентов сегмента

USERS возвращает только номера карточек. Если нужны контакты и поля клиентов, выбирайте их через список клиентов с filter[SEGMENT_ID] — так вы сразу получите нужные поля, включая XML_ID.

Экспорт сегмента в файл

Если нужен файл, а не JSON, — например, для ручной загрузки в другую систему, — сформируйте экспорт и скачайте его.

1. Сформируйте файл:

POST /api/segments/12/export

{ "format": "csv" }

Поле	Обязательно	Описание
`format`	нет	`xlsx` или `csv`. По умолчанию `xlsx`

{
  "success": true,
  "message": "Экспорт завершён",
  "data": {
    "segment_id": 12,
    "segment_name": "Покупали куртки",
    "format": "csv",
    "file_name": "segment_12_1789123456.csv",
    "total_users": 150
  }
}

2. Скачайте файл:

GET /api/segments/exportDownload/?id=12

Ответ — сам файл, а не JSON. Отдаётся последний сформированный файл этого сегмента.

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

экспорт одного сегмента можно запускать не чаще раза в 60 секунд;
сначала дождитесь ответа на запуск экспорта, затем скачивайте — иначе получите предыдущий файл.

Достижения целей

GET /api/goals/12/results?date_from=2026-09-01 00:00:00&date_to=2026-09-30 23:59:59&limit=100

Возвращает все достижения цели с номером 12: кто, когда и с какими данными её достиг. Номер цели маркетолог берёт в кабинете, в разделе целей.

Параметр	Обязательно	Описание
`date_from`, `date_to`	нет	Период в формате `ГГГГ-ММ-ДД ЧЧ:ММ:СС`
`user_id`	нет	Только достижения клиента с этим номером в CDP
`session_id`	нет	Только достижения в этой сессии
`limit`, `offset`	нет	Постраничная выборка. Если `limit` не передан, возвращаются все достижения
`order`	нет	Сортировка. По умолчанию — сначала новые: `order[DATE_HIT]=DESC`

{
  "success": true,
  "data": {
    "items": [
      {
        "ID": "1001",
        "GOAL_ID": "12",
        "USER_ID": 317,
        "SESSION_ID": "a1b2c3d4e5f60718",
        "DATE_HIT": "2026-09-18T10:20:00+03:00",
        "ADDITIONAL_DATA": { "form": "callback" }
      }
    ],
    "count": 1,
    "total": 528
  }
}

USER_ID — номер клиента в CDP; может быть пустым, если посетитель не опознан. ADDITIONAL_DATA — то, что вы передали в additional_data при достижении цели.

Ошибки: 400 — не указан номер цели, 404 — цель не найдена.

Выгружайте с ограничением

Без limit метод отдаёт все достижения разом. Для частых целей задавайте период и limit, иначе ответ будет большим.

Аналитика

Сводные показатели проекта за период — те же, что на дашборде кабинета.

GET /api/analytics?period=month&date=2026-09

Параметр	Обязательно	Описание
`period`	да	`day` — день, `month` — месяц, `range` — произвольный период
`date`	для `day` и `month`	День `ГГГГ-ММ-ДД` или месяц `ГГГГ-ММ`
`date_from`, `date_to`	для `range`	Начало и конец периода, `ГГГГ-ММ-ДД`

При неверном period или без нужных дат — ошибка 400.

Ответ состоит из блоков:

Блок	Что внутри
`kpi`	Выручка (`revenue`), средний чек, конверсия в покупку, брошенные корзины прямо сейчас, доли оплаченных и отменённых заказов
`clients`	Новые и повторные покупатели, конверсия в первый заказ, доля повторных покупок
`activity`	Уникальные посетители по часам (для `day`) или по дням
`devices`	Посетители по типу устройства: `desktop`, `mobile`, `tablet`
`marketing`	Рассылки по каналам: отправлено, доставлено, прочитано, клики, конверсия, заказы и выручка. Внутри канала — разбивка по сценариям и их шагам

{
  "success": true,
  "code": 200,
  "data": {
    "kpi": {
      "revenue": { "value": "37 439", "delta": null },
      "average_check": { "value": "6 239", "delta": null },
      "conversion": { "value": 26, "delta": null }
    },
    "clients": {
      "new": { "value": 4, "delta": null },
      "returning": { "value": 3, "delta": null }
    }
  }
}

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

каждая метрика — объект { "value": ..., "delta": ... }. delta — изменение в процентах к тому же периоду прошлого года, null, если данных за прошлый год нет;
денежные значения приходят строкой с пробелами между разрядами: "37 439". Перед расчётами уберите пробелы и приведите к числу;
проценты и счётчики приходят целыми числами;
заказы привязываются к рассылке по последнему касанию: для e-mail — по клику по ссылке, для SMS — по доставке. Окно атрибуции по умолчанию — 7 дней для e-mail и 3 дня для SMS;
данные за прошедшие дни берутся из кеша, за текущий день считаются в момент запроса.

Что дальше

Как передаются данные, которые потом возвращаются в этих методах, — во введении.
Как опознать клиента, перешедшего из рассылки, прямо на сайте — «Переходы по ссылкам из рассылок».

Два идентификатора клиента​

Клиенты​

Список клиентов​

Один клиент​

Сегменты​

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

Один сегмент​

Экспорт сегмента в файл​

Достижения целей​

Аналитика​

Что дальше​

Два идентификатора клиента

Клиенты

Список клиентов

Один клиент

Сегменты

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

Один сегмент

Экспорт сегмента в файл

Достижения целей

Аналитика

Что дальше