Передача данных через API

Коннектор «API» связывает Октопус CDP с системой, для которой нет готового модуля: CRM, ERP, самописным сайтом, мобильным приложением. Ваша система отправляет в платформу клиентов, заказы, товары и события, а обратно забирает клиентов, сегменты, достижения целей и аналитику.

Раздел для разработчиков

Здесь описаны запросы и ответы. Как создать коннектор, получить ключ и настроить сопоставление полей в кабинете — в статье «Подключение системы через API».

Что понадобится

Проект с основным коннектором 1С-Битрикс или InSales. Коннектор «API» — дополнительный и не может быть основным. Проект в режиме «Только рассылки» запросы с данными не принимает.
Коннектор «API» и его ключ. Коннектор создаётся в кабинете, у каждого коннектора свой ключ формата oct-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
Сопоставление полей для клиентов и товаров. Его настраивает маркетолог в кабинете, когда вы пришлёте первые данные.

Что вы передаёте в Октопус

Данные	Зачем	Где описано
Клиенты	База контактов, на которой строятся сегменты и рассылки	Клиенты
Разделы каталога и товары	Товарные сегменты и подстановка товаров в письма	Каталог
Заказы	Выручка, статусы, история покупок	Заказы
Визиты и корзина	Поведение посетителя, сценарии брошенной корзины	Визиты и корзина
Достижения целей	Конверсии и ключевые действия	Цели

Визиты и цели с сайта удобнее отправлять готовым JS-трекером. Большие объёмы — пакетами до 50 запросов.

Что вы получаете от Октопуса

Платформа не обращается к вашей системе сама: всё забирается вашими запросами с тем же ключом.

Данные	Как получить	Где описано
Клиенты: поля карточки, сегменты клиента, последний визит	`GET /api/users`	Клиенты
Сегменты, их состав и выгрузка в `xlsx` или `csv`	`GET /api/segments`, `POST /api/segments/{id}/export`	Сегменты
Достижения целей за период	`GET /api/goals/{id}/results`	Достижения целей
Аналитика: выручка, клиенты, активность, рассылки	`GET /api/analytics`	Аналитика
Результат по каждой переданной записи	Массив `results` в ответе на метод синхронизации	Результат по каждому элементу
Задания прислать недостающие данные: товар, дерево разделов, описание цели	Опрос `GET /client/commands`	Очередь команд
Клиент, перешедший по ссылке из рассылки	Метка `utm_oct` в адресе страницы	Переходы по ссылкам из рассылок
Проект, к которому привязан ключ	`GET /sync/check`	Проверка ключа

Базовый URL

Все запросы идут на https://api.octopuscdp.ru. Шлюз по ключу определяет ваш проект и передаёт запрос его инстансу, поэтому адрес одинаковый для всех проектов.

POST https://api.octopuscdp.ru/users/sync

Авторизация

Ключ коннектора передаётся в заголовке Authorization:

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

Альтернатива для окружений, где нельзя задать заголовок, — query-параметр ?api_key=oct-.... Заголовок предпочтительнее: ключ не попадает в логи веб-сервера.

Дополнительно можно передавать X-Client-Domain — домен системы, из которой идут данные. Он используется для диагностики и на обработку не влияет.

Ключ равен доступу к данным проекта

Ключ коннектора даёт право и записывать данные в проект, и читать их — включая контакты клиентов. Храните его на стороне сервера и не публикуйте в коде, который попадает в браузер или в мобильное приложение.

Формат запросов и ответов

Тело запроса — application/json в кодировке UTF-8.
Методы записи данных — POST, методы чтения — GET. Параметры выборки передаются в строке запроса.
Ответ всегда JSON.
Максимальный размер тела запроса — 10 МБ.

Успешный ответ:

{
  "success": true,
  "code": 200,
  "message": "Заказы обработаны",
  "data": { }
}

Поля message и data необязательны и есть не у каждого метода.

Ответ с ошибкой:

{
  "success": false,
  "error": "Не переданы данные пользователей",
  "code": 400
}

Проверяйте тело ответа, а не HTTP-код

Часть ошибок приходит с HTTP 200: например, пустой массив данных вернёт 200 и {"success": false, "code": 400, ...} в теле. Ориентируйтесь на поля success и code.

Есть и обратный случай — предупреждение: "success": true, но code отличен от 200 и заполнено поле error. Так отвечает, например, привязка сессии к клиенту, которого ещё нет. Такой ответ означает, что запрос принят, но действие не выполнено.

Результат по каждому элементу

Методы синхронизации принимают массив элементов и обрабатывают их независимо: ошибка на одном не отменяет остальные. Поэтому success: true на уровне запроса ещё не значит, что приняты все элементы — разбирайте массив results.

{
  "success": true,
  "code": 200,
  "data": {
    "results": [
      { "xml_id": "1042", "status": "updated", "user_id": 317 },
      { "xml_id": "1043", "status": "raw_saved", "message": "Данные сохранены, требуется настройка соответствия полей" },
      { "xml_id": null,   "status": "error",    "message": "Не указан ID пользователя" }
    ]
  }
}

Основные значения status:

Значение	Что означает
`created`	Элемент создан в CDP
`updated`	Элемент найден по идентификатору и обновлён
`raw_saved`	Данные приняты и сохранены, но ещё не настроено сопоставление полей — элемент появится после настройки
`created_and_merged_as_master`, `created_and_merged_as_slave`	Только у клиентов: карточка создана и сразу объединена с дубликатами — см. «Объединение дубликатов»
`error`	Элемент не принят, причина в `message`

Специфичные значения описаны в статьях по сущностям.

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

Каждая сущность в CDP опознаётся по вашему идентификатору — тому, который вы прислали в поле ID. Платформа хранит его как внешний идентификатор и при повторной отправке того же ID обновляет существующую запись, а не создаёт новую. Отдельного метода «обновить» нет: повторная отправка и есть обновление.

Требования к идентификаторам:

уникальны в пределах своего типа сущности и неизменны — по ним связываются заказы с клиентами и корзина с товарами;
передаются строкой ("1042"), число тоже принимается и приводится к строке;
в заказах поле USER_ID — это ваш идентификатор клиента, а BASKET[].PRODUCT_ID — ваш идентификатор товара.

Регистр имён полей

Регистр имён полей не важен ни в одном методе: EMAIL, Email и email — одно и то же поле. Это относится ко всему: к обёрткам вроде users и products, к полям записей, к вложенным структурам — позициям корзины ITEMS, составу заказа BASKET — и к конверту пачки /batch.

Не меняются только ключи внутри данных, которые задаёте вы сами: имена GET-параметров в QUERY_PARAMS, свойства позиций корзины и содержимое additional_data сохраняются ровно в том виде, в каком пришли. utm_source останется utm_source.

Придерживайтесь одного написания

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

Порядок первой выгрузки

Сущности связаны между собой, поэтому порядок важен:

Клиенты — POST /users/sync. Заказ без ранее переданного клиента получит статус USER_NOT_FOUND.
Разделы каталога — POST /products/syncSections. Если товар сошлётся на ещё не пришедший раздел, платформа пришлёт через очередь команд команду SYNC_SECTIONS — запрос дерева разделов.
Товары — POST /products/sync. Торговое предложение без родителя останется в очереди на достройку.
Заказы — POST /orders/sync. Товары корзины должны быть уже переданы.
Визиты, корзина, цели — по мере появления событий, в реальном времени.

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

Состояние проекта

Инстанс проекта может быть недоступен — например, во время обновления. Реакция зависит от состояния:

Ситуация	Ответ	Что делать
Проект работает	Обычный ответ метода	—
Проект обновляется	`2xx` и `{"success": true, "queued": true}`	Ничего. Запрос поставлен в очередь и применится после обновления. Считайте его доставленным
Проект недоступен по другой причине	`503` и `project_status` с текущим состоянием	Повторить позже
Ключ не передан или неизвестен	`401`	Проверить ключ
Проект в режиме «Только рассылки»	`403` «Проект „Только рассылки“ не принимает данные по API»	Подключить сайт на 1С-Битрикс или InSales, затем коннектор «API» — см. «Подключение системы через API»

Приостановленная подписка

При неоплаченной подписке кабинет переходит в режим чтения, но приём данных не останавливается: синхронизация клиентов, заказов, товаров и разделов, трекинг и очередь команд продолжают работать. Прекращать отправку не нужно.

Надёжность отправки

У платформы нет ограничения на частоту запросов, но отправка «по одному запросу на событие» в пиковые моменты упирается в сеть и таймауты. Надёжнее писать события в очередь на своей стороне и отправлять пачками через /batch с повторами при сбоях. Готовая схема такой очереди — в разделе «Как построить отправку».

Повторять имеет смысл только то, что не дошло: сетевые ошибки, таймауты, HTTP 5xx. Если пришёл ответ с "success": false и кодом 4xx в поле code — это ошибка в данных, повтор её не исправит. Такой запрос нужно разобрать и отправить заново уже исправленным.

Повторная отправка методов синхронизации (/users/sync, /products/sync, /products/syncSections, /orders/sync, /tracking/basket-sync) безопасна: они работают по принципу «создать или обновить» по вашему идентификатору. Визиты, добавления в корзину и достижения целей при повторе запишутся ещё раз — их повторяйте, только если уверены, что запрос не дошёл.

Проверка ключа

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

GET /sync/check HTTP/1.1
Host: api.octopuscdp.ru
Authorization: Bearer oct-1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

{
  "success": true,
  "message": "API-ключ успешно проверен и сохранен",
  "data": {
    "project_id": 142,
    "project_name": "Мой магазин",
    "status": "ACTIVE",
    "main_domain": "example.ru",
    "authorized_domains": ["example.ru", "shop.example.ru"]
  }
}

HTTP-код	Причина
`200`	Ключ верный
`401`	Ключ не передан, имеет неверный формат или не найден
`503`	Проект существует, но его инстанс сейчас недоступен

Справочник методов

Метод	Назначение	Обязательные поля
`GET /sync/check`	Проверка ключа	Нет
`POST /users/sync`	Клиенты	`users`, у каждого клиента — `ID`. Для создания нового клиента дополнительно нужно значение ключевого поля (по умолчанию `EMAIL`) и настроенное сопоставление
`POST /products/syncSections`	Разделы каталога	`sections`, у каждого раздела — `id` и `name`
`POST /products/sync`	Товары	`products`, у каждого товара — `ID`. Для сборки товара нужно сопоставленное название; у торгового предложения — `PARENT_ID`
`POST /products/delete`	Удаление товаров	`ids` (или `id`)
`POST /orders/sync`	Заказы	`orders`, у каждого заказа — `ID` и `USER_ID`; у позиции корзины — `PRODUCT_ID`, `NAME`, `PRICE`, `QUANTITY`
`POST /orders/delete`	Удаление заказа	`order_id`
`POST /tracking/pageview`	Визит страницы	`SESSID`, `PAGE_URL`, `DOMAIN`, `PAGE_PATH`
`POST /tracking/bind-user`	Связывание сессии с клиентом	`SESSID`, `USER_ID`
`POST /tracking/basket-add`	Добавление в корзину	`SESSID`, `XML_ID`, `PRODUCT_NAME`, `PRICE`
`POST /tracking/basket-sync`	Состояние корзины	`SESSID`, `ITEMS`; у позиции — `xml_id`, `name`, `price`, `quantity`
`POST /goals/{id}/hit`	Достижение цели	`sessid` и либо номер цели в адресе, либо `goal_code`
`GET /client/commands`	Получение команд	Нет
`POST /client/commands/confirm`	Подтверждение выполнения	`command_ids`
`POST /client/commands/errors`	Сообщение об ошибке	`errors`
`POST /batch`	Пакетная отправка	`requests`, у каждого элемента — `endpoint`
`GET /api/users`	Список клиентов	Нет
`GET /api/users/{id}`	Один клиент	Номер клиента в CDP в адресе
`GET /api/segments`	Список сегментов	Нет
`GET /api/segments/{id}`	Один сегмент	Номер сегмента в адресе
`POST /api/segments/{id}/export`	Экспорт сегмента	Номер сегмента в адресе
`GET /api/segments/exportDownload/`	Скачивание экспорта	`id`
`GET /api/goals/{id}/results`	Достижения цели	Номер цели в адресе
`GET /api/analytics`	Аналитика	`period` и даты периода

Отсутствие обязательного поля даёт ответ с "success": false и "code": 400 — либо на весь запрос, либо на отдельный элемент массива, в зависимости от метода.

Что понадобится​

Что вы передаёте в Октопус​

Что вы получаете от Октопуса​

Базовый URL​

Авторизация​

Формат запросов и ответов​

Результат по каждому элементу​

Идентификаторы​

Регистр имён полей​

Порядок первой выгрузки​

Состояние проекта​

Надёжность отправки​

Проверка ключа​

Справочник методов​